apilimit

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 8 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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")
)
View Source
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

type BudgetBalance struct {
	Remaining int64
	Reset     time.Time
}

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.

func Default

func Default() Options

Default returns the initial operational policy, including optional resource scopes once the HTTP boundary has resolved their existence.

func (Options) Validate

func (o Options) Validate() error

Validate rejects unsafe bounds even while disabled, so enabling a saved configuration does not expose a latent unbounded policy.

type RequestBudget

type RequestBudget struct {
	Key   string
	Limit int64
	Reset time.Time
}

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

type Scope struct {
	Principal, Project, Repository string
	Expensive                      bool
}

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

func New(st Store, options Options, now func() time.Time) (*Service, error)

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

func (s *Service) Admit(ctx context.Context, scope Scope) (Decision, error)

Admit charges the accepted request's global, principal, cost and resolved resource scopes atomically. Rejections cannot consume another user's budget.

func (*Service) Authentication

func (s *Service) Authentication(ctx context.Context) (Decision, error)

Authentication charges a shared coarse budget before credential verification.

func (*Service) Enter

func (s *Service) Enter(ctx context.Context) (func(), error)

Enter bounds all request work in this process, including authentication.

func (*Service) EnterExpensive

func (s *Service) EnterExpensive(ctx context.Context, principal string) (func(), error)

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

func (s *Service) EnterRecovery(ctx context.Context) (func(), Decision, error)

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.

func (*Service) Options

func (s *Service) Options() Options

Options returns a copy of the configured policy.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL