ratelimit

type Config struct {
	Tiers            map[Tier]TierConfig
	KeyExtractor     KeyExtractor
	TierResolver     TierResolver
	EventHandler     EventHandler
	CleanupInterval  time.Duration
	WarningThreshold float64 // fires OnApproaching when remaining tokens fall below this fraction (0.0-1.0)
}

type ErrorResponse struct {
	Error      string `json:"error"`
	Message    string `json:"message"`
	Limit      int    `json:"limit"`
	Remaining  int    `json:"remaining"`
	ResetAt    int64  `json:"reset_at"`
	RetryAfter int    `json:"retry_after"`
}

type Event struct {
	Key       string
	KeyType   string // "session", "apikey", "ip"
	Tier      Tier
	Path      string
	Method    string
	Timestamp time.Time

	// rate limit state
	Allowed   bool
	Remaining int
	Limit     int
	ResetAt   time.Time

	// request context for custom handlers
	RemoteAddr string
	UserAgent  string
}

type EventHandler interface {
	OnLimited(event Event)     // called when request is rate limited (before 429 sent)
	OnApproaching(event Event) // called when usage crosses warning threshold
	OnBlocked(event Event)     // called for escalating blocks (future feature)
}

type KeyExtractor func(r *http.Request) (key string, keyType string, err error)

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

type NoopEventHandler struct{}

type Tier string

type TierConfig struct {
	Rate  rate.Limit // tokens per second
	Burst int        // max burst size
}

type TierResolver func(key string, keyType string) Tier