middleware

type BasicAuthOptions struct {
	// Users is a static {username: password} map. Verification
	// scans every entry with constant-time comparisons, so timing
	// reveals neither whether a username exists nor which entry
	// matched. Intended for small fleets and CI; production
	// credentials should live in Validator backed by a
	// hashed-password store.
	Users map[string]string

	// Validator authenticates a (user, pass) pair. Return true to
	// allow the request, false to reject with 401. Validator is
	// called once per request — keep it fast (bcrypt only on the
	// register / login path, not here).
	Validator func(user, pass string) bool

	// Realm appears in the WWW-Authenticate challenge header on a
	// 401 response. Default "Restricted". Browsers use the realm
	// string to namespace cached credentials.
	Realm string

	// LocalKey overrides the req.Local key used to stash the
	// authenticated username. Default BasicAuthLocalKey.
	LocalKey string

	// SkipFunc, when non-nil and returning true, bypasses
	// authentication for that request. Useful to expose /healthz
	// without credentials while protecting the rest of the app.
	SkipFunc func(*gogo.Request) bool

	// MaxCredentialBytes caps the base64 credentials payload before
	// decoding. Default 8 KiB. Set to NoBasicAuthCredentialLimit to
	// disable.
	MaxCredentialBytes int
}

type CORSOptions struct {
	// AllowOrigins is the list of origins that are allowed to make
	// cross-origin requests. "*" allows any origin (default). Exact
	// hostnames or full origins (https://app.example.com) are matched
	// case-insensitively. Wildcard suffixes like "https://*.example.com"
	// are supported — the literal "*" must appear right after "://".
	//
	// AllowCredentials cannot be combined with "*" — browsers reject it
	// per spec. Do not mix "*" with explicit origins; use only "*"
	// for public APIs, or list every trusted origin explicitly.
	AllowOrigins []string

	// AllowMethods is the list of HTTP methods returned in the preflight
	// Access-Control-Allow-Methods header. Defaults to the standard
	// safe-plus-write set: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD.
	AllowMethods []string

	// AllowHeaders is the whitelist of request headers the server
	// permits on cross-origin requests. The preflight response's
	// Access-Control-Allow-Headers is computed as the case-insensitive
	// intersection of the client's Access-Control-Request-Headers and
	// this list — headers the client asks for that are NOT in this
	// list are silently dropped from the response, which causes the
	// browser to refuse to send them on the actual request.
	//
	// Default: Content-Type, Authorization. The literal "*" is
	// supported and means "any header" per the Fetch spec, but ONLY
	// when AllowCredentials is false; with credentials enabled the
	// wildcard is ignored and the configured list is enforced exactly.
	AllowHeaders []string

	// ExposeHeaders lists response headers the browser is allowed to
	// surface to client JavaScript. Empty by default (browsers expose
	// only the CORS-safelisted-response headers).
	ExposeHeaders []string

	// AllowCredentials sets Access-Control-Allow-Credentials: true.
	// Cannot be combined with AllowOrigins == []string{"*"}.
	AllowCredentials bool

	// MaxAge sets Access-Control-Max-Age in seconds. The browser caches
	// the preflight result for this long. 0 omits the header (browser
	// default, ~5 seconds).
	MaxAge int
}

