middleware

package
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 3, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source
const ContextKeyAuthz = "chok.authz"

ContextKeyAuthz is the gin.Context key under which the active authz.Authorizer lives. AttachAuthz writes it; RequireAuthz / RequireAuthzInDomain read it.

Exported as a string constant so application code can override the gin context (e.g. mount a per-tenant Authorizer on a sub-router) without depending on this package's internals.

Variables

This section is empty.

Functions

func AccessLog

func AccessLog(logger log.Logger) gin.HandlerFunc

AccessLog logs request method, path, status, and latency. When a tracing span is active, trace_id / span_id are attached so log entries correlate with the distributed trace.

func AttachAuthz added in v0.1.4

func AttachAuthz(az authz.Authorizer) gin.HandlerFunc

AttachAuthz installs the supplied Authorizer onto the gin.Context for downstream RequireAuthz / RequireAuthzInDomain calls. Production chok wiring (parts/http.go OptionalDependencies + Init) calls this automatically when an AuthzComponent is registered, so application code rarely needs to invoke it directly.

Tests that exercise RequireAuthz without spinning up the full component registry should mount AttachAuthz on their gin engine before the protected routes.

func Authn

func Authn(parser TokenParser, resolver PrincipalResolver) gin.HandlerFunc

Authn creates a Bearer-token authentication middleware.

parser: validates the token (built-in jwt.Manager or custom TokenParser). Panics if nil — configuration errors are caught at startup, not at request time. resolver: optional, enriches Principal from subject+claims.

func CORS

func CORS(opts ...CORSOption) gin.HandlerFunc

CORS returns a CORS middleware.

func Logger

func Logger(l log.Logger) gin.HandlerFunc

Logger injects the given logger into the request context. The logger is enriched with the request's request_id (if present) so downstream code calling log.FromContext(ctx) gets structured per-request logging for free.

Both ctxval (internal, used by handler error logging) and log.WithContext (public, used by business code) are populated.

func LoggerFrom

func LoggerFrom(ctx context.Context) log.Logger

LoggerFrom extracts the logger from context (user-facing helper). Prefers log.FromContext (canonical path); falls back to ctxval for backward compatibility.

func Metrics

func Metrics(reg prometheus.Registerer) gin.HandlerFunc

Metrics returns a gin middleware that instruments HTTP requests with the RED (Rate, Errors, Duration) metrics — the industry-standard golden signals for any HTTP service:

  • http_requests_total{method, path, status} — counter
  • http_request_duration_seconds{method, path} — histogram
  • http_requests_in_flight — gauge

reg is typically obtained from MetricsComponent.PrometheusRegistry(). The middleware is safe to use with any prometheus.Registerer, and is idempotent across re-initialisation: on AlreadyRegisteredError (which happens when HTTPComponent.Init runs after a prior Init/Close cycle) the existing collectors are reused instead of panicking.

func Recovery

func Recovery() gin.HandlerFunc

Recovery returns a middleware that recovers from panics and returns 500. The response uses handler.WriteResponse for format consistency with normal errors (code/reason/message/request_id). The panic and stack trace are logged via the context logger if available; if not (e.g. the panic fired before the Logger middleware ran), the trace is written to stderr so the incident is never silently swallowed.

func RequestID

func RequestID() gin.HandlerFunc

RequestID generates or propagates a request ID via the X-Request-ID header. Client-supplied IDs are truncated to 128 chars and reduced to a strict ASCII safe-set ([A-Za-z0-9._-]) before propagation. The whitelist approach blocks log-injection vectors that the previous "strip < 0x20" filter missed: high-byte UTF-8 sequences such as U+2028 (LINE SEPARATOR) / U+2029 (PARAGRAPH SEPARATOR) used to be passed through verbatim and could split log lines in viewers that interpret them as breaks.

As a convenience, the resolved client IP (c.ClientIP()) is also stored in the request context so downstream handlers — in particular the account module's login rate limiter — can key on source address without needing direct access to *gin.Context.

func RequestIDFrom

func RequestIDFrom(ctx context.Context) string

RequestIDFrom extracts the request ID from context (user-facing helper).

func RequireAuthz added in v0.1.4

func RequireAuthz(obj, act string) gin.HandlerFunc

RequireAuthz is the chok-blessed authorization middleware for global / single-tenant routes. It calls

authz.Authorize(ctx, principal.Subject, obj, act)

against the Authorizer attached to the gin.Context.

