Documentation
¶
Overview ¶
Package ratestore provides cross-pod detection of unauthenticated request bursts. A RateStore counts observations for an identity within a tumbling window and reports, exactly once per (window, identity) across the whole fleet, when the count first crosses a threshold.
The Valkey-backed implementation performs the count-and-latch atomically in a single Lua script evaluated on the server, so no distributed lock or leader election is needed and pod clock skew does not affect window boundaries.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Noop ¶
type Noop struct{}
Noop is a RateStore that never fires. It is used when rate detection is disabled so call sites can invoke Observe unconditionally.
type Options ¶
type Options struct {
// Client is a connected Valkey client. Required.
Client valkey.Client
// KeyPrefix namespaces all keys written by this store (cfg.Valkey.Prefix).
KeyPrefix string
// Threshold is the number of observations within Window that triggers a
// single fired result.
Threshold int64
// Window is the tumbling window size.
Window time.Duration
// Cooldown suppresses further fired results for the same identity/window
// after one has fired. Defaults to Window when zero.
Cooldown time.Duration
}
Options configures a ValkeyStore.
type RateStore ¶
type RateStore interface {
// Observe records one unauthenticated request for hkey. It returns fired ==
// true for exactly one observation per (window, identity) across the fleet:
// the one that first crosses the threshold and wins the emit latch.
Observe(ctx context.Context, hkey string) (fired bool, err error)
// Close releases any resources held by the store.
Close() error
}
RateStore observes an unauthenticated request for the given identity key and reports whether this observation is the one that should emit the burst audit event. Implementations must be safe for concurrent use.
type ValkeyStore ¶
type ValkeyStore struct {
// contains filtered or unexported fields
}
ValkeyStore is a RateStore backed by a Valkey server (single, sentinel or cluster, depending on the addresses supplied at construction).
func New ¶
func New(opts Options) (*ValkeyStore, error)
New creates a ValkeyStore from the given options.
Source Files