type CSRFOptions struct {
	// Secret is the HMAC key used to sign tokens. Required; must be at
	// least 32 bytes of entropy. Rotating the secret invalidates
	// outstanding tokens, which is the intended behavior for
	// logout-everywhere flows.
	Secret []byte

	// CookieName is the Set-Cookie name carrying the token to the
	// browser. Default "csrf_token". The cookie is *not* HttpOnly
	// — JavaScript must be able to read it to echo into an
	// X-CSRF-Token header.
	CookieName string

	// HeaderName is the request header checked on unsafe methods.
	// Default "X-CSRF-Token".
	HeaderName string

	// CookiePath sets the Path attribute on the issued cookie.
	// Default "/".
	CookiePath string

	// CookieDomain sets the Domain attribute on the issued cookie.
	// Default empty (host-only cookie).
	CookieDomain string

	// CookieSecure sets the Secure attribute. Default false —
	// enable in production so the cookie never leaves HTTPS.
	CookieSecure bool

	// CookieSameSite sets the SameSite attribute. Default Lax,
	// which is the modern recommendation: prevents cross-site
	// POSTs from carrying the cookie while still allowing
	// top-level GET navigation.
	CookieSameSite gogo.SameSite

	// CookieMaxAge sets Max-Age in seconds. Default 86400 (1 day).
	CookieMaxAge int

	// MaxTokenBytes caps the CSRF token read from the Cookie and header
	// before signature verification or constant-time comparison. Zero uses
	// a conservative default; NoCSRFTokenLimit disables the cap.
	MaxTokenBytes int

	// SkipFunc, when non-nil and returning true, bypasses CSRF
	// entirely. Useful to allow specific routes (e.g. signed
	// webhook endpoints) to skip the check.
	SkipFunc func(*gogo.Request) bool

	// LocalKey overrides the req.Local key for the issued token.
	// Default CSRFLocalKey.
	LocalKey string
}

type CompressOptions struct {
	// Level is the gzip / deflate compression level. Zero means
	// gzip.DefaultCompression so the zero-value options stay useful.
	// Explicit valid values are gzip.DefaultCompression,
	// gzip.HuffmanOnly, and 1..9. Values outside the stdlib range
	// panic at construction time.
	Level int

	// MinSize skips compression when the buffered body is smaller
	// than this many bytes — small payloads are not worth the CPU
	// and the gzip framing overhead often makes the result larger.
	// Default 1024.
	MinSize int

	// MaxSize caps both compression work and the middleware's staging
	// buffer. Once the response body would grow beyond this many bytes,
	// the encoder is bypassed and the response continues uncompressed
	// (no Content-Encoding header). This avoids retaining a whole large
	// dynamic response just to later decide it is too large to compress.
	//
	// Default 4 MiB. Set to CompressNoMaxSize to disable the cap
	// (matches the pre-cap behavior — every body of any size gets
	// compressed if it passes the other filters).
	MaxSize int

	// Filter, when non-nil, is consulted after the body is buffered
	// to decide whether the response is worth compressing. The
	// default accepts standard text-ish content types and skips
	// pre-compressed media (images, archives). Override to add
	// app-specific types.
	Filter func(contentType string) bool

	// SkipFunc, when non-nil and returning true, bypasses the
	// middleware entirely for that request — useful to spare CPU
	// for streaming endpoints (Server-Sent Events, file
	// downloads) where buffering the whole body defeats the point.
	SkipFunc func(*gogo.Request) bool
}

