Introducing a new way to review your PRs.

Read the announcement

usememos / memos

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

View on GitHub

25 documents · Updated Nov 20, 2026

docs / server-runtime-and-routing

Server runtime and request routing

Memos runs as one HTTP process that opens its data store, builds a shared server, and dispatches requests to the web app, product API, file delivery, and MCP interface. These entry points use one listener and shared instance state, authentication, client identity, storage, and shutdown rules.

Process startup

The command process turns flags and environment values into a validated runtime profile. It prepares persistence, access settings, and optional declarative configuration before it creates the HTTP server, so every route starts with the same database, access policy, and instance configuration.

Runtime configuration

The runtime profile defines the mode, listener, data directory, database driver, database source name, canonical instance URL, rate limiting, trusted proxy ranges, and declarative configuration behavior. Cobra supplies command-line flags. Viper also reads MEMOS_ environment variables by changing hyphens to underscores. Normal startup uses SQLite and port 8081; the profile also supports MySQL, PostgreSQL, and Cloudflare D1. Demo mode uses SQLite and a separate database file.

Profile validation normalizes the instance URL, creates or checks the data directory, and selects a SQLite database file when no source name is given. The profile also turns the trusted-proxy setting into the client-address policy used by the whole request tree. Deployment and operations choices that surround these settings are described in deployment, configuration, and operations.

References: cmd/…/main.go• L56-115 internal/…/profile.go• L15-42 internal/…/profile.go• L64-123 internal/…/clientip.go• L45-85

Command modes

The command has a server mode, a version-only mode, and configuration management commands. --version, -V, and the version subcommand use the same build version and do not open the database or start an HTTP listener. The config commands operate on declarative instance settings without starting the HTTP server.

References: cmd/…/main.go• L37-54 cmd/…/main.go• L108-116 cmd/…/config.go• L33-90

Declarative configuration commands

The config command lets an operator validate, preview, apply, and inspect declarative instance settings. Validation reads configuration without a database. Planning compares the desired state with an existing database, while apply can migrate or create the database and writes the change and state record as one operation. State reports what the configuration currently manages.

The server can apply the same configuration during startup. config-apply=startup keeps the instance from serving until the desired state is valid and applied; config-apply=off leaves application to an explicit config apply step, which supports a separate configuration job before a rollout.

References: cmd/…/config.go• L33-90 cmd/…/config.go• L160-245 cmd/…/config.go• L248-319 cmd/…/main.go• L261-304

Startup sequence

Startup follows a fixed order in which each stage prepares the next stage:

  1. The process reads command and environment settings into a profile.
  2. It applies the webhook private-destination policy and validates the profile.
  3. It opens the selected database driver and creates the store.
  4. It runs database migrations.
  5. It applies declarative configuration when startup application is enabled.
  6. It seeds demo content when demo mode is enabled, then reads the instance access mode.
  7. It builds the server, obtains the persistent instance secret, and registers routes.
  8. It opens a TCP listener or Unix socket and serves HTTP.

Invalid declarative configuration stops startup rather than allowing the process to run with an unexpected instance state. Legacy deployment files are no longer loaded; startup warns when it finds them and points operators to the declarative configuration directory. The deprecated broad private-webhook switch remains available for compatibility, while the allowlist provides narrower control.

The server persists a generated instance secret when one does not exist. That secret signs tokens and must survive a restart. Demo mode uses its fixed demo secret instead.

References: cmd/…/main.go• L119-200 cmd/…/main.go• L261-304 server/server.go• L52-119 server/server.go• L193-213

Listener lifecycle

The listener uses TCP when no Unix socket is configured. A Unix socket overrides the address and port and receives mode 0660. The HTTP server limits header wait time and idle keep-alive time, but it allows long request bodies and streaming responses for uploads and SSE.

Shutdown closes long-lived SSE connections first. It then drains normal HTTP work within ten seconds, removes pending upload sessions and temporary files, and closes the store. This order prevents active requests from losing their staged upload state while the process is still serving them.

References: server/server.go• L27-40 server/server.go• L122-190 server/…/upload_session.go• L232-264

Server composition

The server builds one net/http request tree around a profile and store. Shared middleware runs before the mounted services, while each service owns the response type and access checks for its delivery path.

Shared middleware

Recovery turns handler panics into controlled server errors. CORS reflects non-null origins for API use, but only the request host or configured instance URL receives permission to use cookie credentials. Token-authenticated callers can therefore call the API from other origins without making refresh-cookie responses readable there.

