Documentation
¶
Overview ¶
Package admission provides request admission controls for existing middleware hooks. Applications own budgets, grouping, placement and transport mappings.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Concurrency ¶
type Concurrency struct {
// contains filtered or unexported fields
}
Concurrency bounds simultaneous endpoint invocations. Construct it with NewConcurrency and share the pointer across the endpoints in one budget. It must not be copied. Completion, including panic unwinding, releases the permit; cancellation alone does not. It is unsuitable for streams or work that continues after the wrapped endpoint returns.
func NewConcurrency ¶
func NewConcurrency(capacity int) (*Concurrency, error)
NewConcurrency constructs an admission budget. Capacity must be positive; invalid configuration returns an error before any middleware is constructed. No queues, worker goroutines, retries or cross-process coordination are used.
func (*Concurrency) Middleware ¶
func (c *Concurrency) Middleware(next loom.Endpoint) loom.Endpoint
Middleware wraps a unary endpoint with immediate admission. Saturation returns a *loom.ServiceError named "overloaded" with Temporary set. Declare that error in the design and map it explicitly, for example to HTTP 503. No retry occurs. A context canceled at admission returns ctx.Err() instead, even when saturated. After admission the original context and request are passed through unchanged; the endpoint's result, error and panic propagate unchanged.
Install through generated Endpoints.Use or a protected per-method constructor to retain validation and authorization before admission. This does not protect transport decoding or authentication. It panics for an uninitialized budget or nil endpoint, before requests can be served.
func (*Concurrency) SetCapacity ¶
func (c *Concurrency) SetCapacity(capacity int) error
SetCapacity atomically changes the local limit without changing permits or counters. Nonpositive values return an error and leave the prior limit intact. Reductions affect new admissions only; existing invocations finish normally.
func (*Concurrency) Snapshot ¶
func (c *Concurrency) Snapshot() ConcurrencySnapshot
Snapshot returns the effective capacity and accounting in one synchronized read. Applications may export these bounded counters and gauges to their metrics system.
type ConcurrencySnapshot ¶
type ConcurrencySnapshot struct {
// Capacity is the current positive admission limit.
Capacity int
// InFlight counts invocations that have acquired a permit and not exited.
// It may exceed Capacity after a reduction.
InFlight int
// Admitted counts acquired permits, including calls that later fail or panic.
Admitted uint64
// Rejected counts calls denied because capacity was unavailable.
Rejected uint64
// Canceled counts calls denied because their context was already canceled
// or expired at the admission decision. These are not also Rejected.
Canceled uint64
}
ConcurrencySnapshot is a coherent local observation with no request labels. Counters cover calls reaching this admission boundary since construction.
type Rate ¶
type Rate struct {
// contains filtered or unexported fields
}
Rate wraps a maintained token bucket with atomic policy updates. Construct it with NewRate; it must not be copied. A Rate is one process-local budget, not a keyed store. Applications own trusted grouping and bounded storage of separate budgets, or supply a shared backend to NewRateAdmission.
func NewRate ¶
func NewRate(policy RatePolicy) (*Rate, error)
NewRate validates policy and constructs a full local bucket at version 1.
func (*Rate) Allow ¶
func (r *Rate) Allow(ctx context.Context) (RateDecision, error)
Allow consumes one token if available, without waiting or reserving future allowance. A canceled context consumes nothing. Consumed tokens are not refunded if later validation, service execution or request cancellation fails. RetryAfter is advisory: other calls and policy changes can alter availability.
func (*Rate) Policy ¶
func (r *Rate) Policy() (RatePolicy, uint64)
Policy returns both effective settings and their version in one coherent read.
func (*Rate) SetPolicy ¶
func (r *Rate) SetPolicy(policy RatePolicy) error
SetPolicy atomically applies both settings. Accrue allowance under the old rate up to the update, retain that allowance (clamped to the new burst), then use the new rate for future refill. Increasing burst adds refill headroom, not immediate allowance. Reapplying identical settings does not reset accounting or advance the version. Invalid updates leave all state unchanged.
type RateAdmission ¶
type RateAdmission struct {
// contains filtered or unexported fields
}
RateAdmission bounds calls to a quota backend and rejects its errors or invalid decisions. Construct it with NewRateAdmission. It creates no background goroutines, retries, queues or key storage. Its timeout bounds cooperative backends; it cannot forcibly stop a callback that ignores ctx.
func NewRateAdmission ¶
func NewRateAdmission(check RateCheck, timeout time.Duration) (*RateAdmission, error)
NewRateAdmission validates the checker and its positive per-check time budget. Applications must configure network/storage timeouts in their checker too.
func (*RateAdmission) Check ¶
func (a *RateAdmission) Check(ctx context.Context, key string) (RateDecision, error)
Check runs one backend check with a child deadline, retaining the caller's values and earlier deadline. Caller cancellation returns ctx.Err(). Backend errors, backend timeouts, malformed decisions and an uninitialized admission return a safe *loom.ServiceError named "rate_limit_unavailable". Backend error text and grouping keys are never included. No error permits execution.
func (*RateAdmission) Middleware ¶
func (a *RateAdmission) Middleware(key func(context.Context, any) (string, error), denied func(RateDecision) error) func(loom.Endpoint) loom.Endpoint
Middleware admits unary endpoint calls using an application-owned grouping function and declared denial error. Install it through generated Endpoints.Use or protected constructors so grouping uses authenticated identity. A key error becomes "rate_limit_unavailable" without exposing its text. Denial invokes denied with the decision; it must return an error matching the design, including any known RetryAfter mapping. A nil denial error fails closed.
The next endpoint receives the original context, not the bounded backend context. Callback and next panics propagate. Invalid construction dependencies panic before serving. Streams and per-message quotas are outside this helper.
type RateCheck ¶
type RateCheck func(ctx context.Context, key string) (RateDecision, error)
RateCheck checks and accounts for one request in an application-selected group. It must be safe for concurrent use and return promptly when ctx ends. A backend owns coherent policy/accounting and the scope of its quota. Keys must not be included in returned error messages, logs or metric labels.
type RateDecision ¶
type RateDecision struct {
// Allowed permits the request to proceed.
Allowed bool
// RetryAfter is a positive advisory delay until allowance may be available.
// Zero means unknown. A successful decision must leave this field zero.
RetryAfter time.Duration
// Version identifies the coherent local policy used for this decision.
// External checkers may use zero when they do not expose a version.
Version uint64
}
RateDecision reports one admission decision. A denied decision with no error means quota exhaustion; backend failures are returned separately as errors.
func (RateDecision) RetryAfterSeconds ¶
func (d RateDecision) RetryAfterSeconds() int64
RetryAfterSeconds rounds a known positive delay up to whole seconds without overflowing. It returns zero for an unknown delay. HTTP adapters can publish a positive value as Retry-After; unknown delays must omit that header.
type RatePolicy ¶
type RatePolicy struct {
// PerSecond is the number of tokens replenished per second.
PerSecond float64
// Burst is the maximum token allowance, initially available in full.
Burst int
}
RatePolicy configures one local token bucket. Both fields must be positive, and PerSecond must be below math.MaxFloat64 (the dependency's unlimited sentinel). One admitted request consumes one token.
Source Files