middleware

type APIKeyProvider[T comparable] struct {
	ValidKeys map[string]T // key -> user ID
	Header    string       // header name (e.g., "X-API-Key")
	Query     string       // query parameter name (e.g., "api_key")
}

type APIKeyUserAuthProvider[T any] struct {
	GetUserFunc func(key string) (*T, error)
	Header      string // header name (e.g., "X-API-Key")
	Query       string // query parameter name (e.g., "api_key")
}

type AuthProvider[T comparable] interface {
	// Authenticate authenticates a request and returns the user ID if authentication is successful.
	// It examines the request for authentication credentials (such as headers, cookies, or query parameters)
	// and validates them according to the provider's implementation.
	// Returns the user ID if the request is authenticated, the zero value of T otherwise.
	Authenticate(r *http.Request) (T, bool)
}

type BasicUserAuthProvider[T any] struct {
	GetUserFunc func(username, password string) (*T, error)
}

type BearerTokenProvider[T comparable] struct {
	ValidTokens map[string]T                 // token -> user ID
	Validator   func(token string) (T, bool) // optional token validator
}

type BearerTokenUserAuthProvider[T any] struct {
	GetUserFunc func(token string) (*T, error)
}

type IPConfig struct {
	// Source specifies where to extract the client IP from
	Source IPSourceType

	// CustomHeader is the name of the custom header to use when Source is IPSourceCustomHeader
	CustomHeader string

	// TrustProxy determines whether to trust proxy headers like X-Forwarded-For
	// If false, RemoteAddr will be used as a fallback for all sources
	TrustProxy bool
}

type IPSourceType string

type Middleware = common.Middleware

type RateLimitConfig[T comparable, U any] struct {
	// Unique identifier for this rate limit bucket
	// If multiple routes/subrouters share the same BucketName, they share the same rate limit
	BucketName string

	// Maximum number of requests allowed in the time window
	Limit int

	// Time window for the rate limit (e.g., 1 minute, 1 hour)
	Window time.Duration

	// Strategy for identifying clients (IP, User, Custom)
	// - "ip": Use client IP address
	// - "user": Use authenticated user ID
	// - "custom": Use a custom key extractor
	Strategy RateLimitStrategy

	// Function to extract user ID from user object (only used when Strategy is StrategyUser)
	// This allows for efficient user ID extraction without trying multiple types
	UserIDFromUser func(U) T

	// Function to convert user ID to string (only used when Strategy is StrategyUser)
	// This allows for efficient user ID conversion without type assertions
	UserIDToString func(T) string

	// Custom key extractor function (used when Strategy is "custom")
	// This allows for complex rate limiting scenarios
	KeyExtractor func(*http.Request) (string, error)

	// Response to send when rate limit is exceeded
	// If nil, a default 429 Too Many Requests response is sent
	ExceededHandler http.Handler
}

type RateLimitStrategy int

type RateLimiter interface {
	// Allow checks if a request is allowed based on the key and rate limit config
	// Returns true if the request is allowed, false otherwise
	// Also returns the number of remaining requests and time until reset
	Allow(key string, limit int, window time.Duration) (bool, int, time.Duration)
}

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

type UserAuthProvider[T any] interface {
	// AuthenticateUser authenticates a request and returns the user object if authentication is successful.
	// It examines the request for authentication credentials (such as headers, cookies, or query parameters)
	// and validates them according to the provider's implementation.
	// Returns the user object if the request is authenticated, nil and an error otherwise.
	AuthenticateUser(r *http.Request) (*T, error)
}