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:
- The process reads command and environment settings into a profile.
- It applies the webhook private-destination policy and validates the profile.
- It opens the selected database driver and creates the store.
- It runs database migrations.
- It applies declarative configuration when startup application is enabled.
- It seeds demo content when demo mode is enabled, then reads the instance access mode.
- It builds the server, obtains the persistent instance secret, and registers routes.
- 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.
| Service | Main responsibility | Primary paths |
|---|---|---|
| Health endpoint | Reports that the process and database are ready to serve | /healthz |
| Frontend service | Serves the embedded web app and public discovery files | /, static assets, /robots.txt, /sitemap.xml |
| File service | Serves attachments, user avatars, and administrator memo exports with access checks | /file/attachments/..., /file/users/.../avatar, /file/users/.../export |
| API service | Exposes product operations over REST-style gateway and Connect transports | /api/..., /memos.api.<Service>/<Method> |
| MCP service | Exposes 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.NewServermounts a route. - Keep
config-applybehavior aligned between startup and theconfigcommands. 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
| Trigger | Consequence | Guard |
|---|---|---|
| Invalid profile, database driver, or migration | The process does not start | Validate configuration and complete persistence setup before constructing the server |
| Invalid startup declarative configuration or an unappliable plan | The process does not start with a partial instance state | Apply and validate configuration after migration and before server creation |
A read-only config plan or config state points to a missing SQLite database | The command fails instead of silently creating a new instance | Require an existing database for read operations |
Legacy deployment files remain in /etc/secrets | Their settings are not applied to the instance | Move 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 instance | Keep the health check tied to a short database ping timeout |
| The stored instance secret is replaced during startup | Existing signed access and refresh tokens fail after restart | Generate and persist the secret only when the instance has none |
| An API path is not resolved to a protobuf procedure | Anonymous access is denied rather than bypassing policy | Treat an unresolved gateway procedure as protected |
| A public or bootstrap ACL entry names a removed or renamed RPC | The access boundary becomes stale or a startup/test path can fail to classify the method | Validate ACL names against registered method descriptors |
| The instance access policy cannot be read | The request returns a generic internal error instead of being treated as anonymous access | Keep policy-store failures separate from ErrUnauthenticated and hide the storage detail |
| An API caller changes a field managed by declarative configuration | The live instance diverges from the next configuration plan | Compare the requested field with managed state and reject only the owned change |
| A quota check fails while reading usage data | The write is refused instead of silently bypassing the limit | Map limit failures to an internal error and fail closed |
| A frontend classifier treats an API, file, Connect, or well-known path as SPA HTML | A dynamic request receives the wrong content or a discovery probe receives HTML | Exclude dynamic and hidden prefixes before static serving and fallback |
| A missing asset or discovery 404 receives a normal frontend cache policy | Clients or intermediaries keep an absent or stale response | Use no-store for missing assets and skip frontend cache headers for well-known paths |
| Native file routes are shadowed by the gateway fallback | Media clients lose native range delivery | Keep concrete file routes more specific and registered on the shared mux |
| A file request uses the wrong parent memo or an expired share token | Private content can be exposed or valid content can be denied | Resolve access from the attachment's linked resource and validate the token |
| An external attachment has a malformed or unsafe reference | The file route cannot redirect to the attachment | Allow redirects only to host-bearing HTTP or HTTPS URLs |
| A storage read fails after a file response has selected media headers | The client can receive a misleading media error instead of the JSON error envelope | Validate local files and map pre-response storage failures through the common handler |
| An export request lacks administrator access or another export is running | The archive is refused | Authenticate the caller, require an administrator, and limit concurrent exports |
| An upload sends a wrong offset or incomplete final write | The session cannot be finalized | Require the next write offset and declared total size to match committed data |
| An SSE stream remains open during shutdown | HTTP shutdown waits for work that does not finish by itself | Close the SSE hub before draining the HTTP server |
| MCP receives an untrusted browser origin | A browser can use the endpoint across sites | Require the request host or configured instance URL |
| MCP uses a placeholder peer address for its in-process API request | Anonymous callers share one rate-limit identity | Forward the address resolved by the outer request middleware |
Key files
| File | Why to read it |
|---|---|
| cmd/…/main.go | Process entry point, command modes, configuration inputs, startup, declarative configuration, demo seeding, legacy-file warning, and shutdown |
| cmd/…/config.go | Declarative configuration validation, planning, apply, and state commands |
| cmd/…/config_test.go | Guarantees for configuration command isolation, planning, database creation, and state output |
| internal/…/profile.go | Runtime profile defaults and validation |
| internal/…/clientip.go | Trusted-proxy and request client identity rules |
| server/server.go | Server construction, middleware, health readiness, route mounting, listener choice, and shutdown |
| server/cors.go | Cross-origin and cookie credential boundary |
| server/…/api.go | API transport registration, authorization, request limits, and compatibility routes |
| server/…/connect_services.go | Connect transport delegation and browser session header behavior |
| server/…/acl_config_test.go | Guarantees for public, bootstrap, protected, unknown, and registered RPC access classification |
| server/…/authz_test.go | Access-policy matrix and the distinction between authentication and policy-store failures |
| server/…/gateway_route_resolver.go | Procedure lookup used before gateway authorization |
| server/…/gateway_route_resolver_test.go | Guarantees that gateway bindings and published API paths resolve to their intended procedures |
| server/…/connect_handler.go | Connect service registration over browser-facing procedure paths |
| server/…/ratelimit.go | Rate-limit and usage-limit refusal contracts shared by transports |
| server/…/usage_limit.go | Fail-closed usage checks for memo and attachment writes |
| server/…/instance_service.go | Instance profile, setting access, secret handling, and declarative configuration ownership |
| server/…/user_service_memo_views.go | Authenticated user-owned memo view resource behavior |
| server/…/memo_view_service_test.go | Guarantees for memo view ownership, resource names, validation, ordering, and update safety |
| server/…/instance_service_configuration_test.go | Guarantees that API edits respect managed configuration and referenced resources |
| server/…/instance_service_test.go | Guarantees for instance profile visibility and setting authorization and validation |
| server/…/frontend.go | Static assets, cache policy, SPA fallback, hidden-path handling, and discovery routes |
| server/…/frontend_test.go | Guarantees for frontend cache boundaries, dynamic-path bypass, and discovery behavior |
| server/…/fileserver.go | Native attachment, avatar, and export route registration plus file delivery boundary |
| server/…/memo_export.go | Administrator-only export admission and streaming behavior |
| server/…/attachment_upload.go | Resumable attachment upload lifecycle |
| server/…/upload_session.go | Upload limits, expiration, retries, and cleanup |
| server/…/sse_handler.go | Authenticated long-lived event stream |
| server/…/service.go | MCP endpoint, transport, request limit, and tool registration |
| server/…/adapter.go | In-process translation from MCP tools to API requests |
| server/…/startup_test.go | Full-process checks for startup, route mounting, access policy, response encoding, and restart behavior |
| server/http_compat_test.go | HTTP status, header, path, CORS, and streaming compatibility across the route tree |
| server/…/fileserver_test.go | Coverage for file authorization, external references, ranges, storage modes, avatars, thumbnails, and error responses |