mw

Documentation

Index

• Constants
• func AccessLog(log *slog.Logger, next http.Handler) http.Handler
• func CircuitBreak(b *CircuitBreaker, next http.Handler) http.Handler
• func ConcurrencyLimit(sem *Semaphore, next http.Handler) http.Handler
• func Instrument(m *Metrics, next http.Handler) http.Handler
• func MaxBodyBytes(limit int64, next http.Handler) http.Handler
• func OptionalAuth(auth AuthHandler, next http.Handler) http.Handler
• func RID(ctx context.Context) string
• func RateLimit(limiter ratelimit.Limiter, ipr IPResolver, cfg RateLimitConfig, ...) http.Handler
• func Recover(next http.Handler) http.Handler
• func RequestID(next http.Handler) http.Handler
• func RequireAdminKey(adminKey string, next http.Handler) http.Handler
• func RequireAuth(auth AuthHandler, next http.Handler) http.Handler
• func RouteName(ctx context.Context) string
• func Subject(ctx context.Context) (string, bool)
• func WithRoute(next http.Handler, routeName string) http.Handler
• func WithSubject(next http.Handler, sub string) http.Handler
• type AuthHandler
• type Authenticator
  • func (a Authenticator) ValidateBearer(r *http.Request) (string, error)
• type BreakerConfig
• type BreakerState
• type BreakerStats
• type CircuitBreaker
  • func NewCircuitBreaker(cfg BreakerConfig) *CircuitBreaker
  • func (b *CircuitBreaker) Stats() BreakerStats
• type IPResolver
  • func (r IPResolver) ClientIP(req *http.Request) string
• type JWKSStats
• type JWKSValidator
  • func NewJWKSValidator(url string, opts JWKSValidatorOptions) (*JWKSValidator, error)
  • func (j *JWKSValidator) Stats() JWKSStats
  • func (j *JWKSValidator) Validate(ctx context.Context, tokenStr string) (string, error)
• type JWKSValidatorOptions
• type Metrics
  • func NewMetrics(reg prometheus.Registerer) *Metrics
• type RateLimitConfig
• type Semaphore
  • func NewSemaphore(maxInFlight int) *Semaphore
  • func (s *Semaphore) Cap() int
  • func (s *Semaphore) Enabled() bool
  • func (s *Semaphore) InUse() int
  • func (s *Semaphore) Release()
  • func (s *Semaphore) TryAcquire() bool

Constants

const AdminKeyHeader = "X-Admin-Key"

Functions

func AccessLog

func AccessLog(log *slog.Logger, next http.Handler) http.Handler

func CircuitBreak

func CircuitBreak(b *CircuitBreaker, next http.Handler) http.Handler

CircuitBreak rejects requests when the breaker is open. It counts failures when downstream returns >= 500.

func ConcurrencyLimit

func ConcurrencyLimit(sem *Semaphore, next http.Handler) http.Handler

ConcurrencyLimit rejects requests when too many are already in-flight for a route.

func Instrument

func Instrument(m *Metrics, next http.Handler) http.Handler

func MaxBodyBytes

func MaxBodyBytes(limit int64, next http.Handler) http.Handler

func OptionalAuth

func OptionalAuth(auth AuthHandler, next http.Handler) http.Handler

func RID

func RID(ctx context.Context) string

func RateLimit

func RateLimit(limiter ratelimit.Limiter, ipr IPResolver, cfg RateLimitConfig, next http.Handler) http.Handler

func Recover

func Recover(next http.Handler) http.Handler

func RequestID

func RequestID(next http.Handler) http.Handler

func RequireAdminKey

func RequireAdminKey(adminKey string, next http.Handler) http.Handler

func RequireAuth

func RequireAuth(auth AuthHandler, next http.Handler) http.Handler

func RouteName

func RouteName(ctx context.Context) string

func Subject

func Subject(ctx context.Context) (string, bool)