type HelmetOptions struct {
	// HSTS sets Strict-Transport-Security. Default
	// "max-age=15552000; includeSubDomains" (180 days). The header is
	// only meaningful over HTTPS; browsers ignore it on plain HTTP.
	// Set "off" to omit (useful for HTTP-only dev environments).
	HSTS string

	// ContentSecurityPolicy sets Content-Security-Policy. Empty by
	// default — CSP is highly app-specific and a wrong policy breaks
	// pages. Set "off" or leave empty to omit. Common starter:
	// "default-src 'self'".
	ContentSecurityPolicy string

	// FrameOptions sets X-Frame-Options. Default "SAMEORIGIN".
	// Standard values: DENY, SAMEORIGIN. "off" omits.
	FrameOptions string

	// ContentTypeOptions sets X-Content-Type-Options. Default
	// "nosniff". "off" omits.
	ContentTypeOptions string

	// ReferrerPolicy sets Referrer-Policy. Default "no-referrer".
	// "off" omits.
	ReferrerPolicy string

	// XSSProtection sets X-XSS-Protection. Default "0" — modern
	// guidance is to disable the legacy IE/old-Chrome filter, which
	// could be abused to introduce XSS in otherwise safe pages.
	// "off" omits.
	XSSProtection string

	// DNSPrefetchControl sets X-DNS-Prefetch-Control. Default "off"
	// (browsers will not pre-resolve hostnames found in the page).
	// "off" as a value still emits the header; pass "" to use the
	// default and pass the literal "" override using SetHeader-style
	// is N/A — use HelmetOptions{DNSPrefetchControl: "on"} to enable.
	// To suppress the header entirely set "omit".
	DNSPrefetchControl string

	// DownloadOptions sets X-Download-Options (IE legacy). Default
	// "noopen". "omit" suppresses.
	DownloadOptions string

	// PermittedCrossDomainPolicies sets
	// X-Permitted-Cross-Domain-Policies (Adobe legacy). Default
	// "none". "omit" suppresses.
	PermittedCrossDomainPolicies string

	// CrossOriginOpenerPolicy sets Cross-Origin-Opener-Policy.
	// Default "same-origin" — isolates the browsing context group
	// to mitigate Spectre / side-channel leaks. "omit" suppresses.
	CrossOriginOpenerPolicy string

	// CrossOriginResourcePolicy sets Cross-Origin-Resource-Policy.
	// Default "same-origin". "omit" suppresses.
	CrossOriginResourcePolicy string
}

type JWTAlgorithm string

type JWTOptions struct {
	// Secret is the HMAC verification key for HS256/384/512.
	// Required when Algorithm is an HMAC variant; must be at least
	// 32 bytes of entropy. Ignored for asymmetric algorithms.
	Secret []byte

	// Key is the public key for asymmetric algorithms (RS*, PS*,
	// ES*). Must match the algorithm family:
	//   - *rsa.PublicKey for RS256/384/512 and PS256/384/512
	//   - *ecdsa.PublicKey for ES256/384/512
	// The middleware panics at construction if Algorithm and Key
	// disagree. Ignored for HMAC algorithms (use Secret).
	Key crypto.PublicKey

	// Algorithm selects the expected signing algorithm. Default
	// HS256. Tokens whose `alg` header differs from this value
	// are rejected — preventing both the legacy "none" attack
	// and algorithm-confusion attacks (HMAC-vs-RSA, where an
	// attacker could sign an RS256 token using the public key as
	// an HMAC secret if the verifier blindly used the alg header).
	Algorithm JWTAlgorithm

	// Issuer, when non-empty, requires the token's `iss` claim to
	// exactly match this value. Default empty disables issuer validation.
	Issuer string

	// Audience, when non-empty, requires the token's `aud` claim to contain
	// this value. The middleware accepts either a string `aud` claim or an
	// array of string audiences. Default empty disables audience validation.
	Audience string

	// RequiredClaims lists claim names that must be present with non-null
	// values. It does not otherwise validate custom claim value semantics.
	// Default nil requires no additional claims.
	RequiredClaims []string

	// TokenFunc extracts the JWT string from the request. Default
	// reads "Authorization: Bearer <token>". Override to source
	// the token from a cookie, query parameter, etc.
	TokenFunc func(*gogo.Request) string

	// LocalKey overrides the req.Local key used to stash claims.
	// Default JWTLocalKey.
	LocalKey string

	// SkipFunc, when non-nil and returning true, bypasses JWT
	// verification for that request.
	SkipFunc func(*gogo.Request) bool

	// Optional, when true, lets requests without a token through
	// (handler can inspect req.Local(LocalKey) to detect the
	// anonymous case). Tokens that are present but invalid are
	// still rejected with 401 — Optional doesn't make malformed
	// tokens acceptable.
	Optional bool

	// Leeway is the clock-skew tolerance when validating `exp` and
	// `nbf` claims. Default 0 (strict).
	Leeway time.Duration

	// MaxTokenBytes caps the compact JWT string before any base64 decode
	// or JSON parsing. Default 16 KiB. Set to NoJWTTokenLimit to disable.
	MaxTokenBytes int
}

