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 returns a new chain with the given middleware added to the end. The original chain is never modified, and the result has its own backing array, so multiple Appends on the same parent chain are safe.
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. // Used only when Strategy is StrategyUser. Optional: if nil, a default // conversion is used (handles string, int, int64, fmt.Stringer, and falls // back to fmt.Sprint). 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