package api import ( "context" "log/slog" "net/http" "google.golang.org/grpc/codes" "google.golang.org/grpc/status" "google.golang.org/protobuf/encoding/protojson" "connectrpc.com/connect" "github.com/grpc-ecosystem/grpc-gateway/v2/runtime" "github.com/labstack/echo/v5" "github.com/pkg/errors" "golang.org/x/sync/semaphore" "github.com/usememos/memos/core/notification" "github.com/usememos/memos/internal/linkmeta" "github.com/usememos/memos/internal/profile" "github.com/usememos/memos/internal/ratelimit" "github.com/usememos/memos/markdown" apipb "github.com/usememos/memos/proto/gen/api" "github.com/usememos/memos/server/auth" "github.com/usememos/memos/store" ) // MaxAPIRequestBytes caps the size of a request body accepted by the API. The // in-process MCP endpoint forwards every tool call through these same routes, so // it derives its own limit from this constant to keep the two gates in lockstep. const MaxAPIRequestBytes = 256 << 20 // maxGeneralRequestBytes caps every procedure that does not carry file bytes. // Request bodies are buffered in memory before they are parsed, so the cap is // what bounds memory per in-flight request; it leaves ample room for the // largest memo content and settings an instance can be configured to accept. const maxGeneralRequestBytes = 16 << 20 // inlineContentProcedures carry a whole file in one request body and keep // the large cap; the size of that content is checked again by the handler // against the instance upload limit. var inlineContentProcedures = map[string]struct{}{ "/memos.api.AttachmentService/CreateAttachment": {}, "/memos.api.AIService/Transcribe": {}, } // requestBodyLimit returns the request body cap for a procedure. Chunked // uploads carry at most one chunk per call, so they get a much lower cap. func requestBodyLimit(procedure string) int64 { if procedure == attachmentUploadProcedure || procedure == importMemosProcedure { return uploadRequestLimit } if _, ok := inlineContentProcedures[procedure]; ok { return MaxAPIRequestBytes } return maxGeneralRequestBytes } type APIService struct { apipb.UnimplementedInstanceServiceServer apipb.UnimplementedAuthServiceServer apipb.UnimplementedUserServiceServer apipb.UnimplementedMemoServiceServer apipb.UnimplementedSpaceServiceServer apipb.UnimplementedAttachmentServiceServer apipb.UnimplementedAIServiceServer apipb.UnimplementedIdentityProviderServiceServer Secret string Profile *profile.Profile Store *store.Store MarkdownService markdown.Service SSEHub *SSEHub NotificationEmailSender notification.EmailSender // RateLimiter bounds request rates; nil disables every limit. RateLimiter ratelimit.Limiter // Challenge verifies proof-of-humanity tokens on signup and password // sign-in; nil means no challenge is configured. Challenge ratelimit.Challenge // SignupPolicy decides whether a self-service registration may proceed; // nil allows every registration. SignupPolicy ratelimit.SignupPolicy // thumbnailSemaphore limits concurrent thumbnail generation to prevent memory exhaustion thumbnailSemaphore *semaphore.Weighted imageProcessingSemaphore *semaphore.Weighted // instanceStatsCache memoizes GetInstanceStats results for instanceStatsCacheTTL. instanceStatsCache instanceStatsCache linkMetadataFetcher linkMetadataFetcher attachmentUploads attachmentUploads memoImports memoImports } // NewAPIService creates an API v1 service with its shared dependencies. func NewAPIService(secret string, profile *profile.Profile, store *store.Store) *APIService { markdownService := markdown.NewService( markdown.WithTagExtension(), markdown.WithMentionExtension(), ) service := &APIService{ Secret: secret, Profile: profile, Store: store, MarkdownService: markdownService, SSEHub: NewSSEHub(), NotificationEmailSender: nil, RateLimiter: newProfileRateLimiter(profile), thumbnailSemaphore: semaphore.NewWeighted(3), // Limit to 3 concurrent thumbnail generations imageProcessingSemaphore: semaphore.NewWeighted(2), } service.linkMetadataFetcher = linkmeta.NewHTMLMetaFetcher() return service } // newGatewayMarshaler mirrors grpc-gateway's default JSON marshaler with one // change: EmitDefaultValues replaces EmitUnpopulated. Both keep proto3 scalar // defaults ("" / 0 / false) and empty lists in the payload — the generated // OpenAPI schema declares several of them required — but EmitUnpopulated also // writes `null` for every unset message field (e.g. Attachment.motion_media on // a plain image). No schema marks those fields nullable, so a client that // validates responses against the spec rejects them; the MCP tools serve the // same schema as their outputSchema, and strict MCP clients fail every call // that returns an attachment. EmitDefaultValues omits unset message fields // instead, which the schema already allows. func newGatewayMarshaler() *runtime.HTTPBodyMarshaler { return &runtime.HTTPBodyMarshaler{ Marshaler: &runtime.JSONPb{ EmitDefaultValues: true, DiscardUnknown: true, }, } } // RegisterGateway registers the gRPC-Gateway and Connect handlers with the given Echo instance. func (s *APIService) RegisterGateway(ctx context.Context, echoServer *echo.Echo) error { // Shared authorizer: one source of truth for authentication and anonymous-access // policy, used by both the gRPC-Gateway middleware and the Connect interceptor. authorizer := NewAuthorizer(s.Store, s.Secret).WithRateLimiter(s.RateLimiter) // grpc-gateway does not hand the matched procedure to middleware: // runtime.RPCMethod is only populated by the generated handler, which runs // after middleware. Resolve the procedure from the proto HTTP bindings // instead so the policy check actually runs on this transport. routeResolver, err := newGatewayRouteResolver() if err != nil { return errors.Wrap(err, "failed to build gateway route resolver") } gatewayAuthMiddleware := func(next runtime.HandlerFunc) runtime.HandlerFunc { return func(w http.ResponseWriter, r *http.Request, pathParams map[string]string) { // grpc-gateway does not pass through the Connect metadata interceptor. // Apply the same no-store policy here so a memo that later loses access // cannot remain readable from a browser or intermediary response cache. setAPIResponseNoStoreHeaders(w.Header()) ctx := r.Context() authHeader := r.Header.Get("Authorization") result := authorizer.Authenticate(ctx, authHeader) // An unresolved path yields an empty procedure, which CheckAccess // treats as protected: authenticated callers pass and anonymous ones // are refused. Failing closed keeps a routing gap from becoming an // access-control gap. procedure, _ := routeResolver.resolveRequest(r) if err := authorizer.CheckAccess(ctx, procedure, result); err != nil { writeGatewayAuthorizationError(w, err) return } if err := authorizer.Throttle(ctx, procedure, result); err != nil { writeGatewayStatusError(w, err) return } // Apply the identity to the context (no-op for permitted anonymous requests). if result != nil { r = r.WithContext(auth.ApplyToContext(ctx, result)) } r.Body = http.MaxBytesReader(w, r.Body, requestBodyLimit(procedure)) next(w, r, pathParams) } } // Create gRPC-Gateway mux with auth middleware. gwMux := runtime.NewServeMux( runtime.WithMarshalerOption(runtime.MIMEWildcard, newGatewayMarshaler()), runtime.WithMiddlewares(gatewayAuthMiddleware), runtime.WithErrorHandler(gatewayErrorHandler), runtime.WithIncomingHeaderMatcher(gatewayIncomingHeaderMatcher), ) if err := apipb.RegisterInstanceServiceHandlerServer(ctx, gwMux, s); err != nil { return err } if err := apipb.RegisterAuthServiceHandlerServer(ctx, gwMux, s); err != nil { return err } if err := apipb.RegisterUserServiceHandlerServer(ctx, gwMux, s); err != nil { return err } if err := apipb.RegisterMemoServiceHandlerServer(ctx, gwMux, s); err != nil { return err } if err := apipb.RegisterSpaceServiceHandlerServer(ctx, gwMux, s); err != nil { return err } if err := apipb.RegisterAttachmentServiceHandlerServer(ctx, gwMux, s); err != nil { return err } if err := apipb.RegisterAIServiceHandlerServer(ctx, gwMux, s); err != nil { return err } if err := apipb.RegisterIdentityProviderServiceHandlerServer(ctx, gwMux, s); err != nil { return err } gwGroup := echoServer.Group("") // Register SSE endpoint with same CORS as rest of /api. RegisterSSERoutes(gwGroup, s.SSEHub, s.Store, s.Secret) handler := echo.WrapHandler(gwMux) gwGroup.Any("/api/*", handler) gwGroup.Any("/file/*", handler) gwGroup.Any("/api/v1/*", removedAPIVersionHandler(false)) // Connect handlers for browser clients (replaces grpc-web). logStacktraces := s.Profile.Demo connectInterceptors := connect.WithInterceptors( NewMetadataInterceptor(), // Convert HTTP headers to gRPC metadata first NewLoggingInterceptor(logStacktraces), NewRecoveryInterceptor(logStacktraces), NewAuthInterceptor(authorizer), ) connectMux := http.NewServeMux() connectHandler := NewConnectServiceHandler(s) connectHandler.RegisterConnectHandlers(connectMux, connectInterceptors, // Bound the decompressed message as well as the wire bytes below. connect.WithConditionalHandlerOptions(func(spec connect.Spec) []connect.HandlerOption { return []connect.HandlerOption{connect.WithReadMaxBytes(int(requestBodyLimit(spec.Procedure)))} })) connectGroup := echoServer.Group("") connectGroup.Any("/memos.api.*", echo.WrapHandler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { r.Body = http.MaxBytesReader(w, r.Body, requestBodyLimit(r.URL.Path)) connectMux.ServeHTTP(w, r) }))) connectGroup.Any("/memos.api.v1.*", removedAPIVersionHandler(true)) return nil } // removedAPIMessage tells clients of the removed v1 API where it went. const removedAPIMessage = "API v1 has been removed. Use /api/... for REST and /memos.api./ for Connect. " + "See https://github.com/usememos/memos/blob/main/proto/api/CHANGELOG.md" // removedAPIVersionHandler answers requests to the removed /api/v1 and // memos.api.v1 routes with 410 Gone, in the error body shape each transport's // clients decode. It exists for one release so old clients fail with a // pointer to the migration; delete it in the release after. func removedAPIVersionHandler(connectProtocol bool) echo.HandlerFunc { return func(c *echo.Context) error { if connectProtocol { return c.JSON(http.StatusGone, map[string]string{"code": connect.CodeUnimplemented.String(), "message": removedAPIMessage}) } return c.JSON(http.StatusGone, map[string]any{"code": int(codes.Unimplemented), "message": removedAPIMessage}) } } func setAPIResponseNoStoreHeaders(header http.Header) { header.Set("Cache-Control", "no-cache, no-store, must-revalidate") header.Set("Pragma", "no-cache") header.Set("Expires", "0") } // newProfileRateLimiter builds the default limiter, or nil when the profile // turns rate limiting off. func newProfileRateLimiter(profile *profile.Profile) ratelimit.Limiter { if !profile.RateLimit { return nil } return ratelimit.NewMemoryLimiter(ratelimit.DefaultPolicy()) } // gatewayIncomingHeaderMatcher forwards the challenge token to metadata on top // of the gateway's default set. func gatewayIncomingHeaderMatcher(key string) (string, bool) { if http.CanonicalHeaderKey(key) == challengeTokenHeader { return challengeTokenMetadataKey, true } return runtime.DefaultHeaderMatcher(key) } // gatewayErrorHandler adds the rate-limit header fields to a refusal before // the default handler writes the status body. func gatewayErrorHandler(ctx context.Context, mux *runtime.ServeMux, marshaler runtime.Marshaler, w http.ResponseWriter, r *http.Request, err error) { if st, ok := status.FromError(err); ok { for key, values := range rateLimitHTTPHeaders(st) { for _, value := range values { w.Header().Add(key, value) } } } runtime.DefaultHTTPErrorHandler(ctx, mux, marshaler, w, r, err) } // writeGatewayStatusError writes a gRPC status as the gateway's JSON error body, // including its details and any rate-limit header fields. func writeGatewayStatusError(w http.ResponseWriter, err error) { st := status.Convert(err) for key, values := range rateLimitHTTPHeaders(st) { for _, value := range values { w.Header().Add(key, value) } } body, marshalErr := protojson.Marshal(st.Proto()) if marshalErr != nil { http.Error(w, `{"code": 13, "message": "failed to encode error"}`, http.StatusInternalServerError) return } w.Header().Set("Content-Type", "application/json") w.WriteHeader(runtime.HTTPStatusFromCode(st.Code())) _, _ = w.Write(body) } func writeGatewayAuthorizationError(w http.ResponseWriter, err error) { if errors.Is(err, ErrUnauthenticated) { http.Error(w, `{"code": 16, "message": "authentication required"}`, http.StatusUnauthorized) return } slog.Error("failed to resolve API access policy", "error", err) http.Error(w, `{"code": 13, "message": "failed to resolve API access policy"}`, http.StatusInternalServerError) }