type LogEntry struct {
	Method    string
	URL       string
	Status    int
	Duration  time.Duration
	IP        string
	UserAgent string
}

type LoggerOptions struct {
	// Output is where formatted log lines go. Default os.Stdout.
	Output io.Writer

	// Format produces the log line to write. Default: standard text
	// format "<method> <url> <status> <duration> <ip> <user-agent>".
	// Replace with a JSON-emitting function for structured logs.
	Format func(LogEntry) string

	// SkipPaths is a set of URLs to omit from logging — useful for
	// health-check spam (/healthz, /metrics, etc.).
	SkipPaths []string
}

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

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

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

type MetricsOptions struct {
	// Buckets are the histogram bucket upper bounds in seconds.
	// Sorted ascending; the implicit +Inf bucket is appended
	// internally so callers don't have to. If empty, defaults to
	// defaultMetricsBuckets — a Prometheus-standard set tuned for
	// the gogo latency range.
	Buckets []float64

	// Namespace prefixes every metric name (`<namespace>_<metric>`).
	// Default "http".
	Namespace string

	// Subsystem inserts a second prefix
	// (`<namespace>_<subsystem>_<metric>`). Empty by default — only
	// useful when an app exposes multiple metric groups under
	// distinct middlewares.
	Subsystem string

	// OnObservation fires after every request the middleware
	// instruments. It receives the same bounded method/status label
	// values used by the Prometheus output and never receives path or
	// route labels by default. Hook callers wire this to their tracer
	// of choice (OpenTelemetry, Datadog, etc.) without dragging the
	// SDK into gogo's dependency tree. The callback runs inline on
	// the handler goroutine — keep it non-blocking; spawn a
	// goroutine yourself if the export crosses the network.
	OnObservation func(method, status string, dur time.Duration)
}

type RateLimitOptions struct {
	// Max is the number of requests allowed per Window per key.
	// Required; zero disables the middleware (it passes everything
	// through).
	Max int

	// Window is the fixed window length. Counters reset at each
	// boundary. Required.
	Window time.Duration

	// KeyFunc derives the bucket key from the request. Default req.IP(), which
	// is the immediate TCP peer. Behind trusted proxies, override this when you
	// want end-client limits, for example by selecting from req.IPs(). For
	// AsyncStore on async routes, req.IP() requires Config.CapturePeerIP unless
	// Config.TrustedProxies auto-enabled it; when the default key cannot read a
	// peer IP, the middleware rejects instead of using an empty or header-derived
	// key.
	KeyFunc func(*gogo.Request) string

	// SkipFunc, when non-nil and returning true, bypasses the limit
	// entirely. Useful for whitelisting health-check probes or
	// authenticated admin traffic.
	SkipFunc func(*gogo.Request) bool

	// OnLimit, when non-nil, is invoked instead of the default 429
	// Too Many Requests response when a key is over its limit. The
	// middleware has already attached the X-RateLimit-* and
	// Retry-After headers before calling OnLimit.
	OnLimit gogo.Handler

	// Store overrides the in-memory bucket store. Empty default is a
	// process-local map[string]*rateBucket guarded by a mutex.
	// Provide an implementation backed by Redis / Memcache for
	// distributed deployments.
	Store RateLimitStore

	// MaxBuckets caps the in-memory store's bucket count to bound
	// memory growth under high key cardinality (e.g. attacker spam
	// with a unique key per request). When the cap is hit the store
	// sweeps expired buckets first; if that still doesn't free space,
	// the OLDEST remaining bucket (by resetAt) is evicted to make
	// room. Zero (default) means 100_000 — enough for legitimate
	// fleets, low enough that worst-case memory stays under ~10 MiB.
	// NoRateLimitBucketLimit disables the cap (not recommended outside
	// tests).
	// Only consulted when Store is the default MemoryRateLimitStore.
	MaxBuckets int

	// AsyncStore places the middleware in the async chain only. Enable
	// this when Store.Hit may block on Redis, Memcache, SQL, or network
	// I/O so the hit check runs on the worker goroutine instead of the
	// uWS event-loop thread.
	//
	// Async-placed middleware fires only on GetAsync / PostAsync routes;
	// sync routes do not see it. Keep the default false for the built-in
	// in-memory store or for fast non-blocking custom stores where early
	// sync rejection is desired.
	AsyncStore bool
}

