webhttp

func ClassifyBind ¶ added in v1.12.0

func ClassifyBind(addr string) BindClass

ClassifyBind classifies a configured listen address of the "host:port" form net.Listen accepts. The HOST decides the class; the port is not validated (net.Listen owns that failure, with a better error than any pre-check here could give).

An address net.SplitHostPort cannot split returns BindInvalid, and what that means is deliberately the caller's policy. The three shipped policies, as recipes:

// Fail-silent (web-terminal-kiro): an unparseable addr will fail at
// Listen anyway; only a definite exposure warrants the warning.
if webhttp.ClassifyBind(addr) == webhttp.BindExposed { warn(...) }

// Fail-public (pg-autodump): a spurious warning is preferable to a
// silently unflagged open endpoint.
if webhttp.ClassifyBind(addr) != webhttp.BindLoopback { warn(...) }

// Classify-the-unsplit-input (web-terminal-server): a portless value
// like "127.0.0.1" is read as a bare host and classified anyway.
class := webhttp.ClassifyBind(addr)
if class == webhttp.BindInvalid { class = webhttp.ClassifyBindHost(addr) }
if class != webhttp.BindLoopback { warn(...) }

No name resolution is performed and no repair is attempted; like CanonicalHost, the classifier reports what the input IS rather than guessing what the operator meant.

func ClassifyBindHost ¶ added in v1.12.0

func ClassifyBindHost(host string) BindClass

ClassifyBindHost classifies a bare bind host (no port): the host half of a listen address, or a whole portless bind value under the classify-the-unsplit-input recipe above. It never returns BindInvalid — a bare host always classifies: "localhost" (any case) and loopback IP literals are BindLoopback; everything else, including the empty string (the wildcard "listen on all interfaces" host), unspecified addresses ("0.0.0.0", "::"), routable IPs, and unresolved hostnames, is BindExposed.

func WithHostAllowlistError ¶ added in v1.11.0

func WithHostAllowlistError(code, msg string) HostAllowlistOption

WithHostAllowlistError sets the error code and message written in the 403 JSON envelope (via WriteError) when a request's Host is not allowed. Defaults to "host_not_allowed" / "host not allowed". Override it to name the app's own configuration knob, e.g. "host not allowed; add it to KWEB_ALLOWED_HOSTS".

func WithLoopbackExempt ¶ added in v1.11.0

func WithLoopbackExempt() HostAllowlistOption

WithLoopbackExempt admits a request whenever BOTH its socket peer and its Host are loopback, regardless of the allowlist — the container-internal carve-out. It keeps a service's own loopback clients working under any allowlist: a baked Docker healthcheck (curl http://127.0.0.1:PORT), an in-container agent hitting localhost, a sidecar probe. Without it, an allowlist of browser-facing hostnames rejects those callers and can brick a health signal.

The carve-out is unreachable by the attacks a host allowlist defends against. A DNS-rebinding request carries the ATTACKER'S hostname in Host, so it fails the loopback-Host test even when it originates from a browser on this same machine (a loopback peer); and a remote client forging Host: 127.0.0.1 is not a loopback socket peer, so it fails the peer test. Both conditions must hold, and only genuinely local traffic can satisfy both.

Off by default: a bare allowlist rejects everything not listed, loopback included. Opt in when the service runs behind a loopback health check or serves in-container clients.

func ParseHostList ¶ added in v1.11.0

func ParseHostList(entries []string, opts ...HostAllowlistOption) (policy *HostPolicy, invalid []string)

ParseHostList parses operator-supplied allowlist entries (a config array or a comma-split environment variable) into a HostPolicy, returning the entries it could not use separately — a shape deliberately identical to ParseCIDRs so a strict caller can reject bad input while a lenient caller logs it and proceeds.

Each entry is trimmed; a blank entry is skipped and does not engage the gate. A usable entry is canonicalized via CanonicalHost and added to the allowlist. An entry that is not a well-formed host[:port] under CanonicalHost's strict grammar is reported as invalid (returned, never added): a pasted URL ("http://example.com"), a lone port (":9848") that belongs in the bind address, bracket or colon garbage, a non-ASCII name (configure the Punycode A-label instead), or an IP-like numeric string that is not a valid address ("127.0.0.001").

Activation, and the fail-closed contract: the policy is INACTIVE only when no non-blank entry was supplied at all (unset or all-whitespace configuration) — then Middleware is a pass-through and Allows returns true, the backward-compatible "accept every Host" default. As soon as ANY non-blank entry is supplied the gate is ACTIVE, even if every entry was invalid: a misconfigured allowlist (all entries malformed) then rejects every request rather than silently disabling the protection. Because invalid entries are returned rather than retained as unmatchable keys, a caller that wants to fail loud can inspect the invalid slice at startup and refuse to boot; a caller that wants to proceed logs it and runs with the valid subset (or, when the subset is empty, a fail-closed deny-all).

Pair it with WithLoopbackExempt for a containerized service whose own loopback health check or in-container clients must keep working, and with WithHostAllowlistError to name the app's configuration knob in the 403.