The client-address middleware resolves the request address once. It trusts forwarding headers only from configured proxies and stores the result in the request context. Rate limits, session records, file access, and in-process MCP calls then use the same client identity.

References: server/server.go• L58-67 server/server.go• L102-111 server/cors.go• L12-55 internal/…/clientip.go• L99-139 internal/…/clientip.go• L173-183

Mounted services

The server mounts explicit file routes with native HTTP behavior and gives their unmatched requests to the API gateway. The health endpoint reports readiness only while the database answers. The current server composition does not mount an RSS router; RSS is therefore not a live route in this process unless a later composition adds one.

ServiceMain responsibilityPrimary paths
Health endpointReports that the process and database are ready to serve/healthz
Frontend serviceServes the embedded web app and public discovery files/, static assets, /robots.txt, /sitemap.xml
File serviceServes attachments, user avatars, and administrator memo exports with access checks/file/attachments/..., /file/users/.../avatar, /file/users/.../export
API serviceExposes product operations over REST-style gateway and Connect transports/api/..., /memos.api.<Service>/<Method>
MCP serviceExposes selected API operations as Model Context Protocol tools/mcp

The detailed product API surface is described in API contracts and service implementation. File, RSS, and MCP behavior is described in MCP, RSS, and file delivery endpoints.

References: server/server.go• L77-119 server/…/api.go• L138-260 server/…/fileserver.go• L127-146 server/…/memo_export.go• L20-35 server/…/frontend.go• L41-60

Request routing

The request path selects a delivery interface before that interface applies its own authentication and data rules. Native file routes take precedence over the API gateway fallback. MCP calls are translated back into the same in-process API handler, while frontend fallback avoids paths owned by dynamic services.

Dispatch map

This map shows how an HTTP request moves from shared middleware to the service that owns its response.

