requestid

Documentation

Overview

Package requestid provides request ID middleware for celeris.

The middleware reads the request ID from the incoming X-Request-Id header (configurable). If the incoming ID is absent or invalid, a new UUID v4 is generated using a buffered random source that batches 256 UUIDs per crypto/rand syscall. The ID is set on both the response header and the context store under ContextKey ("request_id").

Basic usage:

server.Use(requestid.New())

Custom header and deterministic generator for testing:

server.Use(requestid.New(requestid.Config{
    Header:    "x-trace-id",
    Generator: requestid.CounterGenerator("req"),
}))

Input Validation

Incoming IDs are validated: only printable ASCII (0x20-0x7E) is accepted, with a maximum length of 128 characters. Invalid or oversized IDs are silently replaced with a fresh UUID.

DisableTrustProxy

Config.DisableTrustProxy controls whether the inbound request header is accepted. When false (default), a valid inbound header is propagated as-is. When true, the inbound header is always ignored and a fresh ID is generated:

server.Use(requestid.New(requestid.Config{
    DisableTrustProxy: true,
}))

Retrieving the Request ID

Use FromContext to retrieve the request ID from downstream handlers:

id := requestid.FromContext(c)

Use FromStdContext to retrieve it from a stdlib context.Context:

id := requestid.FromStdContext(ctx)

Skipping

Use Config.Skip for dynamic skip logic or Config.SkipPaths for path exclusions. SkipPaths uses exact path matching.

Custom Generator Validation

Custom generator output is validated with the same rules as inbound headers. If the generator returns an invalid or empty string, it is retried up to 3 times before falling back to the built-in UUID.

CounterGenerator returns a monotonic ID generator ("{prefix}-{N}") with zero syscalls after initialization.

Middleware Order

Register first -- all downstream middleware can access the request ID.

Index

• Constants
• func CounterGenerator(prefix string) func() string
• func FromContext(c *celeris.Context) string
• func FromStdContext(ctx context.Context) string
• func New(config ...Config) celeris.HandlerFunc
• type Config

Examples

• New
• New (Counter)

Constants

const ContextKey = "request_id"

ContextKey is the context store key for the request ID.

Functions

func CounterGenerator

func CounterGenerator(prefix string) func() string

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

func FromContext(c *celeris.Context) string

FromContext returns the request ID from the context store. Returns an empty string if no request ID was stored.

func FromStdContext

func FromStdContext(ctx context.Context) string

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()
}

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"),
	})
}

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.