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.

Retrieving the Request ID

Use FromContext to retrieve the request ID from downstream handlers:

id := requestid.FromContext(c) // reads ContextKey from context store

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

Index

• Constants
• Variables
• func CounterGenerator(prefix string) func() string
• func FromContext(c *celeris.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.

Variables

var DefaultConfig = Config{
	Header: "x-request-id",
}

DefaultConfig is the default request ID configuration.

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.

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 New

func New(config ...Config) celeris.HandlerFunc

New creates a request ID middleware with the given config.

Example

package main

import (
	"github.com/goceleris/middlewares/requestid"
)

func main() {
	// Zero-config: generates UUID v4, propagates existing x-request-id.
	_ = requestid.New()
}

Example (Counter)

package main

import (
	"github.com/goceleris/middlewares/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

	// 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
}

Config defines the request ID middleware configuration.