ratelimit

type CheckResult struct {
	// Allowed indicates whether the operation is allowed.
	Allowed bool `json:"allowed"`

	// Reason provides a human-readable reason if denied.
	Reason string `json:"reason,omitempty"`

	// Usages contains current usage for all limits.
	Usages []Usage `json:"usages"`

	// RetryAfter indicates how long to wait before retrying (if denied).
	RetryAfter *time.Duration `json:"retry_after,omitempty"`
}

type Config struct {
	// Enabled controls whether rate limiting is active.
	Enabled bool

	// Limits defines the rate limit rules.
	Limits []LimitRule
}

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

type IdentifierFunc func(r *http.Request) (identifier string, scope Scope)

type LimitRule struct {
	// Type is the limit type (token or count).
	Type LimitType

	// Window is the time window for this limit.
	Window TimeWindow

	// Limit is the maximum allowed in the window.
	Limit int64
}

type LimitType string

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

type MiddlewareConfig struct {
	// Limiter is the rate limiter to use.
	Limiter RateLimiter

	// IdentifierFunc extracts the identifier and scope from requests.
	// If nil, DefaultIdentifierFunc is used.
	IdentifierFunc IdentifierFunc

	// TokenEstimator estimates token count for a request.
	// If nil, token count is set to 0 (only count-based limiting).
	TokenEstimator func(r *http.Request) int64

	// ExcludedPaths are paths that bypass rate limiting.
	ExcludedPaths []string

	// OnLimited is called when a request is rate limited.
	// If nil, a default JSON error response is sent.
	OnLimited func(w http.ResponseWriter, r *http.Request, result *CheckResult)
}

type RateLimitError struct {
	// Message is a human-readable error message.
	Message string

	// Result contains the detailed rate limit check result.
	Result *CheckResult
}

type RateLimiter interface {
	// Check verifies if the operation is allowed without recording usage.
	// Use this when you want to check limits before potentially expensive operations.
	Check(ctx context.Context, scope Scope, identifier string) (*CheckResult, error)

	// Record records actual usage (tokens and/or count).
	// Use this after an operation completes to record the actual usage.
	Record(ctx context.Context, scope Scope, identifier string, tokenCount int64, requestCount int64) error

	// CheckAndRecord checks limits and records usage in a single atomic operation.
	// This is the recommended method for most use cases as it prevents race conditions.
	CheckAndRecord(ctx context.Context, scope Scope, identifier string, tokenCount int64, requestCount int64) (*CheckResult, error)

	// GetUsage returns current usage statistics for an identifier.
	// Returns usage for all configured limits.
	GetUsage(ctx context.Context, scope Scope, identifier string) ([]Usage, error)

	// Reset resets usage for an identifier.
	// Useful for testing or manual quota resets.
	Reset(ctx context.Context, scope Scope, identifier string) error

	// ResetExpired removes expired usage records.
	// Should be called periodically for cleanup.
	ResetExpired(ctx context.Context, before time.Time) error
}

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

type Scope string

type Store interface {
	// GetUsage gets current usage for a specific limit.
	// Returns the current amount, window end time, and any error.
	// If no usage exists, returns 0 with a new window end time.
	GetUsage(ctx context.Context, scope Scope, identifier string, limitType LimitType, window TimeWindow) (int64, time.Time, error)

	// IncrementUsage increments usage for a specific limit.
	// Returns the new amount, window end time, and any error.
	// If the window has expired, it resets and starts a new window.
	IncrementUsage(ctx context.Context, scope Scope, identifier string, limitType LimitType, window TimeWindow, amount int64) (int64, time.Time, error)

	// SetUsage sets usage for a specific limit.
	// Used for explicit resets or window rollovers.
	SetUsage(ctx context.Context, scope Scope, identifier string, limitType LimitType, window TimeWindow, amount int64, windowEnd time.Time) error

	// DeleteUsage deletes all usage records for an identifier.
	DeleteUsage(ctx context.Context, scope Scope, identifier string) error

	// DeleteExpired deletes all expired usage records.
	// Records with windowEnd before the specified time are deleted.
	DeleteExpired(ctx context.Context, before time.Time) error

	// Close closes the store and releases resources.
	Close() error
}

type TimeWindow string

type Usage struct {
	// LimitType is the type of limit (token or count).
	LimitType LimitType `json:"limit_type"`

	// Window is the time window for this usage.
	Window TimeWindow `json:"window"`

	// Current is the current usage in the window.
	Current int64 `json:"current"`

	// Limit is the maximum allowed in the window.
	Limit int64 `json:"limit"`

	// WindowEnd is when the current window ends.
	WindowEnd time.Time `json:"window_end"`

	// Remaining is the remaining quota in the window.
	Remaining int64 `json:"remaining"`

	// Percentage is the usage percentage (0-100+).
	Percentage float64 `json:"percentage"`
}

type ValidationError struct {
	Field   string
	Message string
}