func ProbeLogLevel ¶ added in v1.15.0

func ProbeLogLevel(paths ...string) LogOption

ProbeLogLevel is the fleet-standard access-log level policy for routine machine-probe endpoints — health checks, readiness probes, metrics scrapes (Docker HEALTHCHECK curls, Gatus monitors, Prometheus). A request whose r.URL.Path exactly matches one of paths logs at Debug when it succeeds (status < 400), Warn on a 4xx, and Error on a 5xx; every other request stays at the default Info.

The point: a probe hitting a HEALTHY endpoint every 30 seconds is noise and stays out of the shipped log stream (Debug is dropped below the operating level — but becomes visible the moment an operator raises the level to debug, when "is the probe even reaching me, from where" is the question), while a FAILING probe — the readiness 503, the broken-install signal — is exactly what an operator greps for and surfaces at Warn/Error with its status, duration, and request id. Prefer this preset over skipping probe paths entirely (a skip hides the failure too) and over leaving them at Info (a line every 30s per prober). Skip lists remain the right tool for STREAMS (SSE, WebSocket), where one open-to-close line is misleading by shape, not merely noisy.

It is a WithLogLevel policy under the hood, so the two are mutually exclusive (last applied wins), it composes with the skip options (a skipped path emits no line and never consults the policy), and a panicking policy falls back to Info per the WithLogLevel contract. With no paths every request logs at Info, as without the option.

func WithClientIP ¶ added in v1.2.0

func WithClientIP(trusted ...*net.IPNet) LogOption

WithClientIP adds a "client_ip" attribute to the access-log line, set to the best-effort client IP resolved by ClientIP with the given trusted proxy ranges. With no trusted ranges the immediate socket peer is logged (the spoof-proof default); pass the reverse-proxy CIDRs to resolve the real client from a trusted X-Forwarded-For, exactly as ClientIP does. The attribute is omitted entirely unless this option is supplied, so the default access line is unchanged. It is resolved once per request, inside the deferred access log, so it costs nothing on skipped (streaming) paths.

func WithClientIPFunc ¶ added in v1.2.0

func WithClientIPFunc(fn func(*http.Request) string) LogOption

