middleware

func AuditInterceptor ¶

func AuditInterceptor(logger *slog.Logger, claimsFrom ClaimsLookup) connect.Interceptor

AuditInterceptor creates a Connect interceptor that produces audit log entries for every RPC call. Audit logs capture: who made the call (user ID, email), what procedure was called, when, the result (success/error code), the duration, and the OTel trace id when the request carries a span.

Audit records are emitted with log_type=audit on a child logger, so they can be routed to a dedicated audit sink (separate file, SIEM, compliance database) independent of operational logs. The record message is "audit.event" ([auditMessage]) — INFO on success, WARN on error.

claimsFrom is the project's ClaimsFromContext (the project owns the claims context key — see ClaimsLookup). When nil, or when no claims are present (unauthenticated request), the user is logged as "anonymous".

This is the slog-only constructor; it is fully backward compatible. For compliance-grade durable persistence (so projects can delete a hand-rolled DB-persisting interceptor), use AuditInterceptorWithSink to additionally fan each event out to an AuditSink.

func AuditInterceptorWithSink ¶

func AuditInterceptorWithSink(logger *slog.Logger, claimsFrom ClaimsLookup, sink AuditSink) connect.Interceptor

AuditInterceptorWithSink is AuditInterceptor plus a durable sink. Every RPC is logged to slog exactly as the slog-only variant does AND dispatched to sink.Record on a fresh bounded-timeout context off the request path, so the sink never blocks the RPC response. Passing a nil sink yields behavior identical to AuditInterceptor.

func CORSMiddleware ¶

func CORSMiddleware(allowOrigins []string, allowCredentials bool) func(http.Handler) http.Handler

CORSMiddleware returns an HTTP middleware that applies the CORS policy described by allowOrigins and allowCredentials.

Semantics (per the Fetch / CORS specs):

• When the request has no Origin header, no CORS headers are written and the request is passed through. Emitting ACAO with an empty value (or "*") on a same-origin request is a well-known footgun: the browser never needed CORS on it in the first place, and some caches key on the ACAO value.

• When allowOrigins contains "*" AND allowCredentials is true, this middleware panics. The combination is spec-invalid (browsers reject it) and must be caught at config validation time (the scaffolded config.Validate does). The panic is a belt-and- suspenders guard if validation is bypassed.

• When allowOrigins contains "*" and credentials are disabled, the request Origin is echoed back rather than a literal "*". Echoing keeps the response compatible with future credentialed callers (no silent breakage) and still satisfies "*" semantically.

• When specific origins are listed, an exact (case-insensitive) match on the Origin header is required. No match → no CORS headers (the browser will block the response).

Vary: Origin is always set so intermediate caches key on the Origin.

func ContextWithRequestID ¶

func ContextWithRequestID(ctx context.Context, id string) context.Context

ContextWithRequestID returns a copy of ctx with the given request ID attached. Exposed so tests and non-HTTP entrypoints can propagate the value into code paths that read RequestIDFromContext.

func HTTPAuth ¶

func HTTPAuth(
	authenticate func(token string) (*auth.Claims, error),
	withClaims func(ctx context.Context, claims *auth.Claims) context.Context,
) func(http.Handler) http.Handler

HTTPAuth returns HTTP middleware that validates Bearer tokens and populates the context with claims, mirroring the Connect auth interceptor for plain HTTP routes.

authenticate validates the raw token and returns the claims — pass the project's ValidateToken. withClaims stashes them on the context — pass the project's ContextWithClaims (the project owns the claims context key). If authenticate is nil (dev mode), all requests are allowed through untouched.

func HTTPStack ¶

func HTTPStack(logger *slog.Logger, claimsFrom ClaimsLookup) func(http.Handler) http.Handler

HTTPStack returns HTTP middleware that applies recovery, logging, and audit to plain HTTP handlers. This provides the same cross-cutting concerns as the Connect interceptors for routes that cannot use the Connect protocol (e.g. webhooks, OAuth callbacks, REST endpoints).

claimsFrom is the project's ClaimsFromContext (see ClaimsLookup); nil produces anonymous audit entries.

Auth is NOT included because REST routes often have different auth requirements (e.g. webhook signature verification instead of JWT). Use HTTPAuth separately for routes that need Bearer authentication.

func IdempotencyInterceptor ¶

func IdempotencyInterceptor(opts IdempotencyOptions) connect.Interceptor

