Documentation
¶
Overview ¶
Package common provides common utilities and interfaces for the SRouter framework.
Package common provides shared types and utilities used across the SRouter framework.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthTokenConfig ¶ added in v1.3.9
type AuthTokenConfig struct {
// Source determines where to look for the token.
Source AuthTokenSource
// HeaderName is used when Source is AuthTokenSourceHeader.
// If empty, defaults to "Authorization".
HeaderName string
// CookieName is used when Source is AuthTokenSourceCookie.
CookieName string
}
AuthTokenConfig defines how to extract authentication tokens from requests.
type AuthTokenSource ¶ added in v1.3.9
type AuthTokenSource int
AuthTokenSource defines where to extract authentication tokens from.
const ( // AuthTokenSourceHeader reads the token from a request header. AuthTokenSourceHeader AuthTokenSource = iota // AuthTokenSourceCookie reads the token from a request cookie. AuthTokenSourceCookie )
type Middleware ¶
Middleware defines the type for HTTP middleware functions. It takes an http.Handler and returns an http.Handler.
type MiddlewareChain ¶ added in v1.0.2
type MiddlewareChain []Middleware
MiddlewareChain represents a chain of middleware
func NewMiddlewareChain ¶ added in v1.0.2
func NewMiddlewareChain(middlewares ...Middleware) MiddlewareChain
NewMiddlewareChain creates a new middleware chain
func (MiddlewareChain) Append ¶ added in v1.0.2
func (c MiddlewareChain) Append(middlewares ...Middleware) MiddlewareChain
Append adds middleware to the end of the chain
func (MiddlewareChain) Prepend ¶ added in v1.0.2
func (c MiddlewareChain) Prepend(middlewares ...Middleware) MiddlewareChain
Prepend adds middleware to the beginning of the chain
func (MiddlewareChain) Then ¶ added in v1.0.2
func (c MiddlewareChain) Then(h http.Handler) http.Handler
Then applies the middleware chain to a handler
func (MiddlewareChain) ThenFunc ¶ added in v1.0.2
func (c MiddlewareChain) ThenFunc(f http.HandlerFunc) http.Handler
ThenFunc applies the middleware chain to a handler function
type RateLimitConfig ¶ added in v1.1.14
type RateLimitConfig[T comparable, U any] struct { // BucketName provides a namespace for the rate limit. // If multiple routes/subrouters share the same BucketName, they share the same rate limit counters. BucketName string // Limit is the maximum number of requests allowed within the Window. Limit int // Window is the time duration for the rate limit (e.g., 1*time.Minute, 1*time.Hour). Window time.Duration // Strategy determines how clients are identified for rate limiting. Strategy RateLimitStrategy // UserIDFromUser extracts the user ID (type T) from the user object (type U). // Required only when Strategy is StrategyUser and the user object is stored in the context. UserIDFromUser func(user U) T // UserIDToString converts the user ID (type T) to a string for use as a map key. // Required only when Strategy is StrategyUser. UserIDToString func(userID T) string // KeyExtractor provides a custom function to generate the rate limit key from the request. // Required only when Strategy is StrategyCustom. KeyExtractor func(r *http.Request) (key string, err error) // ExceededHandler is an optional http.Handler to call when the rate limit is exceeded. // If nil, a default 429 Too Many Requests response is sent. ExceededHandler http.Handler }
RateLimitConfig defines configuration for rate limiting with generic type parameters. T is the User ID type (comparable). U is the User object type (any). Note: This struct uses generic types T and U, which might require careful handling when used across different packages if the specific types T and U are not known at the point of configuration (e.g., in RouterConfig). Using `any` for T and U in RouterConfig might be necessary, with type assertions or conversions happening within the middleware or route registration logic where the types are known.
type RateLimitStrategy ¶ added in v1.1.14
type RateLimitStrategy int
RateLimitStrategy defines how the rate limiter identifies clients.
const ( // StrategyIP uses the client's IP address as the key for rate limiting. // Requires router.ClientIPMiddleware to be applied first. StrategyIP RateLimitStrategy = iota // StrategyUser uses the authenticated user's ID from the context. StrategyUser // StrategyCustom uses a custom key extractor function. StrategyCustom )
type RateLimiter ¶ added in v1.1.14
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 the approximate time until the limit resets.
Allow(key string, limit int, window time.Duration) (allowed bool, remaining int, reset time.Duration)
}
RateLimiter defines the interface for rate limiting algorithms.
type RouteOverrides ¶ added in v1.3.1
type RouteOverrides struct {
// Timeout overrides the default timeout for requests.
// A zero value means no override is set.
Timeout time.Duration
// MaxBodySize overrides the maximum allowed request body size in bytes.
// A zero value means no override is set.
MaxBodySize int64
// RateLimit overrides the rate limiting configuration.
// A nil value means no override is set.
RateLimit *RateLimitConfig[any, any]
// AuthToken overrides the authentication token source.
// A nil value means no override is set.
AuthToken *AuthTokenConfig
}
RouteOverrides contains settings that can be overridden at different levels (global, sub-router, route). These overrides follow a hierarchy where the most specific setting takes precedence.
func (*RouteOverrides) HasAuthToken ¶ added in v1.3.9
func (ro *RouteOverrides) HasAuthToken() bool
HasAuthToken returns true if an auth token override is set (non-nil).
func (*RouteOverrides) HasMaxBodySize ¶ added in v1.3.1
func (ro *RouteOverrides) HasMaxBodySize() bool
HasMaxBodySize returns true if a max body size override is set (non-zero).
func (*RouteOverrides) HasRateLimit ¶ added in v1.3.1
func (ro *RouteOverrides) HasRateLimit() bool
HasRateLimit returns true if a rate limit override is set (non-nil).
func (*RouteOverrides) HasTimeout ¶ added in v1.3.1
func (ro *RouteOverrides) HasTimeout() bool
HasTimeout returns true if a timeout override is set (non-zero).
Source Files