type RateLimitStore interface {
	// Hit increments the counter for key in the current window and
	// returns the new count and the time the window resets. If the
	// window has rolled over, the store should reset to 1.
	Hit(key string, window time.Duration) (count int, resetAt time.Time)
}

type RequestIDOptions struct {
	// Header is the request/response header name carrying the ID.
	// Default "X-Request-ID". Some shops prefer X-Correlation-ID or
	// Traceparent-style values — set this to whatever your edge proxy
	// already uses so the chain stays consistent.
	Header string

	// MaxLength caps an incoming request ID before it is reused and echoed
	// back. Overlong IDs are discarded and a fresh ID is generated instead.
	// Default 128. Negative disables the length cap.
	MaxLength int

	// Validator can reject incoming IDs that don't match your fleet's
	// format. When nil, the default accepts visible non-space ASCII only.
	// Rejected IDs are replaced with a generated ID.
	Validator func(string) bool

	// Generator produces a new ID when the request has no incoming
	// value. Default generates 32 random hex characters (16 bytes of
	// crypto/rand, 128 bits of entropy). Replace with uuid.NewString
	// or a ULID generator for systems with established conventions.
	Generator func() string
}

type Session struct {
	ID string
	// contains filtered or unexported fields
}

type SessionOptions struct {
	// Secret signs the session-id cookie with HMAC so it cannot be
	// forged by clients (and is bound to this server fleet). Required;
	// must be at least 32 bytes of entropy.
	Secret []byte

	// Store is the persistence backend. Default
	// NewMemorySessionStore() — single-process, lost on restart.
	Store SessionStore

	// CookieName is the Set-Cookie name carrying the session id.
	// Default "session".
	CookieName string

	// CookiePath / CookieDomain mirror the cookie attributes of
	// the same names. Path defaults to "/", Domain empty.
	CookiePath   string
	CookieDomain string

	// CookieSecure sets the Secure flag — should be true in
	// production so the session id never leaks over plain HTTP.
	CookieSecure bool

	// CookieSameSite sets SameSite. Default Lax.
	CookieSameSite gogo.SameSite

	// TTL is the session lifetime. Default 24 hours. Used for
	// both the cookie Max-Age and the Store's expiry hint.
	TTL time.Duration

	// SkipFunc, when non-nil and returning true, bypasses session
	// loading for that request — useful for completely
	// session-irrelevant routes (static assets) that don't want
	// to pay the store-read cost.
	SkipFunc func(*gogo.Request) bool

	// LocalKey overrides the req.Local key. Default
	// SessionLocalKey.
	LocalKey string

	// MaxEntries caps the in-memory store's bucket count to bound
	// memory growth under high session-id cardinality (long-running
	// servers with sustained signup traffic, or attackers spamming
	// new session cookies). When the cap is hit on a fresh Save,
	// the store sweeps expired entries first; if that still doesn't
	// free space, the OLDEST remaining entry (by expires) is
	// evicted to make room. Zero (default) means 100_000 — enough
	// for typical fleets, low enough that worst-case memory stays
	// under ~50 MiB even with rich session payloads.
	// NoSessionEntryLimit disables the cap (not recommended outside
	// tests).
	//
	// Only consulted when Store is the default MemorySessionStore.
	MaxEntries int

	// AsyncStore places the middleware in the async chain only. Enable
	// this when Store may block on Redis, SQL, disk, or network I/O so
	// Load / Save / Delete run on the worker goroutine instead of the
	// uWS event-loop thread.
	//
	// Async-placed middleware fires only on GetAsync / PostAsync routes;
	// sync routes do not see it. Keep the default false for the built-in
	// in-memory store or for fast non-blocking custom stores that must
	// protect sync routes too.
	AsyncStore bool
}

