API contracts and service implementation
The Memos API is a protobuf contract for account, memo, space, attachment, instance, identity, configuration-status, and memo-transfer operations. Attachment operations include inline uploads, resumable uploads, and content replacement. Generated bindings expose the same contract through REST and Connect, while server/api applies access rules, quota rules, configuration ownership rules, and product actions before it reads or changes domain and persistence state. See the parent page, server runtime and routing, for how requests enter this layer. See MCP, RSS, and file delivery for archive downloads and other file-boundary flows. See persistence and data evolution for the storage boundary.
API contract surface
The public contract lives in proto/api/. It defines resource names, RPCs, HTTP routes, request fields, response fields, and access-related behavior in one place. The package is memos.api without a version marker; breaking changes are recorded in proto/…/CHANGELOG.md.
Resource and request model
Resources give each product object a stable name that clients can reuse in later calls. The contract uses common request shapes for create, update, delete, list, and custom actions, so REST, Connect, gRPC, and generated clients describe the same product behavior.
The main contract rules are:
| Contract rule | Product meaning |
|---|---|
| Resource names | Identify objects such as memos/{memo}, users/{user}, and spaces/{space} across calls. User names use the public username rather than an internal numeric ID. |
INPUT_ONLY fields | Accept values such as passwords, file bytes, and secrets without returning them in normal resources. |
OUTPUT_ONLY fields | Expose server values such as timestamps, computed memo data, sizes, roles, and creators. |
FieldMask updates | Change only the named fields when the service supports partial updates. Instance settings are replaced as a whole even though the update request carries a field mask. |
next_page_token | Continue a bounded list without exposing the server's page position format. |
oneof values | Select one credential, setting value, upload mode, or media detail. |
| Declarative configuration messages | Describe desired resources, lifecycle rules, removals, plans, and the state of the last apply without exposing configured values. |
| Usage metrics | Apply separate bounds to memo count, memo content bytes, total stored upload bytes, and one upload's size. |
| Attachment replacement | Let a resumable upload replace stored content while keeping the attachment name, memo link, creator, and creation time. The caller must be allowed to manage the target. |
List requests can also carry product filters and sort rules. Memo views reuse the memo filter as a saved query, while user and attachment lists expose their own supported filter fields. Instance settings no longer include MEMO_RELATED; reaction choice is not controlled by an instance setting.
References: proto/…/README.md• L7-32 proto/…/common.proto• L7-33 proto/…/configuration.proto• L12-35 proto/…/configuration.proto• L38-77 proto/…/instance_service.proto• L125-177 proto/…/instance_service.proto• L461-494 proto/…/memo_service.proto• L17-25 proto/…/memo_service.proto• L305-389 proto/…/user_service.proto• L350-376 proto/…/user_service.proto• L639-643 proto/…/attachment_service.proto• L128-159 proto/…/attachment_service.proto• L246-267 proto/…/CHANGELOG.md• L28-35
API version and route model
The API uses unversioned REST paths under /api/ and fully qualified procedures under /memos.api.<Service>/<Method>. Resource types also use memos.api/<Type>, so generated clients and access policy must use the same package and route names.
For one migration release, the server answers old /api/v1/... and /memos.api.v1.* requests with 410 Gone and a message that points to the changelog. This gives old clients a clear migration result without keeping two active product contracts.
References: proto/…/CHANGELOG.md• L28-80 proto/…/memo_service.proto• L20-30 proto/…/instance_service.proto• L17-67 server/…/api.go• L236-278
Generated bindings
The protobuf files are the source of truth. Buf generation turns the API definitions into Go message types, gRPC contracts, gRPC-Gateway adapters, Connect clients and handlers, an OpenAPI description, and TypeScript types for the web client. It also turns store definitions into the typed records used at the persistence boundary.
The generated outputs have these roles:
| Output | Role |
|---|---|
| proto/…/*.pb.go | Carry public API messages, enums, and Go service interfaces. |
| proto/…/*_grpc.pb.go | Define native gRPC procedures, clients, servers, and registration metadata. |
| proto/…/*.connect.go | Define Connect procedure paths, clients, and HTTP handlers. |
| proto/…/*_pb.gw.go | Map annotated REST requests to protobuf calls and JSON responses. |
| proto/…/openapi.yaml | Describe the REST paths and schemas used by tools and clients. |
| proto/…/*.pb.go | Carry the persistence-side settings and memo payload types used by the store and API converters. |
web/src/types/proto | Keep web request and response types aligned with the contract. |
The instance bindings carry the current setting keys, including usage limits but not the removed MEMO_RELATED setting. The UserService bindings carry the user resource, statistics, usage, saved-view, notification, identity, token, and memo-import surface across gRPC, REST, and Connect. The store bindings keep persistence-only shapes such as usage-limit records and configuration state separate from the public instance-setting API. Generated code does not add a second set of product rules. It carries the same service surface to each supported client and transport, while store bindings carry the persistence shape behind the service boundary.
References: proto/buf.yaml• L1-19 proto/buf.gen.yaml• L1-30 proto/…/user_service.pb.go• L1339-1364 proto/…/user_service_grpc.pb.go• L22-56 proto/…/user_service.connect.go• L24-131 proto/…/user_service.pb.gw.go• L38-70 proto/…/instance_service.pb.go• L470-636 proto/…/instance_service.pb.go• L1041-1055 proto/…/attachment_service.pb.go• L856-930 proto/…/openapi.yaml• L510-684 proto/…/instance_setting.pb.go• L316-500 proto/…/instance_setting.pb.go• L1420-1485 proto/…/memo.pb.go• L1-15
Service request path
The server presents one product implementation through REST and Connect. A transport adapter decodes the request, shared admission checks protect the call, APIService applies resource and domain rules, and the result is converted to a public protobuf response.
This diagram shows how the contract reaches persistence and external services.
flowchart LR
C[Protobuf contract] --> G[Generated bindings]
R[REST or Connect request] --> T[Transport adapter]
G --> T
T --> A[Authentication, challenge, and request policy]
A --> H[APIService handler]
H --> D[Domain rules, quota checks, configuration ownership, and resource conversion]
D --> P[Store or external service]
P --> O[Typed response or status error]
O --> T
Transport adapters
APIService owns the shared store, profile, markdown, notification, upload, import, and rate-control dependencies for the public services. Gateway registration maps the generated REST handlers to /api/* and file delivery routes, while Connect registration exposes the generated procedure paths under /memos.api.*.
The request dispatcher sends SSE requests to the event stream, rejects the removed versioned paths with a migration response, sends Connect procedures to the Connect handlers, and sends REST and file paths to the Gateway. Both REST and Connect use the same authorizer and procedure-specific body limits. Inline file calls keep the high API cap, while attachment and memo-import chunks use a lower per-call cap. REST responses also disable caching so a later access change cannot leave protected data in an intermediary cache.
The Connect wrapper delegates each generated method to the matching APIService method. It converts gRPC status details and rate-limit metadata into Connect errors, so clients receive the same product result through either transport. Authentication methods use a shared header carrier when the service must set or clear session cookies.
References: server/…/api.go• L29-58 server/…/api.go• L60-117 server/…/api.go• L120-136 server/…/api.go• L138-260 server/…/connect_handler.go• L14-50 server/…/connect_handler.go• L64-90 server/…/connect_services.go• L17-73 server/…/connect_services.go• L104-224 server/…/connect_services.go• L328-371 proto/…/user_service.connect.go• L670-825
Authentication and request limits
The shared authorizer is the first policy gate. It authenticates access tokens or personal access tokens, permits only the defined anonymous methods, and checks the instance access mode before a public method reaches its handler. Resource-specific rules remain in the service because they need the requested user, memo, space, or attachment.
The public-method map is also split into normal public methods and a smaller bootstrap set. The bootstrap set keeps sign-in, instance discovery, registration, identity-provider discovery, and share links available when the instance is private. Configured proof-of-humanity challenges add a separate precondition when a request needs one. Request limits protect in-memory request handling, and rate-limit refusals carry stable status details and retry information through both HTTP and Connect. Inline content and chunked upload procedures use different body caps, while the attachment handler checks the final file size and user quota again. Usage-limit refusals use the same RESOURCE_EXHAUSTED code but identify a quota and do not claim that waiting will help. The access policy tests preserve the distinction between an unauthenticated caller and an internal access-store failure, which becomes a server error rather than an authentication response.
References: server/…/acl_config.go• L3-85 server/…/authz.go• L15-117 server/…/api.go• L28-57 server/…/api.go• L140-183 server/…/ratelimit.go• L25-181 server/…/acl_config_test.go• L15-187 server/…/attachment_upload_transport_test.go• L34-110
Domain and persistence boundary
The handlers translate public resources into store and domain operations, then rebuild public resources from the result. This boundary keeps storage records out of the API and gives each operation one place for validation, access checks, quota checks, derived fields, and side effects.
Memo responses show this relationship clearly. A response can combine stored memo content with derived payload data such as tags, location, and content properties. It can also include readable attachments, relations, reactions, comments, snippets, and space placement. The converter includes each related value only after the relevant access rule passes; a parent memo's identity in a comment does not grant access to the parent.
References: proto/…/memo.proto• L7-31 server/…/memo_service.go• L25-79 server/…/memo_service.go• L85-236 server/…/memo_create_helpers.go• L32-92 server/…/memo_service_converter.go• L26-137 server/…/resource_name.go• L33-69
Product service groups
The protobuf services group operations by the product resource or capability they govern. Each group has a public contract and matching methods on the shared APIService.
Authentication and identity services
AuthService starts, refreshes, and ends user sessions. Password and SSO sign-in return a short-lived access token, while refresh-token rotation uses an HTTP-only cookie so the browser can renew a session without exposing the long-lived token to page scripts. Access tokens are bound to the user's password state, so a password change or administrator reset invalidates old access tokens; the session that makes its own change can still refresh.
IdentityProviderService exposes the provider list needed by sign-in and lets administrators manage configured OAuth2 providers. Client secrets are write-only, and deployment-managed providers cannot be changed through the API.
SSO resolves an external subject to one local user. A signed-in user can bind a new identity, while a first-time visitor can create an account only when registration permits it; the service does not treat an external email as proof of ownership of an existing local account. It uses the provider subject or a safe generated username and handles concurrent identity claims without linking the identity to the wrong account.
References: proto/…/auth_service.proto• L14-49 proto/…/idp_service.proto• L14-57 server/…/auth_service.go• L24-107 server/…/auth_service_session.go• L25-184 server/…/auth_service_session.go• L249-293 server/…/auth_service_sso.go• L19-69 server/…/auth_service_sso.go• L100-185 server/…/idp_service.go• L19-51
User services
UserService manages accounts and user-owned support resources. Its surface includes settings, statistics, usage views, notifications, webhooks, linked identities, personal access tokens, and Memos import. User archive export is a file-delivery operation rather than a UserService RPC.
Account actions preserve instance governance. The first account becomes an administrator, self-service registration follows instance policy, password changes revoke other sessions, and the last active instance administrator cannot be removed. User usage reports memo count and stored upload bytes together with effective limits for memo count, memo content, total storage, and one upload. User statistics also expose persisted attachment size for the authenticated user's own statistics, independent of the memo filter. User resources use canonical users/{username} names, which also lets usage-limit settings and declarative configuration refer to the same user identity.
User settings are private to the owning user. Field masks merge supported general preferences, while tag and editor settings accept their supported fields as complete values; the service returns defaults when a setting has not yet been stored.
The file-delivery boundary streams an instance-administrator's archive of one user's own memos, comments, and linked files. Import stages an archive in bounded chunks, can first return a validation plan, and then applies an explicit conflict policy. Imported memos and stored files use the same write and quota controls as normal product actions. Saved memo views are reusable filters rather than a second memo store, and their ownership keeps the query private to the user who created it.
References: proto/…/user_service.proto• L19-22 proto/…/user_service.proto• L43-115 proto/…/user_service.proto• L117-297 proto/…/user_service.proto• L605-643 proto/…/user_service.proto• L687-740 proto/…/user_service.proto• L1303-1382 proto/…/CHANGELOG.md• L28-45 proto/…/user_service.pb.go• L1339-1453 server/…/user_service.go• L61-188 server/…/user_service.go• L203-337 server/…/user_service.go• L340-483 server/…/user_service_settings.go• L15-252 server/…/user_service_converters.go• L143-232 server/…/user_service_usage.go• L15-64 server/…/user_service_identities.go• L14-157 server/…/user_service_memo_export.go• L34-73 server/…/user_service_memo_transfer.go• L33-146 server/…/user_resource_name.go• L11-38
Memo services
MemoService is the main product surface for Markdown memos. It covers memo lifecycle, visibility, comments, relations, reactions, share links, link metadata, and memo attachment links.
Memo creation and update validate visibility, space placement, memo count, content bytes, managed attachment references, and relations before the store mutation. The limit belongs to the memo owner, even when an administrator edits the memo. A successful write can also publish live-change events, send notifications, and call user webhooks. Comments are independent memo resources with an immutable parent relation, while attachment and reference setters replace the requested set.
The contract uses field masks for selected updates and page tokens for bounded lists. A share-token read is a separate unauthenticated path that returns not found for an invalid or expired token. Memo access rules apply again when the service assembles related resources. The response converter also projects space placement only to viewers who can learn it and skips reactions whose creator record no longer exists.
References: proto/…/memo_service.proto• L17-186 proto/…/memo_service.proto• L188-303 proto/…/memo_service.proto• L387-396 proto/…/CHANGELOG.md• L77-95 server/…/memo_service.go• L25-158 server/…/memo_service.go• L286-490 server/…/memo_service_comments.go• L18-95 server/…/memo_create_helpers.go• L32-92 server/…/memo_service_converter.go• L50-137 server/…/usage_limit.go• L13-50
Space services
SpaceService manages collaborative spaces, memberships, roles, and invitations. A space is both a placement boundary for memos and a read boundary for memos with SPACE visibility.
Creating a space gives the caller its first administrator role. An invitation does not grant access until acceptance; role changes and member removal preserve the rule that a space must keep an administrator. Invitation actions also coordinate user notifications with the current membership state.
References: proto/…/space_service.proto• L14-147 proto/…/space_service.proto• L149-190 server/…/space_service.go• L86-310 server/…/space_service_notifications.go• L12-80
Attachment services
AttachmentService manages binary media and optional memo links. It supports inline creation and resumable chunk uploads, returns normalized metadata, and exposes files only through the authenticated file boundary. A resumable upload can also replace the content of an existing attachment while preserving its identity and memo link.
The service checks ownership or memo access before reads and writes. It applies filename, MIME, media metadata, instance size, and user quota rules. Image handling can remove EXIF data for privacy, while motion-media groups and memo-content references remain protected during deletion. Chunked uploads bind a temporary session to its owner, enforce ordered writes with safe retries, and recheck access and quota at finalization.
Content replacement is limited to a stored attachment that the caller can manage and that is not an external link or part of a motion photo. The replacement keeps the attachment name, creator, memo, and creation time, while its filename, type, size, and media metadata come from the new file. The quota check uses the replaced file's size when measuring the owner's new storage use. The service commits the new content before removing the old content, so a retry can report the committed attachment without applying an older upload over a newer replacement.
References: proto/…/attachment_service.proto• L15-72 proto/…/attachment_service.proto• L74-126 proto/…/attachment_service.proto• L207-267 proto/…/attachment_service.pb.go• L856-930 proto/…/openapi.yaml• L121-261 server/…/attachment_service.go• L73-180 server/…/attachment_service.go• L420-660 server/…/attachment_upload.go• L46-213 server/…/attachment_service_replace.go• L21-267 server/…/attachment_service_replace_test.go• L17-226
Instance and usage services
InstanceService exposes the instance profile, access mode, settings, email checks, configuration status, and administrator usage statistics. Settings cover branding, storage, notifications, AI providers, registration policy, access policy, tag metadata, and usage limits. Clients can read one setting or batch up to 100 settings in request order. An update replaces one whole setting; deployment-owned settings and configuration-managed fields stay outside API control. Reaction choice is no longer an instance setting.
Settings use the persistence model as a private store shape and the API model as a public shape. The handler validates the public value, converts it to the store value, preserves omitted write-only credentials, and converts the stored result back. Storage, notification, and usage-limit settings require an administrator. AI reads require a signed-in user and hide transcription defaults from non-admin users. The email test uses supplied settings or the stored settings and checks the recipient before it calls the mail service.
Usage limits define a default or user-specific bound for memo count, memo content bytes, total stored upload bytes, or one upload's size. Administrators manage these limits through the USAGE_LIMITS instance setting. User names in that setting resolve to stored user IDs on write and back to canonical resource names on read. Users and administrators can read the effective limits with the user's usage report. A user-specific limit replaces the default for that metric, and zero means unlimited. Replacing an attachment checks the new size against the same owner's limits while removing the old size from the storage calculation. A failed limit lookup rejects the product action instead of disabling the limit by accident.
AIService provides authenticated audio transcription through the configured instance provider. It validates the supplied audio and returns text without making the audio part of the stored product state.
References: proto/…/instance_service.proto• L17-67 proto/…/instance_service.proto• L125-177 proto/…/instance_service.proto• L407-499 proto/…/user_service.proto• L687-740 proto/…/instance_setting.proto• L9-34 proto/…/instance_setting.proto• L248-320 server/…/instance_service.go• L42-199 server/…/instance_service.go• L202-328 server/…/instance_service.go• L342-405 server/…/instance_service_usage_limits.go• L18-94 server/…/instance_service_validation.go• L18-121 server/…/instance_service_converters.go• L13-41 server/…/usage_limit.go• L13-57 server/…/user_service_usage.go• L15-64 server/…/ai_service.go• L47-120
Declarative configuration status
The configuration status API gives administrators a safe view of resources managed by declarative configuration. Configuration documents can declare identity providers, instance settings, bootstrap users, and linked identities, with lifecycle rules for ignored fields, destruction, and write-only values. The API reports the last apply, managed resources, source files, and managed or ignored fields; it does not return configured values. The server stores this ownership state so every API replica can reject direct changes to managed fields even when it did not load the configuration files.
Configuration-managed writes return FAILED_PRECONDITION with resource, source, and field metadata. The same ownership checks cover creating, deleting, renaming, or changing resources that a managed resource references. This keeps API actions consistent with the desired state described by declarative configuration management.
References: proto/…/configuration.proto• L12-65 proto/…/configuration.proto• L68-143 proto/…/instance_service.proto• L63-67 proto/…/instance_service.proto• L570-604 proto/…/instance_setting.proto• L273-320 server/…/instance_service_configuration.go• L19-120 server/…/instance_service.go• L297-328 server/…/user_service.go• L340-373 server/…/user_service.go• L486-531 server/…/user_service_identities.go• L39-141 server/…/idp_service.go• L19-45 server/…/instance_service_configuration_test.go• L54-218
Change checklist
When these files or sections are changed, remember to consider these:
- A changed protobuf service, RPC, field, route annotation, or package name requires regenerated Go, gRPC, Gateway, Connect, OpenAPI, and web TypeScript outputs.
- A changed store protobuf requires regenerated store bindings and a review of every API-to-store converter that reads or writes that shape.
- A new or moved RPC must be registered in both Gateway and Connect. Preserve the unversioned procedure and REST path names.
- A changed field behavior must remain aligned with response conversion and secret redaction. Do not expose passwords, tokens, API keys, webhook secrets, or provider secrets.
- A changed resource name, filter, sort field, or page-token shape must stay aligned with the handler and store query contract. Saved memo views reuse the memo filter contract.
- A changed user resource-name rule must be checked against user lookup, usage-limit entries, declarative resource references, linked resources, and configuration ownership checks.
- A changed memo payload field must stay aligned with content processing, store persistence, API conversion, and filterable derived values.
- A changed anonymous-access or private-instance rule must update both the public method map and its bootstrap subset. Review server runtime and routing for the wider request entry path.
- A changed challenge, request-size, or rate-limit contract must preserve metadata and HTTP headers across REST and Connect. A quota refusal must remain distinct from a retryable rate refusal.
- A changed usage-limit setting or effective-limit rule must stay aligned across instance settings,
GetUserUsage, memo creation, memo edits, comments, inline uploads, chunked uploads, attachment replacement, and memo import. - A changed configuration resource or lifecycle rule must stay aligned across plan/apply state, configuration status, managed-field checks, ignored fields, write-only versioning, and API error metadata.
- A changed memo visibility or space rule must be checked for direct reads, lists, comments, relations, reactions, shares, linked attachments, and placement updates.
- A changed chunked upload contract must preserve owner binding, offset retries, total-size checks, expiry, request limits, and finalization behavior for new attachments, attachment replacement, and memo import.
- A changed attachment contract must preserve MIME handling, immutable media metadata, motion-media grouping, content replacement identity rules, storage cleanup, and memo-content reference checks.
- A changed account role, password, or state rule must preserve password-bound token invalidation, session revocation, and the last-instance-admin and active-space-admin safeguards.
- A changed SSO identity rule must preserve unique provider-subject binding, registration policy, safe username fallback, and protection against email-based account takeover.
- A changed export or import contract must stay aligned across the file-delivery route, archive manifest, attachment content, chunk session ownership, conflict policy, and quota accounting.
- A removed or renamed instance setting must stay aligned across the public enum, store enum, configuration-file compatibility rules, generated OpenAPI schema, and setting converters. Do not reintroduce a removed setting through a generated binding.
- A changed user statistics field must stay aligned across the public protobuf, generated transport bindings, access scope, and the distinction between memo-filtered statistics and persisted attachment totals.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A protobuf change lands without regenerated bindings | A transport or client uses an old route, type, or RPC shape | Buf generation produces all declared API and store outputs. |
| API and store protobuf shapes drift | A handler reads the wrong setting or loses derived memo data at the persistence boundary | The API conversion layer maps the two generated models and validates the public value before storage. |
| A service is registered in only one transport | REST and Connect expose different product behavior | Gateway and Connect registration use the same service set. |
| An old versioned route is used after the migration window | The client receives 410 Gone instead of a product response | The changelog defines the route change and the server gives a migration error. |
| Gateway route resolution fails | Anonymous access could bypass a method policy | Unresolved procedures fail closed before the handler runs. |
| The access policy store fails while checking anonymous access | The gateway returns an internal error instead of treating the caller as anonymous or returning a misleading 401 | Authorization error mapping distinguishes ErrUnauthenticated from internal failures. |
| An anonymous caller reaches a protected method | The request is rejected before resource data is read | The shared authorizer checks authentication and instance access mode. |
| A challenge token is missing or invalid | A protected sign-in or account action is refused without consuming a normal product result | Challenge errors use a stable precondition detail so clients can show the challenge. |
| A batch or inline request exceeds its body limit | The request is rejected before the handler can finish | Transport limits distinguish ordinary bodies, inline content, and chunks, including compressed Connect messages. |
| A caller sends an invalid resource name, filter, or page token | The request returns InvalidArgument without a store change | Resource, filter, and token validation run before the product action. |
| A memo is returned without checking related access | A response can disclose a parent, space, relation, or attachment | Conversion follows the memo and related-resource access decisions. |
| A memo payload is missing or stale | Tags, location, snippets, or content properties are absent or wrong in API responses and filters | Content processing stores the payload and conversion maps it into the public memo. |
| A usage-limit check fails open | A database or configuration problem lets a user exceed a limit | Limit-check errors become Internal; only a valid refusal becomes quota exhaustion. |
| A quota refusal is treated as a retryable rate refusal | A client waits instead of freeing space or changing the limit | Quota errors carry QUOTA_EXCEEDED details and no RetryInfo. |
| A direct write changes a configuration-managed field | The API state drifts from the declared configuration | Ownership state is checked in the store and the response names the managed resource and fields. |
| A managed user is renamed or deleted while another managed resource names it | Usage limits or other configuration references point to the wrong or missing user | Reference checks refuse the change until configuration releases or updates the reference. |
| A setting update uses an empty credential after changing its connection identity | The service cannot connect, or an intended secret change is silently incomplete | Empty credentials are preserved only when the connection identity is unchanged. |
| A removed instance setting remains in a client or configuration file | The client sends an unsupported key or the configuration apply rejects an old declaration | The changelog records the break, the public and store schemas reserve the old value, and compatibility data rejects the old form. |
| A non-admin reads usage-limit or protected setting data | User names, limits, or credentials become visible to an unauthorized caller | Instance-setting access checks require an administrator and response conversion redacts secrets. |
| A chunk uses the wrong owner, offset, or final size | Upload or import cannot continue or finalize | Sessions bind the user and check committed offsets and total size. |
| A replacement targets an external, motion-photo, deleted, or no-longer-manageable attachment | The upload cannot safely preserve the attachment's product identity | Replacement validation checks the target at start and finish and rejects unsupported targets. |
| A replacement retry runs after a newer replacement committed | An older upload could overwrite newer content or delete the current file | Per-attachment replacement coordination reports the committed result and deletes only content no longer referenced. |
| A secret or input-only field is copied into a response | Credentials become readable through a normal API call | Protobuf field behavior and service conversion keep secret values write-only. |
| A final attachment or memo write is refused by quota | Temporary upload data or a staged session could remain usable | Final quota checks revoke refused attachment uploads and import sessions remain bounded. |
| Storage cleanup fails after attachment, user, or memo deletion | Database rows and managed files can become out of step | Cleanup failure is reported as a distinct post-delete error for repair. |
| A password changes without token and session invalidation | Old access or refresh credentials continue to act as the user | Access tokens bind to password state and other refresh sessions are revoked. |
| The last active administrator is demoted, archived, or deleted | The instance loses its required administrator | User writes return FAILED_PRECONDITION until another administrator exists. |
| An SSO subject is empty, already linked, or claimed during provisioning | Sign-in can create an unusable account or link an external identity to the wrong local user | Subject validation, unique identity storage, registration checks, and concurrent reconciliation protect the link. |
| An export reads another user's memo or fails after the response starts | The archive discloses data or becomes a truncated download | Export selection is scoped to the owner and loads memo rows before writing the archive. |
| An import session is reused by another user or finishes at the wrong offset | An archive is mixed, rejected, or applied to the wrong account | Sessions bind to the caller and enforce ordered writes, total size, expiry, and bounded chunks. |
| A user statistics field is added to the schema without matching access rules | A caller can infer storage data outside the intended owner scope | The public field's output scope remains enforced by the service before response conversion. |
Key files
| File | Why to read it |
|---|---|
| proto/…/README.md and proto/…/CHANGELOG.md | API design rules, field stability rules, and the unversioned route and metric migration. |
| proto/…/configuration.proto | Declarative resource declarations, lifecycle rules, plans, removals, and safe configuration status shapes. |
| proto/…/memo_service.proto | Memo resources, visibility, relationships, sharing, pagination, and HTTP routes. |
| proto/…/user_service.proto | Account resources, usage reports, saved views, notifications, linked identities, personal access tokens, user statistics, and memo import. |
| proto/…/attachment_service.proto | Attachment resources, media metadata, resumable upload, and content replacement contract. |
| proto/…/space_service.proto | Space membership, roles, invitations, and memo placement boundary. |
| proto/…/instance_service.proto | Instance profile, access mode, settings, limits, configuration status, and setting access rules. |
| proto/…/instance_setting.proto and proto/…/memo.proto | Persistence-side setting and memo payload shapes that sit behind the public API. |
| proto/…/auth_service.proto and proto/…/idp_service.proto | Session lifecycle and external identity provider contract. |
| proto/buf.gen.yaml | The generated consumers that must stay aligned with the protobuf source. |
| proto/…/user_service.pb.go, proto/…/user_service_grpc.pb.go, proto/…/user_service.connect.go, and proto/…/user_service.pb.gw.go | The generated user messages, statistics field, transport procedures, REST mapping, and server interfaces. |
| proto/…/instance_service.pb.go, proto/…/attachment_service.pb.go, and proto/…/openapi.yaml | The generated instance and attachment messages, setting keys, REST paths, and schemas exposed to clients. |
| proto/…/instance_setting.pb.go | The generated persistence model for settings, usage limits, and configuration state. |
| server/…/api.go | Shared service dependencies, transport registration, procedure routing, request limits, route migration, and Gateway responses. |
| server/…/acl_config.go, server/…/authz.go, and server/…/acl_config_test.go | Public endpoints, private-instance bootstrap access, authentication, shared request admission, and the tested error classes. |
| server/…/connect_handler.go and server/…/connect_services.go | Connect service registration, delegation, response wrapping, and error conversion. |
| server/…/resource_name.go and server/…/user_resource_name.go | The resource-name rules that connect protobuf paths to store lookups. |
| server/…/memo_service.go, server/…/memo_service_comments.go, and server/…/memo_create_helpers.go | Memo actions, comment behavior, quota checks, validation, mutation, and side effects. |
| server/…/memo_service_converter.go | Conversion of stored memos and related data into access-aware public responses. |
| server/…/space_service.go and server/…/space_service_notifications.go | Space governance and invitation notification effects. |
| server/…/attachment_service.go, server/…/attachment_upload.go, and server/…/attachment_service_replace.go | Attachment validation, quota checks, chunked upload, content replacement, deletion safety, and the managed file boundary. |
| server/…/attachment_service_replace_test.go | Contract checks for safe replacement retries and cleanup after a committed replacement. |
| server/…/instance_service.go, server/…/instance_service_configuration.go, server/…/instance_service_usage_limits.go, and server/…/instance_service_validation.go | Instance settings, protected values, configuration ownership, validation, usage-limit configuration, and effective quota behavior. |
| server/…/instance_service_converters.go | Redaction of stored credentials and conversion of public settings. |
| server/…/usage_limit.go and server/…/user_service_usage.go | Quota enforcement and user-facing usage reports. |
| server/…/user_service.go, server/…/user_service_settings.go, and server/…/user_service_memo_transfer.go | Account governance, private user settings, and staged memo import. |
| server/…/user_service_memo_export.go | The user-scoped archive data and file-writing boundary used by file delivery. |
| server/…/auth_service_sso.go and server/…/sso_username.go | External identity resolution, safe account provisioning, and username fallback. |
| server/…/user_service_identities.go | Linked identity and personal access token resource behavior. |
| server/…/idp_service.go | Identity-provider validation, administration, secret handling, and configuration ownership checks. |
| server/…/instance_service_configuration_test.go and server/…/memo_export_test.go | Contract checks for managed-resource protection and archive export/import behavior. |