IdempotencyInterceptor returns a Connect interceptor that deduplicates requests carrying an Idempotency-Key header. If the same key is seen within the TTL window, the cached response (or error) is returned without calling the handler again.

Keys are scoped per-procedure so the same key on different RPCs is treated as distinct. For the HTTP-layer equivalent (REST/webhook routes) see IdempotencyMiddleware.

When opts.CacheSize <= 0 the interceptor is disabled and nil is returned.

func IdempotencyMiddleware ¶

func IdempotencyMiddleware(cfg IdempotencyConfig) func(http.Handler) http.Handler

IdempotencyMiddleware returns an http.Handler that deduplicates requests carrying an Idempotency-Key header. If a request with the same key has already been served (and is still in the cache), the cached response is replayed without invoking the downstream handler.

Usage:

mux := http.NewServeMux()
cfg := middleware.IdempotencyConfig{CacheSize: 500, TTL: 30 * time.Minute}
handler := middleware.IdempotencyMiddleware(cfg)(mux)

func RateLimitInterceptor ¶

func RateLimitInterceptor(opts RateLimitOptions, claimsFrom ClaimsLookup) connect.Interceptor

RateLimitInterceptor returns a Connect interceptor that enforces a per-key token-bucket rate limit. Keys are derived in this order:

1. authenticated claim subject (claims.UserID) via claimsFrom, if available
2. peer IP from the Connect request/stream peer address

When opts.Rps <= 0 the interceptor is disabled and this function returns nil. Memory is bounded by an LRU cache of up to rateLimitCacheSize limiters; idle keys are evicted in LRU order so the interceptor is safe to expose to anonymous traffic. claimsFrom may be nil (all callers are then keyed by peer IP).

func Redact ¶

func Redact(v any, fields ...string) map[string]any

Redact accepts a struct (or pointer to struct) and a set of field names to mask. It returns a map[string]any mirroring the struct's exported fields, with the named fields replaced by "[REDACTED]".

Non-struct inputs return nil. Unexported fields are silently skipped.

Example:

type User struct {
    ID    string
    Email string
    Name  string
}
out := middleware.Redact(User{ID: "1", Email: "a@b.c", Name: "Alice"}, "Email")
// out == map[string]any{"ID": "1", "Email": "[REDACTED]", "Name": "Alice"}

func RequestIDFromContext ¶

func RequestIDFromContext(ctx context.Context) string

RequestIDFromContext returns the request ID attached to ctx, or "" if none is set. Useful for handlers and downstream logging sites that want to include the ID on custom log lines. Nil ctx returns "" (never panics) so callers in CLI/worker contexts can share the same helper.

The storage is pkg/observe's context key: a request ID set by this HTTP middleware is visible to observe.LoggingInterceptor (and vice versa) without a header round-trip.

func RequestIDMiddleware ¶

func RequestIDMiddleware() func(http.Handler) http.Handler

RequestIDMiddleware is an HTTP middleware that ensures every request carries a correlation ID. It must be wired ahead of the logging middleware so log records inherit the generated ID.

Behavior:

• If the inbound request has a non-empty RequestIDHeader, that value is trusted and reused. This lets edge proxies and upstream services stitch together a single trace across hops without coordination.

• Otherwise a 16-byte crypto/rand hex token is minted — the same shape observe.RequestIDInterceptor mints at the Connect layer, so IDs look uniform whichever layer assigned them. crypto/rand keeps IDs unpredictable to third parties that might otherwise enumerate them.

• The chosen ID is exposed to downstream middleware/handlers via the request context (RequestIDFromContext) and echoed on the response header so the client can log it for later correlation.

func SecurityHeadersMiddleware ¶

func SecurityHeadersMiddleware(cfg SecurityHeadersConfig) func(http.Handler) http.Handler

SecurityHeadersMiddleware returns an HTTP middleware that sets OWASP-recommended security response headers:

• Content-Security-Policy — locks down what the browser may load
• X-Content-Type-Options: nosniff — prevents MIME sniffing
• Referrer-Policy — limits Referer leakage
• Permissions-Policy — opts out of powerful browser APIs
• Strict-Transport-Security — forces HTTPS (production only)

Headers relevant to health/pprof endpoints (health checks don't need CSP stringency, but we still set nosniff/referrer/permissions there for consistency and defense in depth). Callers wire this in at the outermost HTTP layer so every response benefits — including /healthz, /readyz, /metrics, and REST/webhook routes that bypass the Connect interceptor chain.

When cfg.Enabled is false, this becomes a no-op.