Outcomes:

  • allowed=true → c.Next()
  • allowed=false → 403 PermissionDenied
  • error → 500 InternalError (logged with subject/obj/act)
  • no Principal → 401 Unauthenticated (Authn middleware missing)
  • no Authorizer → 500 InternalError ("authz not wired" — fix wiring)

The previous URL-based form (Authz(az), object=route pattern, action=HTTP method) was removed in v0.3 because (a) policy DBs filled with URL strings are fragile under refactors and (b) Casbin idiom is business-code (sub, obj, act) tuples decoupled from transport.

func RequireAuthzInDomain added in v0.1.4

func RequireAuthzInDomain(obj, act, domainParam string) gin.HandlerFunc

RequireAuthzInDomain is the multi-tenant cousin of RequireAuthz. It reads the tenant id from the named gin path parameter (typically "wsid", "orgid", "tenant") and calls

authz.AuthorizeInDomain(ctx, principal.Subject, dom, obj, act)

requiring the configured Authorizer to satisfy authz.DomainAuthorizer.

Fail-closed posture (SPEC v0.3.2): when the active Authorizer does NOT implement DomainAuthorizer the middleware refuses the request with 500 — silent degradation to Authorize would drop the domain constraint and let cross-tenant requests through. Wire the right Authorizer (chok's authz/casbin satisfies it natively) or this route is unsafe to expose.

domainParam name is consulted via c.Param; an empty value yields 400 InvalidArgument (the route declared :wsid but the request didn't match — almost certainly a routing bug in the application).

func Timeout

func Timeout(d time.Duration) gin.HandlerFunc

Timeout returns a middleware that injects a context deadline into each request. Handlers (and libraries they call — DB drivers, HTTP clients) that respect context cancellation will stop work when the deadline fires, and the middleware writes a 504 if no response was produced.

A zero or negative duration disables the middleware (pass-through).

This is a cooperative timeout: the handler runs synchronously on the same goroutine, so gin.Context is never accessed concurrently. If a handler ignores context cancellation (e.g. a pure CPU loop), it will block until it returns on its own. For hard process-level limits, configure http.Server.WriteTimeout instead.

func Tracing

func Tracing(serviceName string) gin.HandlerFunc

Tracing returns a middleware that creates a server span for each HTTP request using the global OpenTelemetry TracerProvider. Span name follows the OpenTelemetry HTTP semantic conventions: "METHOD route" (e.g. "GET /api/v1/posts/:id").

When the TracerProvider is a no-op (tracing disabled), the middleware adds negligible overhead — the span is never sampled and attributes are not recorded.

This middleware should be placed early in the chain (after Recovery, RequestID) so that downstream middleware and handlers inherit the span context. The Logger middleware will automatically pick up trace_id / span_id from the span context.

Types

type CORSOption

type CORSOption func(*corsConfig)

CORSOption configures the CORS middleware.

func WithAllowCredentials

func WithAllowCredentials(allow bool) CORSOption

WithAllowCredentials enables Access-Control-Allow-Credentials: true, permitting browsers to send cookies / Authorization headers on cross- origin requests. Incompatible with a wildcard Origin — CORS() panics at setup time if both are configured, because the combination is a credential-leak vector (any origin could read authenticated responses).

func WithAllowHeaders

func WithAllowHeaders(headers ...string) CORSOption

func WithAllowMethods

func WithAllowMethods(methods ...string) CORSOption

func WithAllowOrigins

func WithAllowOrigins(origins ...string) CORSOption

func WithExposeHeaders

func WithExposeHeaders(headers ...string) CORSOption

WithExposeHeaders lists response headers that browsers should make visible to JavaScript. By default only simple headers are accessible to cross-origin fetchers; anything else (X-Request-ID, Retry-After, custom pagination cursors, etc.) needs explicit listing here or the client JS can't read them.

func WithMaxAge

func WithMaxAge(seconds int) CORSOption

type PrincipalResolver

type PrincipalResolver func(ctx context.Context, subject string, claims map[string]any) (auth.Principal, error)

PrincipalResolver builds a full Principal from the JWT subject and claims. Optional: when nil, the middleware constructs a minimal Principal from subject and claims only. Receives claims so that roles/tenant can be read directly from the token without an extra database lookup.

type TokenParser

type TokenParser interface {
	Parse(token string) (subject string, claims map[string]any, err error)
}

TokenParser parses a token string and returns the subject and claims. The built-in jwt.Manager implements this interface (HS256). Users needing RS256/EdDSA/external IdP can provide their own implementation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL