Usage limits and quotas
Usage limits let an instance control how much memo and file data each user can create or keep. Administrators set an ordered policy for all users and named users. The server measures current use when a request needs a decision, blocks work that would exceed the active limit, and exposes the same state to users and settings screens.
Quota model
Limit scopes
A usage limit is a ceiling for one metric in one ordered entry. An entry names users or applies to all users. The first entry that matches a user wins for all four metrics, so a named-user entry replaces the whole default entry rather than only selected fields.
The value 0 means unlimited. This lets an administrator remove a restriction without changing the resource shape. Limits apply to administrators as well as regular users.
References: proto/…/instance_setting.proto• L247-269 core/…/usagelimit.go• L41-63 store/usage_limit.go• L52-113
Usage metrics
The system measures four kinds of use. Each metric protects a different shared resource or user action.
| Metric | Meaning | Main effect |
|---|---|---|
MEMOS | Memos created by the user. Comments count as memos. Archived memos and memos in Spaces also count. | Blocks new memo and comment creation. |
MEMO_CONTENT_BYTES | The size of one memo's content. | Blocks memo content that is too large. |
STORAGE_BYTES | Persisted bytes in the user's uploads. Unattached uploads count. External links do not count. | Blocks an upload when the resulting stored total would be too large. |
UPLOAD_BYTES | Bytes in one file. | Blocks a file that is too large even when the user's total storage has room. |
The memo and storage figures are current totals. The content and per-file metrics describe the request itself rather than a stored total.
References: proto/…/instance_setting.proto• L260-268 core/…/usagelimit.go• L104-177 proto/…/user_service.proto• L687-729
Effective limits
For each user, the server resolves one effective entry. It scans the ordered list and uses the first entry that names the user. If no named entry matches, it uses the all-users entry. If no entry matches, every metric is unlimited.
This resolution is visible in the account usage response through the effective limit fields and the entry index. The index identifies which ordered policy entry applies, while an index of -1 means that no configured entry applies.
The following flow shows how an ordered policy becomes the decision used by a request.
flowchart LR
A[Ordered limit entries] --> C[Find first matching entry]
B[All-users entry] --> C
C --> D[Measure current use]
D --> E{Within limit?}
E -->|Yes| F[Continue request]
E -->|No| G[Return quota refusal]
References: core/…/usagelimit.go• L51-63 core/…/usagelimit.go• L187-201 server/…/user_service_usage.go• L47-64 web/…/UsageLimitsSection.tsx• L40-44
Usage measurement
Live usage
The server counts memo rows and sums stored attachment bytes when it needs a usage decision or a usage display. It measures memo content and file size from the request being checked. It does not maintain a separate counter. This avoids stale quota state, but concurrent requests can pass checks before either request changes the stored total.
When no limit applies to a check, the server skips the related count or sum. Lowering a limit never deletes existing memos or files. It only prevents new work until the measured use is below the new ceiling.
References: core/…/usagelimit.go• L104-177 core/…/usagelimit.go• L187-201 docs/…/user-usage-limits.md• L42-46
Enforcement points
Quota checks sit at the point where the server can still refuse the operation without leaving partial user work. Memo creation and comments check the memo count. Memo content checks compare the submitted content size. One-shot and chunked attachment uploads check file size and total storage. Chunked uploads check at both start and finish because limits or other uploads can change while a file is in progress.
The same file-size check also protects binary attachments created during memo import. External-link attachments do not consume stored bytes and therefore do not use the storage-byte total.
The request path follows a common pattern:
- Resolve the user's effective entry.
- Measure the needed current value or inspect the submitted content or file size.
- Refuse the operation if the new state would exceed a limit.
- Continue to the normal write path when the check succeeds.
References: server/…/usage_limit.go• L13-50 server/…/memo_service.go• L25-54 server/…/memo_service_comments.go• L60-69 server/…/attachment_service.go• L163-180 server/…/attachment_upload.go• L105-140 server/…/attachment_upload.go• L158-184 server/…/user_service_memo_import.go• L487-517
API contracts
Administrative interface
The InstanceService exposes usage limits as the USAGE_LIMITS instance setting. Only an administrator can read or replace this setting. The API names users with user resource names, while the stored policy keeps stable user IDs.
An update replaces the complete ordered list. The server validates the list and resolves every named user before it stores the setting. A malformed user resource name returns INVALID_ARGUMENT, and a user that does not exist returns NOT_FOUND. When a referenced user no longer exists, reads omit that user from the API view. Deployment-provided settings are read-only at runtime. The setting allows at most 100 entries and can name at most 1,000 users across those entries.
| Operation | Purpose |
|---|---|
GetInstanceSetting | Read the ordered usage-limit policy. |
UpdateInstanceSetting | Replace the ordered policy when deployment configuration does not own it. |
References: proto/…/instance_service.proto• L1-48 server/…/instance_service.go• L143-169 server/…/instance_service.go• L200-290 server/…/instance_service_usage_limits.go• L17-95
Account usage interface
UserService.GetUserUsage returns the user's current memo count and stored bytes. It also returns the effective limit for memo count, memo content size, storage bytes, and upload bytes. The response includes the index of the entry that supplies those limits. The user can read their own resource. An administrator can read any user's resource.
The resource is users/{user}/usage. An unset or zero limit means unlimited. A limit index of -1 means that no policy entry applies. This contract gives account screens and other clients enough state to show both actual use and the policy that governs it.
References: proto/…/user_service.proto• L687-740 server/…/user_service_usage.go• L15-64 web/…/UsageSection.tsx• L8-45
Refusal contract
When a memo or upload would exceed a usage limit, the API returns RESOURCE_EXHAUSTED with the message quota exceeded. The error uses QUOTA_EXCEEDED in the memos.api error domain and reports the metric, limit, and measured usage. It also includes a quota violation that identifies the affected user.
Quota refusals do not include retry information. They do not recover by waiting. The user must reduce use or an administrator must raise or remove the limit. A check or database failure instead returns an internal error, so an infrastructure problem cannot silently disable enforcement.
The API and web client distinguish this contract from a temporary rate-limit refusal:
| Refusal | Recovery | Client signal |
|---|---|---|
| Usage quota | Free space, reduce the file or memo, or change the configured limit. | QUOTA_EXCEEDED; no retry delay. |
| Request rate limit | Wait for the advertised window to pass. | RATE_LIMITED; retry details may be present. |
References: server/…/ratelimit.go• L75-130 server/…/usage_limit.go• L35-51 web/…/error.ts• L73-106
Settings interfaces
Account settings
The My Account view shows usage only when at least one limit applies to the current user. It presents memo use and storage use against their active ceilings. A memo-content limit appears as a maximum content size, and a per-file limit appears as a file-size value rather than as current usage because both apply to one request.
The account UI reads the user usage resource and formats byte values for people. A quota error keeps the cause visible: memo errors ask the user to delete memos, storage errors show current storage use, and file errors show the per-file ceiling.
References: web/…/MyAccountSection.tsx• L72-76 web/…/UsageSection.tsx• L8-45 web/…/usageLimitValues.ts• L62-65 web/…/error.ts• L83-106
Administrative settings
The admin Usage limits view presents the ordered policy as one table. Named-user entries appear before the all-users entry. The first matching named entry controls a user, so a later entry may never apply to a user already matched by an earlier row. The view marks an entry as never applying when all of its users already match earlier entries.
An administrator can edit the all-users row, add or edit a named-user entry, choose users from the instance user list, move named entries, or remove an entry. New entries start immediately above the all-users row, and their position can then change which users they control. The form covers memo count, memo content size, total storage, and per-file size. A new entry starts with the all-users values, so leaving a field unchanged keeps that default. Clearing a field means no limit in that entry. Memo content values use KiB in the form. Other byte limits use MiB. Stored values remain bytes.
When deployment configuration manages the setting, the view shows that state and disables changes. The database policy remains visible, but runtime administration cannot replace it.
References: web/…/UsageLimitsSection.tsx• L40-63 web/…/UsageLimitsSection.tsx• L130-246 web/…/UsageLimitDialog.tsx• L35-85 web/…/UsageLimitDialog.tsx• L97-175 web/…/usageLimitValues.ts• L6-60
Quota state
Instance configuration
All limits share the USAGE_LIMITS instance setting. The instance settings API owns this state. A deployment can provide the setting as part of instance configuration. When it does, runtime updates are rejected.
The stored state validates the entry order, user IDs, non-negative values, and the size caps. Reads for enforcement use the current setting so a change reaches the next check on each replica. If the setting is absent, the instance uses one all-users entry with a 32 MiB per-file limit and an 8 KiB memo-content limit. A stored setting replaces that built-in policy as a whole. It must contain an all-users entry as its last entry.
References: proto/…/instance_setting.proto• L247-269 store/usage_limit.go• L13-131 server/…/instance_service.go• L214-287
User lifecycle
Limits refer to a stable user ID rather than a username. A username change therefore keeps the user's limits. When a user is removed, the system removes or ignores the limits that refer to that user so stale entries do not remain active or consume the instance limit budget.
User removal updates the shared policy only when the stored value is still the one that was read. If another writer changed the policy first, the cleanup retries a bounded number of times and reports a write conflict if it cannot safely apply the change.
References: proto/…/instance_setting.proto• L253-259 store/usage_limit.go• L27-37 store/usage_limit.go• L134-186 server/…/instance_service_usage_limits.go• L31-49
Related pages
- Identity, authentication, and access
- Identity provider integration
- Web settings and account management
- API contracts and services
- Persistence and data evolution
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the four metric meanings aligned across the store schema, live measurement, API fields, form units, and web labels.
- Preserve ordered first-match resolution when changing limit reads, admin forms, or account usage responses.
- Keep memo content limits in bytes on the service boundary and KiB in the admin form.
- Keep
QUOTA_EXCEEDEDdistinct fromRATE_LIMITED, including the absence of retry details for quota errors. - Update both the start and finish checks when changing chunked attachment upload behavior.
- Keep deployment-provided limits read-only through every runtime write path and visible as managed in the admin view.
- Keep user deletion and username changes consistent with limits stored by user ID.
- Keep the all-users entry last and within the store's entry and user caps.
- Preserve conditional writes and bounded retries when user lifecycle actions modify the shared policy.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A memo count or storage sum cannot be read | The request fails with INTERNAL instead of proceeding without a limit. | Quota checks fail closed. |
| A chunked upload passes its start check but the limit changes before finish | The upload is refused at finish and is not saved. | The upload is checked at both stages. |
| Memo content exceeds the active content-size limit | The memo request is refused before the normal write path. | The service checks submitted content size and maps the refusal to QUOTA_EXCEEDED. |
| A named-user entry is removed | The user falls through to the next matching entry, usually the all-users entry. | Effective-limit resolution scans entries in order. |
| An admin lowers a limit below current use | Existing data stays intact, but new matching work is refused. | Usage is measured live; limits do not delete data. |
| Runtime code tries to change deployment-provided limits | The write fails with FAILED_PRECONDITION. | Deployment configuration has precedence over database state. |
| A policy names a user that does not exist | The update fails instead of creating a policy that cannot be resolved. | The API resolves every user name before storing the setting. |
| User deletion races with another policy update | The deletion may report a usage-limit write conflict instead of overwriting the newer policy. | Cleanup uses conditional writes with bounded retries. |
Key files
| File | Why to read it |
|---|---|
| core/…/usagelimit.go | Defines ordered effective-limit resolution and live usage reads. |
| server/…/usage_limit.go | Defines enforcement entry points and conversion of quota decisions into service errors. |
| server/…/instance_service.go | Defines administrator access to the instance setting and deployment-owned write protection. |
| server/…/instance_service_usage_limits.go | Converts API user names to stored user IDs and back. |
| server/…/user_service_usage.go | Defines the account-facing usage resource and its access rules. |
| server/…/ratelimit.go | Defines the wire-level difference between quota and temporary rate-limit errors. |
| store/usage_limit.go | Defines shared instance state, default limits, validation, deployment precedence, and user cleanup. |
| proto/…/instance_setting.proto | Defines the stored policy model and metric meanings. |
| proto/…/user_service.proto | Defines the user usage resource and effective-limit fields. |
| web/…/UsageSection.tsx | Shows how users see current usage and request-size limits. |
| web/…/UsageLimitsSection.tsx | Shows how administrators view, order, and manage the policy entries. |
| web/…/UsageLimitDialog.tsx | Shows how administrators select users and edit metric values. |
| web/…/usageLimitValues.ts | Defines the units and conversion used by limit forms and displays. |
| web/…/error.ts | Shows how quota metadata becomes a user-facing message. |
| server/…/usage_limit_service_test.go | Verifies the API permissions, policy order, enforcement, and refusal contract. |
| store/…/usage_limit_test.go | Verifies defaults, policy validation, conditional updates, and user cleanup. |