ratelimit

type KeyType string

type RateLimitConfig struct {
	// Rate is the number of allowed events in the period.
	Rate int

	// Burst is the maximum number of events that can occur at once.
	// Burst should be >= Rate for meaningful operation.
	Burst int

	// Period is the time window for the rate limit.
	Period time.Duration
}

type RateLimitResult struct {
	// Allowed indicates whether the request is allowed.
	Allowed bool

	// Remaining is the number of remaining requests in the current window.
	Remaining int

	// RetryAfter is the duration until the next request will be allowed.
	// Only meaningful when Allowed is false.
	RetryAfter time.Duration

	// ResetAfter is the duration until the rate limit resets.
	ResetAfter time.Duration
}

type RateLimiter interface {
	// Allow checks if a request identified by key is allowed under the given config.
	// It returns the result of the check and any error that occurred.
	//
	// The key should be a structured identifier created by FormatKey.
	// The config specifies the rate limit parameters (rate, burst, period).
	//
	// Allow atomically decrements the rate limit counter and returns the result.
	// If the request is not allowed, RetryAfter in the result indicates when
	// the next request will be allowed.
	Allow(ctx context.Context, key string, config RateLimitConfig) (RateLimitResult, error)
}