state

type Breaker interface {
	Allow(ctx context.Context) bool
	Record(ctx context.Context, success bool)
	State(ctx context.Context) breaker.State
}

type Budget interface {
	// Add records n units of consumption and reports whether they fit. A
	// rejected Add records nothing — an over-budget caller does not dig the
	// hole deeper by retrying.
	Add(ctx context.Context, n int64) BudgetResult
	// Used reports the window's state without consuming any of it. A budget
	// that can only reject is one an operator discovers at 100%; this is what
	// makes 80% visible.
	Used(ctx context.Context) BudgetResult
}

type BudgetResult struct {
	// Allowed reports whether the consumption fits the allowance.
	Allowed bool
	// Used and Limit describe the window after this check. Limit is 0 for an
	// unlimited budget.
	Used, Limit int64
	// Resets is when the window rolls over. It is not a retry delay: the
	// answer to an exhausted monthly budget is "not until the 1st", and a
	// caller that backs off by this amount would sleep for a fortnight.
	Resets time.Time
	// Degraded reports that shared state was unreachable, so this decision
	// was made per-instance rather than fleet-wide. Budgets fail open — a
	// dependency blip must not refuse all service — but silence would let a
	// fleet run unbudgeted without anyone noticing, so the caller is expected
	// to surface this in audit and metrics.
	Degraded bool
}

type Limiter interface {
	// Allow reports whether one more request fits and, when it does not,
	// how long to wait before retrying.
	Allow(ctx context.Context) (ok bool, retryAfter time.Duration)
}

type ListCache interface {
	// GetOrFill returns the cached bytes for key, or runs fill and caches
	// its result for ttl. ttl <= 0 bypasses caching.
	GetOrFill(ctx context.Context, key string, ttl time.Duration, fill func(context.Context) ([]byte, error)) ([]byte, error)
	// Invalidate drops entries whose key has the given prefix.
	Invalidate(ctx context.Context, prefix string)
}

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

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

type Memory struct{}

type Once interface {
	// TryOnce records key for ttl and reports whether this was the first
	// use. false means the key was already recorded — a replay.
	TryOnce(ctx context.Context, key string, ttl time.Duration) bool
}

type Period string

type Provider interface {
	// Limiter returns a rate limiter for scope admitting rpm requests per
	// minute. rpm <= 0 returns an unlimited limiter.
	Limiter(scope string, rpm int) Limiter
	// Budget returns an accumulating allowance for scope over a
	// calendar-aligned period. limit <= 0 returns an unlimited budget.
	Budget(scope string, period Period, limit int64) Budget
	// Breaker returns a circuit breaker for scope.
	Breaker(scope string, threshold int, halfOpenAfter time.Duration) Breaker
	// ListCache returns the list cache for scope.
	ListCache(scope string) ListCache
	// Once returns the single-use recorder for scope.
	Once(scope string) Once
	// Store returns the shared record store for scope.
	Store(scope string) Store
	// Close releases provider resources.
	Close() error
}

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

type Store interface {
	// Get returns the record for key. Absent — including when the backing
	// store is unreachable — reads as (nil, false).
	Get(ctx context.Context, key string) ([]byte, bool)
	// GetMany returns the records present among keys, omitting absent ones.
	GetMany(ctx context.Context, keys []string) map[string][]byte
	// Set writes key for ttl (ttl <= 0 never expires).
	Set(ctx context.Context, key string, value []byte, ttl time.Duration)
	// SetMany writes every entry with the same ttl in one round trip.
	SetMany(ctx context.Context, entries map[string][]byte, ttl time.Duration)
	// Delete removes key.
	Delete(ctx context.Context, key string)
}