flowchart TD
    Request[HTTP request] --> Middleware[Recovery, CORS, and client address]
    Middleware --> Health[/healthz/]
    Middleware --> Frontend[Frontend assets or SPA fallback]
    Middleware --> File[/file/ native attachment, avatar, and export routes]
    Middleware --> API[/api/* gateway or Connect method path]
    Middleware --> MCP[/mcp]
    MCP --> Adapter[In-process API request]
    Adapter --> API

The frontend static layer skips /api, /file, Connect method paths, and .well-known paths. It serves HTML for the root and extensionless application paths. It uses the SPA entry point only when an eligible path produces a not-found result. Missing asset files and hidden paths remain not found. robots.txt and sitemap.xml are separate discovery routes and require public instance access.

Frontend cache rules follow the same boundary. HTML is not stored, hashed assets can be cached as immutable, and stable assets use a shorter revalidation window. Missing assets use no-store, while dynamic namespaces and well-known discovery paths bypass frontend cache headers so a cached HTML or 404 response cannot stand in for a live service or metadata endpoint.

References: server/server.go• L96-111 server/…/frontend.go• L41-126 server/…/frontend.go• L135-144 server/…/frontend_test.go• L18-232

API transports

The API service exposes two browser and HTTP transports over the same service implementations. The gRPC-Gateway maps protobuf HTTP bindings to /api/..., while Connect serves procedure paths under /memos.api.<Service>/<Method>. Connect handlers pass requests to the same API service methods and preserve the shared error model; authentication methods also carry response headers needed by browser sessions. The old /api/v1/... and /memos.api.v1.* paths return 410 Gone with a migration message rather than reaching a service.

Both transports use one authorization policy and procedure-specific request limits. General requests are capped at 16 MiB. Inline file and AI content can use the 256 MiB API cap, while chunked uploads and memo imports use a smaller per-call limit. Gateway authorization resolves the matched protobuf procedure from its HTTP binding before the generated handler runs. An unresolved procedure is treated as protected.

Authorization failures keep authentication failures separate from server failures. An unauthenticated request receives an unauthorized response, while a failure to read the instance access policy returns an internal error without exposing the storage error to the client. The same method-level policy distinguishes public methods, bootstrap methods, and protected methods for public and private instances. Unknown methods default to protected, and access-control entries must name real RPC methods.

The API JSON marshaler omits unset message fields while keeping scalar defaults. This keeps responses valid against the generated OpenAPI contract, which is also used by MCP tool output schemas. API operations also apply rate limits and user usage limits at the service boundary, so a request can be rejected before its data change is made.

Saved memo views are part of the authenticated user API. Their resource paths sit below a user's resource and remain limited to that user, so exposing their gateway and Connect bindings does not make personal views public.

Instance profile and setting methods expose the runtime state that the frontend needs to start and operate an instance. The profile reports first-run setup from whether any user exists, while it hides the administrator identity from anonymous callers. Sensitive settings require an administrator; non-administrators receive only the AI data needed for feature access. Write-only credentials are never returned and remain unchanged when an update omits them.

API updates also respect declarative configuration ownership. A managed field can be sent again with its current value, but a change is refused until the configuration no longer owns that field. This keeps settings changed through the API consistent with the state that startup and configuration commands enforce.

References: server/…/api.go• L29-58 server/…/api.go• L138-260 server/…/connect_services.go• L12-23 server/…/connect_services.go• L328-379 server/…/acl_config_test.go• L15-187 server/…/gateway_route_resolver.go• L23-127 server/…/gateway_route_resolver_test.go• L81-277 server/…/user_service_memo_views.go• L76-280 server/…/memo_view_service_test.go• L17-114

File delivery

The native file service owns concrete attachment, avatar, and administrator memo export paths. It checks attachment access from the linked memo or comment, instance access mode, and an optional valid share token before it reads bytes. Unlinked attachments are limited to their creator or an administrator, while memo exports require an administrator for the selected user.

After authorization, media streams support HTTP ranges from local storage, S3, or database storage. External attachments redirect only to valid HTTP or HTTPS references. Public files use revalidation-friendly caching; protected files use private no-store caching. The service can serve thumbnails or motion clips, but it falls back to the original image when thumbnail processing could lose sensitive image metadata or exceed safe decode bounds. Browser refresh-token cookies can authenticate private file requests, and storage failures before the response starts use the normal JSON error envelope.

References: server/…/fileserver.go• L127-204 server/…/fileserver.go• L242-325 server/…/fileserver.go• L386-445 server/…/fileserver.go• L711-794 server/…/memo_export.go• L20-120 server/…/fileserver_test.go• L125-264 server/…/fileserver_test.go• L1239-1266

Attachment upload flow

Chunked attachment upload separates request size from final attachment size. An authenticated caller starts a session with metadata, sends bounded chunks at the next committed offset, and finishes only after the declared byte count is complete.

flowchart LR
    Client[Authenticated client] --> Start[Start upload session]
    Start --> Chunks[Send bounded chunks]
    Chunks --> Finish[Finish at committed size]
    Finish --> Validate[Recheck access and usage limits]
    Validate --> Store[Process and save attachment]
    Store --> Result[Attachment resource]

Upload state stays in memory and unfinished bytes stay in a temporary file. Sessions expire after thirty minutes, retry the last accepted chunk safely, and are removed during shutdown. Finalization rechecks permissions and storage limits before it creates the attachment record.

References: server/…/attachment_upload.go• L37-103 server/…/attachment_upload.go• L105-185 server/…/upload_session.go• L16-24 server/…/upload_session.go• L44-85 server/…/upload_session.go• L232-264

Live update delivery

SSE is a long-lived API route at /api/sse, not a second data API. It requires a bearer-authenticated user and sends small memo or space change events so clients can refresh their own data. The hub disconnects slow clients rather than silently dropping events.

The server closes the SSE hub before normal HTTP shutdown. This makes long-lived streams finish and lets the ten-second shutdown drain complete.

References: server/…/sse_handler.go• L21-48 server/…/sse_handler.go• L60-121 server/…/sse_hub.go• L62-107 server/server.go• L158-179

MCP delivery

The MCP endpoint uses stateless Streamable HTTP with JSON responses. Its catalog is fixed at startup and is built from the embedded OpenAPI description, but only a curated set of product operations is exposed.

Each tool call validates its arguments, reads the caller's authorization header, builds the matching /api/... request, and runs that request through the same HTTP handler. The adapter also carries forward the resolved client address so rate limits do not collapse all in-process calls onto a test peer address. API authentication, authorization, errors, usage limits, and response encoding therefore remain the source of truth for MCP.

The endpoint accepts requests without an Origin header for non-browser clients. A supplied origin must match the request host or configured instance URL. Its request body limit follows the 256 MiB API cap so large attachment calls are not rejected by a smaller transport default.

References: server/…/service.go• L19-28 server/…/service.go• L38-97 server/…/service.go• L131-164 server/…/adapter.go• L29-105 server/…/origin.go• L10-31

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the startup sequence in cmd/…/main.go aligned with full-server coverage. Isolated API tests do not prove that server.NewServer mounts a route.
  • Keep config-apply behavior aligned between startup and the config commands. A replica that skips startup application must apply the same desired state before it serves traffic.
  • Keep configuration plan and state operations aligned with database migration behavior. Read-only commands must not create or migrate a missing database.
  • Keep startup configuration application after migration and before demo seeding. Demo content must attach to the declared users.
  • Keep legacy deployment-file warnings aligned with the move to declarative configuration. The old files must not silently regain precedence over the configuration directory.
  • Keep the native /file/... routes ahead of the API gateway fallback. A registration change can replace range-aware media delivery with gateway behavior.
  • Keep attachment, avatar, and administrator export route registration aligned with their access checks and HTTP method behavior. A route can expose a handler without preserving its intended boundary.
  • Keep /api/... and /memos.api.<Service>/<Method> aligned with the generated HTTP bindings. The removed v1 handlers are temporary migration boundaries.
  • Keep every Connect method aligned with its API service method and header behavior. A new RPC needs both transport exposure and the same authentication and error contract.
  • Keep gateway route resolution aligned with protobuf HTTP templates and additional bindings. Authorization depends on the selected procedure before handler execution.
  • Keep public, bootstrap, and protected ACL entries aligned with registered RPC methods. Unknown procedures must remain protected, and renamed procedures must not leave stale public entries.
  • Keep user-owned memo view bindings, resource-name rules, and owner checks aligned. A route change can make a personal resource reachable under the wrong user.
  • Keep authentication failures distinct from access-policy lookup failures. Clients need an unauthorized response for missing credentials and a generic internal response for a failed policy lookup.
  • Keep instance profile privacy, sensitive-setting access, write-only credential handling, and configuration ownership aligned between API responses and update paths. A change to one path can expose secrets or allow the API to override declarative state.
  • Keep API, Connect, MCP, and chunked-upload request limits aligned. MCP forwards tool calls to the API, while uploads need a smaller per-call bound.
  • Keep API rate-limit and usage-limit errors aligned across REST, Connect, and MCP. These transports must preserve the same refusal meaning and retry behavior.
  • Treat InstanceURL, access mode, CORS, MCP origin checks, and file cache policy as one boundary. These values control browser credentials and public delivery.
  • Preserve the stored instance secret across startup changes. Replacing its bootstrap behavior invalidates tokens after restart.
  • Keep the resolved client address stable across the MCP in-process hop. Otherwise anonymous rate limits can merge callers into one bucket.
  • Close upload managers after HTTP draining when changing shutdown order. Temporary files and session state must not outlive the process.
  • Keep frontend path exclusions ahead of SPA fallback. Dynamic API, file, Connect, and well-known discovery requests must not receive application HTML or stale asset caching.
  • Keep frontend cache classification aligned with dispatch. Missing assets and well-known paths must not inherit cache rules for valid assets or application HTML.

Important failure modes

TriggerConsequenceGuard
Invalid profile, database driver, or migrationThe process does not startValidate configuration and complete persistence setup before constructing the server
Invalid startup declarative configuration or an unappliable planThe process does not start with a partial instance stateApply and validate configuration after migration and before server creation
A read-only config plan or config state points to a missing SQLite databaseThe command fails instead of silently creating a new instanceRequire an existing database for read operations
Legacy deployment files remain in /etc/secretsTheir settings are not applied to the instanceMove the settings into the declarative configuration directory; startup warns when it finds legacy file names
The database stops answering health checks/healthz returns 503 Service Unavailable, so a load balancer can stop routing to the instanceKeep the health check tied to a short database ping timeout
The stored instance secret is replaced during startupExisting signed access and refresh tokens fail after restartGenerate and persist the secret only when the instance has none
An API path is not resolved to a protobuf procedureAnonymous access is denied rather than bypassing policyTreat an unresolved gateway procedure as protected
A public or bootstrap ACL entry names a removed or renamed RPCThe access boundary becomes stale or a startup/test path can fail to classify the methodValidate ACL names against registered method descriptors
The instance access policy cannot be readThe request returns a generic internal error instead of being treated as anonymous accessKeep policy-store failures separate from ErrUnauthenticated and hide the storage detail
An API caller changes a field managed by declarative configurationThe live instance diverges from the next configuration planCompare the requested field with managed state and reject only the owned change
A quota check fails while reading usage dataThe write is refused instead of silently bypassing the limitMap limit failures to an internal error and fail closed
A frontend classifier treats an API, file, Connect, or well-known path as SPA HTMLA dynamic request receives the wrong content or a discovery probe receives HTMLExclude dynamic and hidden prefixes before static serving and fallback
A missing asset or discovery 404 receives a normal frontend cache policyClients or intermediaries keep an absent or stale responseUse no-store for missing assets and skip frontend cache headers for well-known paths
Native file routes are shadowed by the gateway fallbackMedia clients lose native range deliveryKeep concrete file routes more specific and registered on the shared mux
A file request uses the wrong parent memo or an expired share tokenPrivate content can be exposed or valid content can be deniedResolve access from the attachment's linked resource and validate the token
An external attachment has a malformed or unsafe referenceThe file route cannot redirect to the attachmentAllow redirects only to host-bearing HTTP or HTTPS URLs
A storage read fails after a file response has selected media headersThe client can receive a misleading media error instead of the JSON error envelopeValidate local files and map pre-response storage failures through the common handler
An export request lacks administrator access or another export is runningThe archive is refusedAuthenticate the caller, require an administrator, and limit concurrent exports
An upload sends a wrong offset or incomplete final writeThe session cannot be finalizedRequire the next write offset and declared total size to match committed data
An SSE stream remains open during shutdownHTTP shutdown waits for work that does not finish by itselfClose the SSE hub before draining the HTTP server
MCP receives an untrusted browser originA browser can use the endpoint across sitesRequire the request host or configured instance URL
MCP uses a placeholder peer address for its in-process API requestAnonymous callers share one rate-limit identityForward the address resolved by the outer request middleware

Key files

FileWhy to read it
cmd/…/main.goProcess entry point, command modes, configuration inputs, startup, declarative configuration, demo seeding, legacy-file warning, and shutdown
cmd/…/config.goDeclarative configuration validation, planning, apply, and state commands
cmd/…/config_test.goGuarantees for configuration command isolation, planning, database creation, and state output
internal/…/profile.goRuntime profile defaults and validation
internal/…/clientip.goTrusted-proxy and request client identity rules
server/server.goServer construction, middleware, health readiness, route mounting, listener choice, and shutdown
server/cors.goCross-origin and cookie credential boundary
server/…/api.goAPI transport registration, authorization, request limits, and compatibility routes
server/…/connect_services.goConnect transport delegation and browser session header behavior
server/…/acl_config_test.goGuarantees for public, bootstrap, protected, unknown, and registered RPC access classification
server/…/authz_test.goAccess-policy matrix and the distinction between authentication and policy-store failures
server/…/gateway_route_resolver.goProcedure lookup used before gateway authorization
server/…/gateway_route_resolver_test.goGuarantees that gateway bindings and published API paths resolve to their intended procedures
server/…/connect_handler.goConnect service registration over browser-facing procedure paths
server/…/ratelimit.goRate-limit and usage-limit refusal contracts shared by transports
server/…/usage_limit.goFail-closed usage checks for memo and attachment writes
server/…/instance_service.goInstance profile, setting access, secret handling, and declarative configuration ownership
server/…/user_service_memo_views.goAuthenticated user-owned memo view resource behavior
server/…/memo_view_service_test.goGuarantees for memo view ownership, resource names, validation, ordering, and update safety
server/…/instance_service_configuration_test.goGuarantees that API edits respect managed configuration and referenced resources
server/…/instance_service_test.goGuarantees for instance profile visibility and setting authorization and validation
server/…/frontend.goStatic assets, cache policy, SPA fallback, hidden-path handling, and discovery routes
server/…/frontend_test.goGuarantees for frontend cache boundaries, dynamic-path bypass, and discovery behavior
server/…/fileserver.goNative attachment, avatar, and export route registration plus file delivery boundary
server/…/memo_export.goAdministrator-only export admission and streaming behavior
server/…/attachment_upload.goResumable attachment upload lifecycle
server/…/upload_session.goUpload limits, expiration, retries, and cleanup
server/…/sse_handler.goAuthenticated long-lived event stream
server/…/service.goMCP endpoint, transport, request limit, and tool registration
server/…/adapter.goIn-process translation from MCP tools to API requests
server/…/startup_test.goFull-process checks for startup, route mounting, access policy, response encoding, and restart behavior
server/http_compat_test.goHTTP status, header, path, CORS, and streaming compatibility across the route tree
server/…/fileserver_test.goCoverage for file authorization, external references, ranges, storage modes, avatars, thumbnails, and error responses