WithClientIPFunc is like WithClientIP but resolves the "client_ip" attribute with a caller-supplied function instead of a fixed trusted-proxy set. Use it when the trusted set is not known at construction — e.g. it is reloaded from config at runtime behind a hot-reloadable resolver — or when client-IP resolution is otherwise app-specific: fn is called once per logged request (never on a skipped path), and its result is logged verbatim as "client_ip". It composes with WithRecordMetric. WithClientIP and WithClientIPFunc both enable the attribute and are mutually exclusive; whichever is applied last wins. A nil fn is ignored (matching the package's skip-nil option convention), so a trailing WithClientIPFunc(nil) neither enables the attribute nor clears a prior WithClientIP.

func WithLogLevel ¶ added in v1.13.0

func WithLogLevel(fn func(r *http.Request, status int) slog.Level) LogOption

WithLogLevel sets the LEVEL POLICY for the access-log line: fn is called once per logged request with the request and the final status, and the line is emitted at the returned level. The default without this option is slog.LevelInfo, unchanged. The hook chooses the level only — the line's attributes and emission rules (deferred emit, skip paths) are the logger's fixed mechanism. ProbeLogLevel is the named preset over this hook for the routine-machine-probe case; reach for the raw hook only when a custom policy is genuinely needed.

The canonical use is scrape-noise control on a polled service: map 2xx/3xx to slog.LevelDebug so a 15-second Prometheus scrape stays out of the log stream at the default level while staying visible under LOG_LEVEL=debug, and raise 4xx to Warn / 5xx to Error so failures surface. Because fn also receives the request, a policy can key on the path instead (quiet only the scrape route, keep everything else at Info).

A request suppressed by WithSkipPaths or WithSkipFunc emits no line at all, so fn is never called for it. A panicking fn is contained: the failure is logged and the line falls back to Info, mirroring the package's other callback guards. A nil fn is ignored (the skip-nil option convention).

func WithLogger ¶

func WithLogger(l *slog.Logger) LogOption

WithLogger sets the slog.Logger used for access-log lines. Defaults to slog.Default().

func WithMaxLoggedPath ¶ added in v1.19.0

func WithMaxLoggedPath(n int) LogOption

WithMaxLoggedPath sets the byte cap the access line applies to the recorded path, replacing the 512-byte default. Reach for it when the app's whole route table is short and a tighter log-line budget is worth more than the tail of a long path: knell serves /healthz, /metrics, and /beat/{id} with an id its config caps at 64 characters, so 128 covers every path it can legitimately answer.

n counts PATH bytes. An over-cap value keeps at most n of them, cut on a UTF-8 rune boundary, followed by the 14-byte truncation marker, so the attribute is at most n+14 bytes; a value within the cap is recorded byte-identical. The cap applies to whatever the path policy produced, including this package's own fail-closed placeholders, so the guarantee has no branch-shaped hole.

A non-positive n is ignored and the default stands (the skip-nil option convention). There is deliberately no way to switch the bound OFF: it exists because eight of the nine access-log consumers had no path bound of their own, so an option that could zero it would reopen precisely the hole it closes — and a config-driven 0 would do it silently.

func WithPathFunc ¶ added in v1.14.0

func WithPathFunc(fn func(*http.Request) string) LogOption

WithPathFunc sets the PATH POLICY for the access-log line: fn is called once per logged request, at emit time, and its return value replaces r.URL.Path as the recorded path. Use it when a route embeds a credential or other sensitive segment (e.g. "/api/sessions/{token}") that should be logged as a token-free template or truncated form — the middle ground between logging the raw path and losing the whole access record to WithSkipPaths or WithSkipFunc.

The returned value is "the path as recorded": it feeds the access line's "path" attribute, the legacy WithRecordMetric hook's path argument, and the "path" attribute of the package's hook-failure diagnostics. It feeds NEITHER request-derived metric hook: WithRecordMetricRequest receives the request itself and owns its own representation, and WithRecordRouteMetric's path label is the matched route, which is a bound of its own and not a redaction policy. fn's return is still length-bounded before it is recorded (512 bytes by default, WithMaxLoggedPath to change it): a transform is a REDACTION policy, and nothing about redacting a token also bounds the path it was in.

fn runs inside the deferred emit, after routing, so http.ServeMux has already populated r.Pattern (empty when nothing matched) and a transform may return the matched template with its own fail-closed fallback for unmatched requests. The WithRecordMetricRequest caveat applies equally: middleware between RequestLogger and the mux that replaces the request (r.WithContext and friends return a clone) hides the populated fields.

Skip predicates (WithSkipPaths, WithSkipFunc) always test the raw r.URL.Path, and a skipped request never calls fn.

Fail-closed: if fn panics or returns the empty string, the line records the "(path-redaction-failed)" placeholder — never the raw path — and a panic is additionally logged through the package's hook-isolation guard, whose own diagnostic also omits the raw path. A nil fn is ignored (the skip-nil option convention).

func WithRecordMetric ¶

func WithRecordMetric(fn func(method, path string, status int, d time.Duration)) LogOption

WithRecordMetric registers a hook invoked once per logged request with the final method, path, status, and latency. Both text arguments are the values the access line RECORDED, so they carry the same bounds: the path is the path policy's output capped by WithMaxLoggedPath, and the method is capped at 24 bytes, which keeps an over-long token out of a metric label as well as out of the log. It fires from a deferred call, so a panicking handler is still recorded. Requests skipped via WithSkipPaths or WithSkipFunc are excluded from the hook as well as from access logging: a stream's open-to-close duration paired with a synthetic status is misleading, which is the whole reason the path is skipped.

Its bounds are LENGTH bounds, not cardinality bounds: a raw r.URL.Path under the cap is still one label value per URL a scanner invents, and a method under 24 bytes is still one per token. For a metric this hook is the wrong shape unless a path policy already collapses the path onto route templates — reach for WithRecordRouteMetric, whose labels are bounded by construction. The three metric options are mutually exclusive; whichever is applied last wins.

func WithRecordMetricRequest ¶ added in v1.13.0

func WithRecordMetricRequest(fn func(r *http.Request, status int, d time.Duration)) LogOption

WithRecordMetricRequest is the request-aware variant of WithRecordMetric: fn is invoked once per logged request with the *http.Request itself, the final status, and the latency. Because http.ServeMux assigns the matched pattern to the request in place, fn observes a populated r.Pattern after routing (empty when nothing matched, e.g. a 404), so a caller can key a metric on the route TEMPLATE rather than on the raw URL path. Caveat: middleware between RequestLogger and the mux that replaces the request (r.WithContext and friends return a clone) hides those fields — the mux populates the clone, not the request this hook received.

Prefer WithRecordRouteMetric. This hook hands fn the raw request, which makes the APP responsible for a bound it can get wrong, and one consumer did: it derived its labels from r.Method, wrote a comment asserting they were bounded, and shipped an attacker-controllable method label anyway, because it also registers a "/" catch-all — so its r.Pattern is never empty, the unmatched collapse it relied on can never fire, and every SPA fallthrough minted a series named by the caller. Nothing in the hook's signature could have caught that. WithRecordRouteMetric computes the bounded pair here and passes it in, so there is no derivation left for a consumer to get wrong; reach for this hook only when the metric genuinely needs something else from the request (say a per-tenant series keyed on an id the app validated itself), and use RouteMetricLabels when what it needs is the standard pair.

Like WithRecordMetric it fires from a deferred call (a panicking handler is still recorded) and is excluded on paths skipped via WithSkipPaths or WithSkipFunc. The three metric options are mutually exclusive; whichever is applied last wins. A nil fn is ignored (the package's skip-nil option convention), so a trailing WithRecordMetricRequest(nil) neither enables the hook nor clears a prior hook.

func WithRecordRouteMetric ¶ added in v1.19.0

func WithRecordRouteMetric(fn func(method, path string, status int, d time.Duration)) LogOption

WithRecordRouteMetric registers the metric hook whose labels THIS PACKAGE derives, and is the recommended one: fn is invoked once per logged request with the bounded (method, path) label pair RouteMetricLabels computes for the request, plus the final status and the latency. The app never receives the raw request through this option, so it has no derivation to get wrong — that is the whole reason the option exists rather than only the function. Safety here is a property of the wiring, not of every consumer remembering to reach for the right helper: WithRecordMetricRequest's godoc records the consumer that reached for the wrong one, believed otherwise, and shipped an attacker-controllable method label.

The labels are bounded BY CONSTRUCTION: the method is one of ten fixed values and the path is either a pattern the SERVER registered or the fixed "unmatched" marker. Cardinality is therefore a function of the route table, not of the traffic, which matters because the hook fires from the access-log defer — outside every app auth gate — and a series once minted is permanent for the process lifetime here AND in every observer scraping it. See RouteMetricLabels for each label's derivation and for the one deliberate divergence from the access line.

fn takes the same (method, path, status, duration) arguments as WithRecordMetric rather than a struct, so that switching a consumer from the unbounded hook to this one changes the option name and nothing else, and one recording function can be passed to either.

Like the other metric hooks it fires from a deferred call (a panicking handler is still recorded), is excluded on paths skipped via WithSkipPaths or WithSkipFunc, and is isolated by a recover guard (a panicking hook skips this request's metric rather than killing the connection). The three metric options are mutually exclusive; whichever is applied last wins. A nil fn is ignored (the package's skip-nil option convention), so a trailing WithRecordRouteMetric(nil) neither enables the hook nor clears a prior hook.

The path policy options (WithPathFunc, WithTemplatePathsUnder, WithMaxLoggedPath) do NOT reach these labels: they govern the recorded path of the LOG LINE, while this hook's path is the matched route. A path policy and this hook are complementary, not alternatives.

func WithSkipFunc ¶

func WithSkipFunc(fn func(*http.Request) bool) LogOption

WithSkipFunc registers a predicate; when it returns true for a request, that request is passed through WITHOUT an access-log line or metric (like a WithSkipPaths match), while the request id is still minted, echoed, and threaded. Use it for streaming routes with path parameters (e.g. "/ws/{id}") that an exact WithSkipPaths match cannot cover.

func WithSkipPaths ¶

func WithSkipPaths(paths ...string) LogOption

WithSkipPaths marks exact request paths (compared against r.URL.Path) that should pass through WITHOUT an access-log line AND without a metric hook. Use it for long-lived streams (SSE, WebSocket) whose single open-forever request would otherwise emit one misleading high-latency line and a synthetic status at close. The request id is still minted, echoed, and threaded into the context for skipped paths. Because the match is exact, streaming routes with path parameters (e.g. "/ws/{id}") need WithSkipFunc instead.

func WithSkipUpgrades ¶ added in v1.20.0

func WithSkipUpgrades() LogOption

WithSkipUpgrades suppresses the access record for a request whose response SWITCHED PROTOCOLS — and for nothing else. It is what a WebSocket route should use instead of a WithSkipFunc predicate that PREDICTS which requests will upgrade.

The decision comes from the response, not from the request. The record is suppressed when the recorded status is 101 (the handshake went through the ResponseWriter, as coder/websocket's WriteHeader(101)-then-hijack does) or when the handler hijacked the connection before recording anything at all (the handler wrote the handshake onto the connection itself, as gorilla/websocket does). Those are the two shapes a completed upgrade takes, and in both the exchange has ENDED rather than completed, so the one line that would be emitted when the socket finally closes — hours later, carrying a session-length duration and a status net/http never sent — describes something that never happened. Every OTHER outcome on the same route keeps its record with its real status, duration, request id, and client ip: the 400 for a malformed Sec-WebSocket-Key, the 403 for a disallowed origin, the 405 for a non-GET, the 426 for missing upgrade headers. Those refusals are what an operator greps for when a browser cannot attach or a reverse proxy mangles a handshake.

Why the decision belongs here: a skip predicate has to answer before the handler runs, so it must model the handshake policy of whichever library will answer the request, and it drifts when that library changes. A consumer's predicate checked that Sec-WebSocket-Key was present exactly once; coder/websocket base64-decodes that header and requires exactly 16 bytes, answering 400 otherwise, so every malformed-key 400 was suppressed as if it had upgraded — as was the cross-origin 403 the same predicate could not model — losing status, duration, request id, and client ip for exactly the refused requests worth seeing. The fact the predicate was guessing at is known HERE, once the response exists.

The interaction with the skip options is one-way. WithSkipPaths and WithSkipFunc are evaluated before the handler and bypass the recorder entirely, so a request either of them matches is skipped whatever status it ends up with, and this option cannot bring its record back. This option only ever REMOVES a record that would otherwise have been emitted.

Suppression removes the whole record, the same pairing WithSkipPaths has and for the same reason: no access line and no metric hook, and neither the WithLogLevel policy nor a WithPathFunc / WithTemplatePathsUnder transform is consulted. The request id is still minted, echoed, and threaded, as on every path through this middleware. A handler that PANICS after the switch is not hidden by that: Recoverer logs the panic and its stack from its own line, which is where a crash mid-session belongs — the access line it would otherwise pair with says 101, not 500, because the status was decided at the handshake.

Two boundaries, because both KEEP their record:

• A handler that never calls WriteHeader records the implicit 200 net/http sends. That is not 101, so an ordinary request that writes only a body is logged exactly as it is without this option.
• A handler that writes an explicit status and THEN hijacks (an HTTP CONNECT tunnel answering 200) keeps its record with that status: it told us what it answered, and only 101 says "this is no longer an HTTP exchange". A consumer that wants such a tunnel silent still has WithSkipFunc, whose prediction problem does not apply to a test on the method.

It takes no status argument on purpose. 101 is the one status that means the exchange ended rather than completed, so a general skip-these-statuses option would add exactly one capability: silencing refusals. A 404 flood is a broken route and a 401 flood is an attack, and deleting their records is CWE-778 rather than noise control — which WithLogLevel (or the ProbeLogLevel preset) already does properly, by lowering a line's level instead of removing it.

HTTP/2's extended-CONNECT upgrade (RFC 8441) answers 2xx rather than 101 and is deliberately out of scope; it cannot arise for this option's audience anyway, since a server that hijacks to speak WebSocket needs HTTP/1.1.

func WithTemplatePathsUnder ¶ added in v1.17.0

func WithTemplatePathsUnder(prefixes ...string) LogOption

WithTemplatePathsUnder declares URL prefixes whose concrete paths carry a CREDENTIAL, so the access log records the matched ROUTE TEMPLATE for them instead of the path itself: "/api/sessions/{id}" rather than "/api/sessions/6f3a…". Prefer it over WithPathFunc for this job — it is the same protection expressed as data, and the reason that matters is below.

The template comes from r.Pattern, which http.ServeMux populates during routing, so the router is the source of truth for what matched. The method prefix ServeMux includes ("DELETE /api/sessions/{id}") is stripped, since the method is already its own attribute on the line.

Three cases, and the middle one is the whole point:

• a path under a declared prefix that MATCHED a route: the template.
• a path under a declared prefix that matched NOTHING (a 404 on "/api/sessions/6f3a…/nope"): the prefix plus an "(unmatched)" marker. Never the raw path — an unrouted request under a credential-bearing prefix still has the credential in it, and this is exactly the leak a path policy exists to close. It is also visible as unmatched rather than mislabelled onto a route it is not, so a NEW upstream subroute shows up in the log as something to wire rather than disappearing.
• a path outside every declared prefix: recorded unchanged. Deliberately not the template, because a static mount's pattern is "/" and logging that would collapse every asset onto one line, losing which asset 404'd. Credential-bearing routes are a per-route-family fact, not a per-app one, which is why this option takes prefixes rather than being a global switch.

Why this exists as a declarative option rather than leaving callers to write their own WithPathFunc: two apps in this fleet hand-rolled the identical transform over the same upstream route table and DIVERGED on the unmatched case — one returned "" (indistinguishable from a broken transform) and one returned an "(unmapped)" marker. A free-form hook makes that outcome the default. Expressed as data, the policy has one implementation, and the unmatched-route decision is made once here instead of once per consumer.

Pair it with the prefix the route-owning package exports (e.g. the terminal engine's SessionsSubtreePath) rather than a local string literal, so the set of credential-bearing routes stays owned by whoever declares those routes.

A prefix that is empty is ignored. Applying this option replaces any previously-set path policy (including WithPathFunc), and vice versa: there is one recorded path, so the last policy applied wins.

func Logging ¶

func Logging(opts ...LogOption) Middleware

Logging returns a Chain-composable Middleware wrapping RequestLogger with the given options. It is exactly RequestLogger in middleware form; use RequestLogger directly when you are not composing with Chain. See RequestLogger for the request-id and access-log behavior and the available LogOption values.

func NoStore ¶ added in v1.20.0

func NoStore() Middleware

NoStore returns middleware that sets Cache-Control: no-store on every response passing through it, before the next handler runs.

The value is FIXED. This is deliberately not a cache-policy API: the one header every dynamic surface needs is worth a name, and anything richer is per-asset POLICY that already has a home in WithStaticCacheControl. Three consumers had hand-written this exact three-line wrapper — for a state-reporting API, for an SPA's HTML and API responses, and for an /api/ subtree whose handlers set no cache directive at all — and the library already set the same value internally at ReadinessHandler without exporting a composable form.

PLACEMENT AND OVERRIDE ORDERING STAY APP-OWNED, exactly like WithStaticCacheControl's policy hook. The header is set before next runs and is not locked: a handler or an inner middleware that needs a different value for its own responses (a long-lived immutable asset, a per-asset cache policy, a cacheable preview image) simply Sets Cache-Control itself and wins, which is why the usual placement is innermost in the Chain — early enough to land before any handler writes a status, late enough that the asset paths that need to override it still can. Scope it by mounting it on the subtree that needs it rather than by configuring it.

It is NOT the middleware for a conditional no-store: a response that must only be uncacheable when it carries a Set-Cookie (the OWASP session- management rule) has a different trigger and a different concern, and belongs with the code that sets the cookie.

func RateLimiter ¶ added in v1.3.0

func RateLimiter(burst int, interval time.Duration, opts ...RateLimitOption) Middleware

RateLimiter returns middleware that throttles requests through a single shared token bucket (standard library only, no external dependency). burst is the maximum number of tokens and the initial fill; interval is the time to accrue one token (the refill cadence). Each admitted request consumes one token; a request that arrives with the bucket empty is answered with a 429 via WriteError(w, r, http.StatusTooManyRequests, "rate_limited", "rate limit exceeded") (code and message overridable with WithRateLimitError) and does not reach the next handler. The 429 carries a conservative Retry-After hint: the whole seconds for the CURRENT token deficit to refill at the configured rate — at most ceil(interval) when the bucket was just emptied, less when it is already partially refilled — clamped to at least 1s.

The bucket is process-wide for the middleware instance — shared across all requests and all clients — so it bounds the AGGREGATE rate of the wrapped route. That is the right tool for capping an expensive shared resource (for example, spawning a heavy child process per request), not for per-client fairness. Per-client limiting is intentionally out of scope; a caller behind a trusted proxy that needs it can key its own buckets on ClientIP.

A non-positive burst or a non-positive interval disables limiting: the middleware returns the next handler unwrapped (mirroring RouteTimeout's non-positive "off" contract), so a config-driven zero cleanly means "no limit".

Apply it to the specific handler you want to throttle, and pair it with WithRateLimitWhen to gate only the expensive method+path when the handler serves several:

sessions := webhttp.RateLimiter(6, time.Second,
	webhttp.WithRateLimitWhen(func(r *http.Request) bool {
		return r.Method == http.MethodPost
	}),
)(sessionsHandler)

func Recoverer ¶

func Recoverer(opts ...RecoverOption) Middleware

Recoverer returns middleware that recovers a panic from a downstream handler, logs it at Error with the stack and the request id (via RequestIDFromContext), fires any WithPanicHook callback, and writes a 500 error via the configured ErrorResponder - WriteError by default, i.e. the JSON envelope {"error":"internal server error","code":"internal_error"}. Override the responder with WithRecoverResponder to render the 500 on another content type. Without it, a handler panic unwinds to net/http, which closes the connection abruptly with no response body.

The http.ErrAbortHandler sentinel is deliberately NOT recovered: per the net/http contract it is re-panicked so the server aborts the response the way the handler intended (it is not logged and fires no hook).

Placement relative to Logging matters. Put Recoverer INSIDE RequestLogger, i.e. Logging outermost, as in Chain(mux, Logging(), Recoverer()): the recovered request then records a 500 before RequestLogger's deferred access line runs, so the request logs as 500. If Recoverer sits OUTSIDE the logger, RequestLogger's deferred line runs during the panic unwind and records the StatusRecorder's default 200, a misleading access line even though the client still receives the 500.

The 500 is best-effort and never double-writes: if the handler already committed the response (wrote headers or body) before panicking, the status is on the wire and cannot be changed, so Recoverer skips the body entirely (it still logs the panic and fires the hook) rather than corrupting the partial response or mislabeling its status under an outer Logging. To detect commitment it observes the response through a StatusRecorder, reusing an existing one (such as RequestLogger's) when present.

func SecurityHeaders ¶

func SecurityHeaders(opts ...SecurityOption) Middleware

SecurityHeaders returns middleware that sets a baseline of response security headers before calling the next handler. Set by default are X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and Referrer-Policy: strict-origin-when-cross-origin. The X-Frame-Options and Referrer-Policy defaults are configurable (override with a value, or omit with an empty string); nosniff is set by default with no option to change it here. Content-Security-Policy, Permissions-Policy, Cross-Origin-Opener-Policy, and Strict-Transport-Security are off unless their options are supplied.

All of these are set BEFORE next runs, so none is immutable: the middleware establishes the baseline but does not lock it. A handler that needs a different value for a specific response can still override (or delete) any of them, nosniff included, on the response header.

func SessionCreateRateLimit ¶ added in v1.8.0

func SessionCreateRateLimit(path string) Middleware

SessionCreateRateLimit returns middleware gating POST requests to path (an exact match, e.g. "/api/sessions") behind the standard session-create token bucket: burst 6, one token accrued per second, and a 429 envelope of code "rate_limited" / message "session creation rate exceeded". Non-POST methods and other paths pass through without consuming a token, so a handler that multiplexes list (GET) and close (DELETE) on the same path stays unthrottled.

This is a preset over RateLimiter for the create-a-heavy-child endpoint shape, where each admitted request forks an expensive process (a PTY, an agent subprocess) and what needs bounding is aggregate create churn. The tuning lives here once; an app needing different numbers or a different predicate composes RateLimiter directly.

func WithRateLimitError ¶ added in v1.3.0

func WithRateLimitError(code, msg string) RateLimitOption

WithRateLimitError sets the error code and message written in the 429 JSON envelope (via WriteError). Defaults to "rate_limited" / "rate limit exceeded".

func WithRateLimitWhen ¶ added in v1.3.0

func WithRateLimitWhen(pred func(*http.Request) bool) RateLimitOption

WithRateLimitWhen restricts limiting to requests for which pred returns true; every other request passes through without consuming a token. Use it to gate a single method+path on a handler that multiplexes several — for example, throttle only POST and leave GET/DELETE on the same path unthrottled. A nil predicate is ignored, so the default (limit every request) stands.

func WithPanicHook ¶

func WithPanicHook(fn func(v any, stack []byte)) RecoverOption

WithPanicHook registers a callback invoked with the recovered value and the captured stack when a panic is caught. Use it to increment a metric or notify an error tracker. It runs after the panic is logged and before the 500 response is written; a nil hook is ignored.

func WithRecoverLogger ¶

func WithRecoverLogger(l *slog.Logger) RecoverOption

WithRecoverLogger sets the slog.Logger used to report a recovered panic. Defaults to slog.Default().

func WithRecoverResponder ¶ added in v1.4.0

func WithRecoverResponder(fn ErrorResponder) RecoverOption

WithRecoverResponder sets the ErrorResponder that writes the 500 body after a recovered panic (only when the response is not already committed). It defaults to WriteError - the JSON envelope; supply one to render the 500 on a different content type, for example an XML endpoint returning its own error document. The responder owns writing the status and headers. A nil responder is ignored, keeping the default.

func WithPreDrain ¶ added in v1.9.0

func WithPreDrain(fn func(ctx context.Context)) RunOption

WithPreDrain registers a hook Run invokes after ctx is cancelled and strictly before srv.Shutdown starts draining in-flight requests. It is the place for the release-the-streams phase a graceful stop needs ahead of the drain: flip a readiness gate so a load balancer stops routing here, cancel the server's BaseContext or shut down an SSE hub so long-lived connections end (otherwise Shutdown waits its full grace period for them). fn receives a context bounded by the SAME shutdown deadline that Shutdown and onShutdown share; whatever budget it spends is no longer available to them. A nil fn is ignored.

func WithServeExit ¶ added in v1.18.0

func WithServeExit(fn func(ctx context.Context)) RunOption

WithServeExit registers an opt-in teardown hook Run invokes when srv.Serve returns on its own — before ctx is ever cancelled — in place of the graceful sequence. That covers a fatal serve error (the listener or the accept loop is gone) and a Shutdown or Close the caller drove itself outside Run. Exactly one of the two paths runs per Run call: with the hook registered, either pre-drain -> Shutdown -> onShutdown ran, or fn did. Without it, Run keeps today's behavior of returning the serve error with NEITHER hook invoked, so an existing caller sees no change. A nil fn is ignored.

fn receives a context bounded by the shutdown grace period, and gets the whole budget: there was no drain to share it with. Run does NOT call srv.Shutdown on this path — Serve has already returned and closed the listener, so a drain would only spend fn's budget waiting on connections whose accept loop is already dead.

WithPreDrain and onShutdown are NOT reused here, because both are documented against a graceful stop that this path is not: ctx is still LIVE (nothing cancelled it), and there is no drain for a pre-drain phase to precede. That matters for what fn must do — a teardown that waits on a goroutine keyed to ctx (a background loop stopped by the same signal context) has to cancel it inside fn, by calling the signal context's stop function, or it waits out the whole grace for a goroutine nothing has asked to stop. A caller whose teardown is cancellation-independent can pass the same function to both slots: Run(ctx, srv, ln, teardown, WithServeExit(teardown)).

func WithShutdownGrace ¶

func WithShutdownGrace(d time.Duration) RunOption

WithShutdownGrace sets how long Run allows for graceful shutdown: the window for the pre-drain hook to run, for in-flight requests to finish, and for the onShutdown teardown to run. Defaults to 5s.

func WithCOOP ¶

func WithCOOP(v string) SecurityOption

WithCOOP sets the Cross-Origin-Opener-Policy header (e.g. "same-origin"). Unset by default.

func WithCSP ¶

func WithCSP(policy string) SecurityOption

WithCSP sets the Content-Security-Policy header. The library never builds a policy for you: a CSP is application-specific (it must match the app's script and style sources, nonces, or hashes), so pass the exact policy string the app needs. Unset by default.

func WithFrameOptions ¶

func WithFrameOptions(v string) SecurityOption

WithFrameOptions overrides the X-Frame-Options header (default "DENY"). Pass an empty string to omit the header, for example when a Content-Security-Policy frame-ancestors directive supersedes it.

func WithHSTS ¶

func WithHSTS(maxAge time.Duration, includeSubdomains, preload bool) SecurityOption

WithHSTS enables the Strict-Transport-Security header with the given max-age and the includeSubDomains and preload directives. HSTS is OFF by default: enable it only for a service reached exclusively over HTTPS, because a browser that sees the header will refuse plain-HTTP and untrusted-certificate connections to the host for the whole max-age window. A negative max-age is clamped to zero (which instructs browsers to forget the policy).

func WithPermissionsPolicy ¶

func WithPermissionsPolicy(v string) SecurityOption

WithPermissionsPolicy sets the Permissions-Policy header (browser feature gating, e.g. "geolocation=(), camera=()"). Unset by default.

func WithReferrerPolicy ¶

func WithReferrerPolicy(v string) SecurityOption

WithReferrerPolicy overrides the Referrer-Policy header (default "strict-origin-when-cross-origin"). Pass an empty string to omit it.

func WithErrorLog ¶

func WithErrorLog(l *log.Logger) ServerOption

WithErrorLog sets http.Server.ErrorLog so connection-level errors go to the caller's logger instead of the standard logger. It is the override for a custom *log.Logger; for the ordinary case of routing those lines into slog at a chosen level, use WithSlogErrorLog.

func WithIdleTimeout ¶

func WithIdleTimeout(d time.Duration) ServerOption

WithIdleTimeout sets http.Server.IdleTimeout, the keep-alive idle deadline.

func WithMaxHeaderBytes ¶

func WithMaxHeaderBytes(n int) ServerOption

WithMaxHeaderBytes sets http.Server.MaxHeaderBytes.

func WithReadHeaderTimeout ¶

func WithReadHeaderTimeout(d time.Duration) ServerOption

WithReadHeaderTimeout sets http.Server.ReadHeaderTimeout, the slowloris guard bounding how long a client may take to send request headers.

func WithReadTimeout ¶

func WithReadTimeout(d time.Duration) ServerOption

WithReadTimeout sets http.Server.ReadTimeout, the deadline for reading the entire request. Leave it unset for streaming request bodies.

func WithSlogErrorLog ¶ added in v1.20.0

func WithSlogErrorLog(level slog.Level) ServerOption

WithSlogErrorLog sets http.Server.ErrorLog to a bridge that forwards net/http's own connection-level lines into slog at level, so they arrive as level-carrying records in an otherwise structured stream instead of as unstructured, level-less standard-logger output that no level-based log rule can match. The lines it covers are net/http's, above all "http: Accept error: ...; retrying" — the trace of an exhausted fd budget, which is a whole-service outage no request-scoped log will report.

The LEVEL is the caller's policy and deliberately has no default here, because consumers legitimately disagree: an accept failure is fatal to a service whose only job is to answer probes (Error) and a degradation to one that will retry (Warn). This option only gives that choice a named home instead of three hand-written copies of the same slog.NewLogLogger recipe.

It resolves slog.Default() when the option is APPLIED (inside NewServer), so install the process logger before building the server; a later slog.SetDefault does not retroactively re-target an already-built http.Server. WithErrorLog remains the escape hatch for any other *log.Logger, and the default (net/http's standard logger) is unchanged when neither option is passed.

func WithWriteTimeout ¶

func WithWriteTimeout(d time.Duration) ServerOption

WithWriteTimeout sets http.Server.WriteTimeout, the deadline for writing the entire response. It is unset by default: streaming apps (SSE, WebSocket, long responses) MUST omit it, because it would cut off an in-progress stream.

func WithStaticCacheControl ¶ added in v1.8.0

func WithStaticCacheControl(fn func(assetPath string) string) StaticOption

WithStaticCacheControl sets the per-asset Cache-Control policy. fn receives the normalized asset path — no leading slash, and "index.html" for the root ("/") request — and returns the Cache-Control value for that asset; an empty return omits the header. The default policy returns "no-cache" for every asset: revalidate on every load (the content-hash ETag makes that a cheap 304), the right choice when asset paths are stable rather than content-addressed. Supply a policy to differ per path, for example immutable large fonts alongside no-cache app code. A nil fn is ignored, keeping the default.

The policy is MECHANISM-free: it chooses header values only. Whether an asset is ETagged, gzipped, or revalidated is the handler's fixed behavior.

func NewStaticTokenVerifier ¶ added in v1.10.0

func NewStaticTokenVerifier(configured string) StaticTokenVerifier

NewStaticTokenVerifier builds a verifier for the configured secret.

An empty configured secret yields the zero verifier, which fails CLOSED: Verify returns false for every presented value, including the empty string. Without that guard the digest comparison would fail OPEN — sha256("") equals sha256(""), so an unset secret would grant access to any client that simply presents no credential. Treat an empty configured value as "auth not configured", never as "no credential required": a caller that wants an open endpoint should skip the gate explicitly rather than rely on an empty secret.

package main

import (
	"fmt"

	"github.com/cplieger/webhttp"
)

func main() {
	v := webhttp.NewStaticTokenVerifier("s3cr3t")
	fmt.Println(v.Verify("s3cr3t"))
	fmt.Println(v.Verify("wrong"))
	// An unset secret fails closed: even an empty presented value is rejected.
	unset := webhttp.NewStaticTokenVerifier("")
	fmt.Println(unset.Verify(""))
}

Output:
true
false
false

func NewStatusRecorder ¶

func NewStatusRecorder(w http.ResponseWriter) *StatusRecorder

NewStatusRecorder wraps w. The recorded status defaults to http.StatusOK (200) and stays there until WriteHeader or the first Write records a status.