Documentation
¶
Overview ¶
Package requestid provides request ID middleware for celeris.
New reads the request ID from the incoming header (default: "x-request-id"). If absent or invalid (non-printable ASCII, >128 bytes), a UUID v4 is generated using a buffered random source that batches 256 UUIDs per crypto/rand syscall. The ID is written to the response header and stored in the context under ContextKey ("request_id").
Key exported symbols:
- New — constructor; accepts an optional Config.
- Config — Header, Generator, DisableTrustProxy, EnableStdContext, Skip, SkipPaths.
- FromContext — retrieve the ID from a celeris.Context in downstream handlers.
- FromStdContext — retrieve the ID from a stdlib context.Context (requires Config.EnableStdContext).
- CounterGenerator — monotonic "{prefix}-{N}" generator; zero syscalls after init.
- ContextKey — the context-store key ("request_id").
Register before logger so every log line carries the request ID.
Documentation ¶
Full guides and examples: https://goceleris.dev/docs/observability#request-ids
Index ¶
Examples ¶
Constants ¶
const ContextKey = "request_id"
ContextKey is the context store key for the request ID.
Variables ¶
This section is empty.
Functions ¶
func CounterGenerator ¶
CounterGenerator returns a monotonic ID generator: "{prefix}-{counter}". Zero syscalls after init. For non-cryptographic use cases.
The counter is process-local (in-memory atomic). Multiple processes or restarts will produce overlapping sequences. For cross-process uniqueness, include a process identifier in the prefix.
func FromContext ¶
FromContext returns the request ID from the context store. Returns an empty string if no request ID was stored.
Uses celeris.Context.GetString so the lookup covers all three sources: the dedicated requestID field set by celeris.Context.SetRequestID (preferred, zero-alloc), the stringKeys map from celeris.Context.SetString, and the any-typed c.keys map from user code that called c.Set(ContextKey, id) directly.
func FromStdContext ¶
FromStdContext returns the request ID from a stdlib context.Context. Returns an empty string if no request ID was stored.
func New ¶
func New(config ...Config) celeris.HandlerFunc
New creates a request ID middleware with the given config.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/requestid"
)
func main() {
// Zero-config: generates UUID v4, propagates existing x-request-id.
_ = requestid.New()
}
Output:
Example (Counter) ¶
package main
import (
"github.com/goceleris/celeris/middleware/requestid"
)
func main() {
// Deterministic counter generator for testing.
_ = requestid.New(requestid.Config{
Generator: requestid.CounterGenerator("req"),
})
}
Output:
Types ¶
type Config ¶
type Config struct {
// Skip defines a function to skip this middleware for certain requests.
Skip func(c *celeris.Context) bool
// SkipPaths lists paths to skip (exact match).
SkipPaths []string
// Generator returns a new request ID. Default: buffered UUID v4.
Generator func() string
// Header is the header name to read/write. Default: "x-request-id".
Header string
// DisableTrustProxy, when true, ignores inbound request ID headers
// and always generates a fresh ID. This prevents request ID spoofing
// from untrusted clients. Default: false (inbound headers are trusted).
DisableTrustProxy bool
// EnableStdContext, when true, stores the request ID in the stdlib
// context.Context via context.WithValue, making it available to
// downstream code that only has access to context.Context (e.g.,
// database drivers, gRPC interceptors). This adds one allocation
// per request. Default: false (request ID stored only in celeris
// Context store).
EnableStdContext bool
}
Config defines the request ID middleware configuration.
Source Files