Documentation
¶
Overview ¶
Package apilimit combines shared request budgets with bounded local work.
Admission has two halves. Request budgets are fixed one-minute windows counted in the metadata store, so replicas that share it share the rates, and a request charges all of its budgets or none. Concurrency permits bound the work in one process, without a waiting queue: a request that finds no free permit is refused at once.
Role ¶
platform layer: API admission, with request budgets shared across replicas and concurrency permits per process. Admission belongs to no module, so it sits in the platform. The composition root builds one Service from the api section of the configuration, and the router's request-limit middleware (app/limits.go) calls it for every request but the health probes: Enter and Authentication before credentials are verified, Admit and, for expensive work, EnterExpensive once the principal and the resources are known, and EnterRecovery on the administrative recovery routes. The request budget port and its values are declared here, by the package that charges through them, and New takes Store, the one method it calls, so that the package imports no store (decision 0044, "Narrowing"); the metadata store and the platform's store satisfy it, and the platform's store adapters (platform/store/sql and platform/store/inmem) implement RequestBudgetStore. The package imports the kernel and the standard library.
Inputs ¶
- Options, the api section of the configuration, with Default as the initial policy: the per-minute rates for authentication, the whole service, each principal, project and repository, and expensive work in total and per principal; the concurrency limits in total, for expensive work and per principal; the counter capacity, MaxKeys; and the budget and expensive-work timeouts. Validate bounds them even while admission is disabled.
- A Store, whose RequestBudgets is the shared budget store, and a clock (time.Now when nil).
- Per request, the context, and for Admit a Scope: the authenticated principal, the resolved project and repository, and whether the work is expensive.
Outputs ¶
- Service, with Enter, EnterExpensive, Authentication, Admit, EnterRecovery and Options; New returns a nil Service when admission is disabled.
- Decision, the caller's own quota and when it resets, which the HTTP boundary turns into rate limit headers; Scope; the sentinels ErrInvalid and ErrBusy.
- The port: RequestBudgetStore, with RequestBudget, BudgetRequest and its Validate, BudgetBalance, BudgetDecision and ErrBudgetCapacity.
Invariants ¶
- Backend errors never grant admission, and there is no per-process fallback: a budget store that fails or misses BudgetTimeout refuses the request.
- A refusal charges none of the budgets, so a rejected request uses up no other principal's allowance.
- Budget keys are SHA-256 digests of server-owned policy names and authenticated scope, never client labels.
- Permits are released only after the handler returns, also when its context is canceled; a release function acts once however often it is called.
- The recovery reserve does not depend on budget capacity: its two concurrent requests and sixty attempts a minute are counted in this process's memory.
References ¶
- Decision 0043: docs/research/decisions/0043-api-reliability.md ("Incoming request budgets and expensive work": the policy, its defaults and its failure modes; "Temporary restrictions and administrative recovery": the recovery reserve).
- Decision 0044: docs/research/decisions/0044-modular-monolith-migration.md ("Narrowing"; platform/apilimit is one of the new packages the target layout does not name).
- Target layout: docs/research/architecture-options/5-modular-monolith.md, line 127 (the platform tree, which does not list this package) and lines 40 and 41 (the platform imports no module and no gateway).
- Plan: docs/implementation/plan.md#p9d-modular-monolith-migration, epic PLT (https://github.com/weaveplatform/artifactweave/issues/938).
- https://github.com/weaveplatform/artifactweave/issues/890
- https://github.com/weaveplatform/artifactweave/issues/987
Status ¶
Implemented with decision 0043 (issue 890, pull request 905) and released in v0.2.0, the P9c release: request budgets shared through the metadata store, which declared the port; per-process and expensive permits without a waiting queue; and the recovery reserve. Moved here in P9d: New takes Store, and the port and its values are declared here.
Testing ¶
- limit_test.go: TestUnitSharedRatesAndScopes (two services share rates through one store; the principal, expensive, project and repository budgets; the window reset), TestUnitBoundedConcurrency (ordinary, expensive and per-principal permits, releases that act once, and canceled contexts), TestUnitBudgetFailureIsClosedAndBounded (a stalled budget store refuses within BudgetTimeout) and TestUnitAPIPolicyValidation (the bounds, a missing store and disabled admission).
- recovery_test.go: TestUnitRecoveryReservedAllowance (two concurrent requests and sixty a minute, the window reset and a canceled context).
The tests build their services over the platform's in-memory store. The platform's request budget contract (the RequestBudgets and RequestBudgetBoundedPruning subtests of platform/store/storetest) runs on the platform's in-memory and SQLite stores and on the metadata store's in-memory, SQLite and PostgreSQL stores, the router's request limit tests (app/limits_test.go) run against this package.
Index ¶
- Variables
- type BudgetBalance
- type BudgetDecision
- type BudgetRequest
- type Decision
- type Options
- type RequestBudget
- type RequestBudgetStore
- type Scope
- type Service
- func (s *Service) Admit(ctx context.Context, scope Scope) (Decision, error)
- func (s *Service) Authentication(ctx context.Context) (Decision, error)
- func (s *Service) Enter(ctx context.Context) (func(), error)
- func (s *Service) EnterExpensive(ctx context.Context, principal string) (func(), error)
- func (s *Service) EnterRecovery(ctx context.Context) (func(), Decision, error)
- func (s *Service) Options() Options
- type Store
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalid reports options outside their bounds, from Validate and New, // or limits enabled without a store to share rates through, from New. ErrInvalid = errors.New("api limit: invalid policy") // ErrBusy reports that the permits a request needs are all held: this // process's ordinary or expensive permits, a principal's share of the // expensive ones, or the two of the recovery reserve. Nothing waits for a // permit, so the request is refused at once; the HTTP boundary tells it // apart from a failed budget store and answers 429, not 503. ErrBusy = errors.New("api limit: concurrent work capacity exhausted") )
var ErrBudgetCapacity = errors.New("store: request budget capacity exhausted")
ErrBudgetCapacity means the bounded budget table cannot admit another key. The budget stores return it, so its text starts "store:", as their other errors do.
Functions ¶
This section is empty.
Types ¶
type BudgetBalance ¶
BudgetBalance is one request budget's remaining requests and reset instant.
type BudgetDecision ¶
type BudgetDecision struct {
Allowed bool
Balances []BudgetBalance
}
BudgetDecision reports balances in request order. A refusal charges none of the budgets; balances then describe their current, unmodified usage.
type BudgetRequest ¶
type BudgetRequest struct {
Budgets []RequestBudget
Now time.Time
MaxKeys int
}
BudgetRequest atomically charges one request against all its budgets. MaxKeys caps retained counters across the shared store (at most 65536). Replicas must use the same capacity/policies and synchronized clocks.
func (BudgetRequest) Validate ¶
func (r BudgetRequest) Validate() error
Validate bounds both the persisted state and the work in one admission. A request out of bounds gives an error wrapping kernel.ErrInvalid, the metadata store's invalid record, not this package's ErrInvalid, which reports an invalid policy.
type Decision ¶
type Decision struct {
Allowed bool
Policy string
Limit int64
Remaining int64
Reset time.Time
ResetAfter time.Duration
RetryAfter time.Duration
}
Decision exposes only the caller's quota, not other principals' shared usage.
type Options ¶
type Options struct {
Enabled bool `yaml:"enabled"`
AuthenticationPerMinute int64 `yaml:"authentication_per_minute"`
GlobalPerMinute int64 `yaml:"global_per_minute"`
PrincipalPerMinute int64 `yaml:"principal_per_minute"`
ProjectPerMinute int64 `yaml:"project_per_minute"`
RepositoryPerMinute int64 `yaml:"repository_per_minute"`
ExpensivePerMinute int64 `yaml:"expensive_per_minute"`
ExpensivePrincipalPerMinute int64 `yaml:"expensive_principal_per_minute"`
MaxConcurrent int `yaml:"max_concurrent"`
ExpensiveConcurrent int `yaml:"expensive_concurrent"`
ExpensivePrincipalConcurrent int `yaml:"expensive_principal_concurrent"`
MaxKeys int `yaml:"max_keys"`
BudgetTimeout time.Duration `yaml:"budget_timeout"`
ExpensiveTimeout time.Duration `yaml:"expensive_timeout"`
}
Options is immutable after constructing a Service. Rates are shared across replicas; concurrency limits apply to one process and have no waiting queue.
type RequestBudget ¶
RequestBudget selects a fixed-window request counter. Key is a lowercase SHA-256 digest of a server-owned policy name and its authenticated scope. Reset is the end of the current window; an active stored window is never shortened by another replica with an older clock or policy configuration.
type RequestBudgetStore ¶
type RequestBudgetStore interface {
// Take atomically tests every budget and increments all or none. Expired
// counters are reclaimed in bounded batches. Backend errors never grant
// admission; callers must not replace this with a per-process fallback.
Take(ctx context.Context, request BudgetRequest) (BudgetDecision, error)
}
RequestBudgetStore enforces request rates across instances sharing metadata. It does not count simultaneous work; Service holds the concurrency permits, per process.
type Scope ¶
Scope carries authenticated and resolved identities, never arbitrary client labels. Empty resource scopes mean the request is not bound to one resource.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service owns one process's permits and shares rates through metadata. It starts no goroutines. Release must run after the handler actually returns, including when its context is canceled; never release early while work runs.
func New ¶
New validates options and returns a Service that charges the request budgets of st, reading time from now (time.Now when nil). Options that Validate refuses give an error wrapping ErrInvalid, even when admission is disabled. With admission disabled New returns a nil Service and a nil error, so the caller mounts no limits. Enabled limits without st give an error wrapping ErrInvalid: rates are shared only through metadata, and there is no per-process fallback.
func (*Service) Admit ¶
Admit charges the accepted request's global, principal, cost and resolved resource scopes atomically. Rejections cannot consume another user's budget.
func (*Service) Authentication ¶
Authentication charges a shared coarse budget before credential verification.
func (*Service) EnterExpensive ¶
EnterExpensive refuses excess work immediately; no caller can fill a pending queue, and one principal cannot occupy every expensive permit by default.
func (*Service) EnterRecovery ¶
EnterRecovery reserves two requests and sixty authentication attempts per minute in this process for the narrowly mounted administrative recovery API. Its constant-size state is independent of metadata budget capacity/failure. Recovery still requires valid administrator credentials and a working store.
type Store ¶
type Store interface {
RequestBudgets() RequestBudgetStore
}
Store is what admission needs from persistence: the request budgets that Authentication and Admit charge. New reads RequestBudgets once and charges through what it returns, so services over one store share its rates, as replicas over one metadata database do; the metadata store satisfies it.