type SessionStore interface {
	// Load returns the data map for id, or (nil, false) when the
	// id is unknown or expired. Implementations should treat
	// expired sessions as absent.
	Load(id string) (map[string]any, bool)

	// Save persists the data for id with the supplied TTL.
	// Implementations are free to round / truncate TTL.
	Save(id string, data map[string]any, ttl time.Duration) error

	// Delete removes the session.
	Delete(id string) error
}

type Snapshot struct {
	TotalRequests int64
	InFlight      int64
	MeanLatency   time.Duration
	Status        map[string]int64
	Method        map[string]int64
	BucketLE      []float64
	BucketCounts  []int64 // len = len(BucketLE) + 1 (+Inf trailing)
	BytesIn       int64
	BytesOut      int64
}

type WebSocketAuthOptions struct {
	// AllowedOrigins is the exact-match list of permitted Origin
	// header values. Empty means no browser Origin is allowed. A
	// handshake with neither Origin nor legacy Sec-WebSocket-Origin
	// is still rejected unless AllowMissingOrigin is true. To allow
	// browser clients from a specific site, list it explicitly:
	// []string{"https://app.example.com"}.
	//
	// Matching is case-insensitive. Trailing slashes are ignored.
	// The literal "*" is treated as "allow any origin" and is
	// intentionally not the zero-value default — opt in explicitly
	// when you understand the risk. Do not mix "*" with explicit
	// origins; the helper panics at construction time.
	//
	// Entries must be valid origins ("scheme://host[:port]"), "null",
	// or "*". Paths other than a single trailing slash, queries,
	// fragments, userinfo, empty entries, and control characters panic
	// at middleware construction.
	AllowedOrigins []string

	// AllowMissingOrigin permits handshakes that arrive with neither
	// Origin nor legacy Sec-WebSocket-Origin. Default false. Useful
	// for CLI tooling (websocat, curl --include) that doesn't set
	// Origin, but dangerous if any of your real clients are browsers
	// — browser requests always carry an Origin and a request without
	// one is either a non-browser or a stripped-down forgery.
	AllowMissingOrigin bool

	// Verify, when non-nil, runs after the Origin check passes and
	// is the place to plug in app-specific auth (bearer-token
	// verification, session-cookie lookup, etc.). Return a non-empty
	// userData to accept the connection with that value attached via
	// ctx.SetUserData; return nil userData with ok=true to accept
	// anonymously; return ok=false to reject with the supplied
	// status / message (defaults to 401 / "unauthorized" when zero).
	//
	// Run on the loop thread — keep it fast. For DB-backed
	// verification, look the token up at HTTP login time and stash
	// the verified bits in a signed cookie that Verify can decode
	// without I/O.
	Verify func(ctx *gogo.UpgradeContext) (userData any, ok bool, rejectStatus int, rejectMsg string)

	// AllowedSubprotocols, when non-empty, restricts the
	// Sec-WebSocket-Protocol negotiation: the helper picks the
	// first protocol from this list that the client also offered
	// in ctx.Protocols(). If the client offered no overlap the
	// connection is rejected with 400. When AllowedSubprotocols is
	// nil the helper accepts without negotiating a protocol. Entries
	// must be valid WebSocket subprotocol tokens; empty or malformed
	// entries panic at middleware construction.
	AllowedSubprotocols []string
}