func WithRoute

func WithRoute(next http.Handler, routeName string) http.Handler

func WithSubject

func WithSubject(next http.Handler, sub string) http.Handler

Types

type AuthHandler

type AuthHandler interface {
	ValidateBearer(r *http.Request) (string, error)
}

type Authenticator

type Authenticator struct {
	Mode       string // "hmac" | "jwks"
	HMACSecret []byte
	JWKS       *JWKSValidator
}

func (Authenticator) ValidateBearer

func (a Authenticator) ValidateBearer(r *http.Request) (string, error)

type BreakerConfig

type BreakerConfig struct {
	Enabled             bool
	FailureThreshold    int           // consecutive failures to open
	OpenDuration        time.Duration // how long to stay open
	HalfOpenMaxInFlight int           // how many trial requests in half-open
}

type BreakerState

type BreakerState string

const (
	BreakerClosed   BreakerState = "closed"
	BreakerOpen     BreakerState = "open"
	BreakerHalfOpen BreakerState = "half_open"
)

type BreakerStats

type BreakerStats struct {
	State         BreakerState `json:"state"`
	Failures      int          `json:"failures"`
	OpensAt       time.Time    `json:"opens_at"`
	RetryAfterSec int          `json:"retry_after_seconds"`
	HalfInFlight  int          `json:"half_open_in_flight"`
}

type CircuitBreaker

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

func NewCircuitBreaker

func NewCircuitBreaker(cfg BreakerConfig) *CircuitBreaker

func (*CircuitBreaker) Stats

func (b *CircuitBreaker) Stats() BreakerStats

type IPResolver

type IPResolver struct {
	Trusted *netx.CIDRSet
}

func (IPResolver) ClientIP

func (r IPResolver) ClientIP(req *http.Request) string

type JWKSStats

type JWKSStats struct {
	URL       string    `json:"url"`
	KeyCount  int       `json:"key_count"`
	FetchedAt time.Time `json:"fetched_at"`
}

type JWKSValidator

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

JWKSValidator validates RS256 JWTs using a remote JWKS. It caches public keys by kid and refreshes on cache-expiry or unknown kid.

func NewJWKSValidator

func NewJWKSValidator(url string, opts JWKSValidatorOptions) (*JWKSValidator, error)

func (*JWKSValidator) Stats

func (j *JWKSValidator) Stats() JWKSStats

func (*JWKSValidator) Validate

func (j *JWKSValidator) Validate(ctx context.Context, tokenStr string) (string, error)

Validate validates the JWT string, returning the "sub" on success.

type JWKSValidatorOptions

type JWKSValidatorOptions struct {
	HTTPTimeout time.Duration
	CacheTTL    time.Duration
	Leeway      time.Duration

	// If provided, token must match one of these issuers.
	Issuers []string
	// If provided, token must match one of these audiences.
	Audiences []string

	// Allowed JWT algs (default ["RS256"])
	ValidAlgs []string
}

type Metrics

type Metrics struct {
	Requests *prometheus.CounterVec
	Latency  *prometheus.HistogramVec
}

func NewMetrics

func NewMetrics(reg prometheus.Registerer) *Metrics

type RateLimitConfig

type RateLimitConfig struct {
	Enabled   bool
	RPS       float64
	Burst     float64
	Scope     string // "user" | "ip"
	RouteName string
}

type Semaphore

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

Semaphore is a tiny counting semaphore for per-route in-flight limiting.

func NewSemaphore

func NewSemaphore(maxInFlight int) *Semaphore

func (*Semaphore) Cap

func (s *Semaphore) Cap() int

func (*Semaphore) Enabled

func (s *Semaphore) Enabled() bool

func (*Semaphore) InUse

func (s *Semaphore) InUse() int

func (*Semaphore) Release

func (s *Semaphore) Release()

func (*Semaphore) TryAcquire

func (s *Semaphore) TryAcquire() bool