limiter

type Clock ¶

type Clock interface{ Now() time.Time }

Clock supports deterministic backend contract fixtures.

type Config ¶

type Config struct {
	BackendModuleID string `json:"backend_module_id"`
	BackendType     string `json:"backend_type"`
	TimeoutMS       int    `json:"timeout_ms"`
	FailureMode     string `json:"failure_mode"`
}

Config is the Community-owned selection envelope (schema 1). No policy bypass is implicit: failure_mode defaults to closed.

type Dimension ¶

type Dimension string

Dimension is one ingress traffic class.

const (
	DimensionLLM   Dimension = "llm"
	DimensionMCP   Dimension = "mcp"
	DimensionAgent Dimension = "agent"
)

type LimiterBackend ¶

type LimiterBackend interface {
	Admit(context.Context, LimiterRequest) (LimiterDecision, error)
	Retire(context.Context, string) error
	Health(context.Context) error
	Close(context.Context) error
}

LimiterBackend is the candidate protected domain SPI. All methods honor context; diagnostics are replaced by bounded gateway codes. Retire fences a generation permanently, including late operations. Admit on a retired generation must return ErrLimiterRetired (possibly wrapped); it never fails open. Generation-scoped storage survives replacement of a module's prepared connection/resource handles. Close stops admissions, cancels/drains work, and runs once per owned handle. Backend factories initialize connections before extension publication.

type LimiterDecision ¶

type LimiterDecision struct {
	Allowed    bool
	RetryAfter time.Duration
}

LimiterDecision reports one atomic consume-or-deny operation. A failure may have consumed a token; the caller must never retry it automatically.

type LimiterProvider ¶

type LimiterProvider interface {
	LimiterBackend(string) (LimiterBackend, error)
}

LimiterProvider is implemented by a linked extension's prepared resource. Selection resolves this interface only during preparation, never per request.

type LimiterRequest ¶

type LimiterRequest struct {
	Generation   string
	VirtualKeyID string
	Dimension    Dimension
	Limit        Policy
}

LimiterRequest is an immutable policy snapshot. Generation is an opaque, globally unique policy identity, never a bearer key. An unchanged policy keeps its generation across extension refreshes. Backends must preserve its state.

type MemoryBackend ¶

type MemoryBackend struct {
	// contains filtered or unexported fields
}

MemoryBackend is the Community process-local reference backend. Its lifetime is one gateway; it is not a distributed quota authority.

func NewMemoryBackend(clock Clock) *MemoryBackend

func (b *MemoryBackend) Admit(ctx context.Context, r LimiterRequest) (LimiterDecision, error)

func (b *MemoryBackend) Close(ctx context.Context) error

func (b *MemoryBackend) Health(ctx context.Context) error

func (b *MemoryBackend) Retire(ctx context.Context, g string) error

type Policy ¶

type Policy struct {
	RequestsPerMinute int
	Burst             int
}

Policy contains validated positive request-token limits.

type Selection ¶

type Selection struct {
	// contains filtered or unexported fields
}

func DefaultSelection() *Selection

func (s *Selection) Backend() LimiterBackend

func (s *Selection) Budget() time.Duration

func (s *Selection) Close(context.Context) error

func (s *Selection) Configuration() Config

func (s *Selection) Health(ctx context.Context) error

func (s *Selection) Identity() string

func (s *Selection) StateResetComparedTo(ctx context.Context, previous extension.Resource) (bool, error)

func (s *Selection) String() string