Request ID

​

Overview

​

Installation

import "github.com/go-mizu/mizu/middlewares/requestid"

​

Quick Start

app := mizu.New()
app.Use(requestid.New())

​

Configuration

​

Examples

​

Basic Usage

app.Use(requestid.New())

app.Get("/", func(c *mizu.Ctx) error {
    id := requestid.Get(c)
    c.Logger().Info("processing", "request_id", id)
    return c.JSON(200, map[string]string{"id": id})
})

​

Custom Header

app.Use(requestid.WithOptions(requestid.Options{
    Header: "X-Trace-ID",
}))

​

Custom Generator

var counter uint64

app.Use(requestid.WithOptions(requestid.Options{
    Generator: func() string {
        return fmt.Sprintf("req-%d-%d", time.Now().Unix(), atomic.AddUint64(&counter, 1))
    },
}))

​

ID Propagation

Client → X-Request-ID: abc123 → Server
                              → Response X-Request-ID: abc123

Client → (no header) → Server generates: xyz789
                    → Response X-Request-ID: xyz789

​

Logging with Request ID

app.Use(requestid.New())

app.Get("/", func(c *mizu.Ctx) error {
    logger := c.Logger().With("request_id", requestid.Get(c))
    logger.Info("handling request")
    // ...
    return c.JSON(200, data)
})

​

Pass to Downstream Services

func callService(c *mizu.Ctx) error {
    req, _ := http.NewRequest("GET", "http://service/api", nil)
    req.Header.Set("X-Request-ID", requestid.Get(c))
    // ...
}

​

API Reference

func New() mizu.Middleware
func WithOptions(opts Options) mizu.Middleware
func FromContext(c *mizu.Ctx) string
func Get(c *mizu.Ctx) string  // Alias for FromContext

​

Technical Details

​

Implementation

• Context Storage: Request IDs are stored in the request context using a private contextKey{} struct type to prevent collisions
• ID Generation: Default generator creates UUID v4-style identifiers using crypto/rand for cryptographic randomness
• Header Propagation: The middleware checks for existing request IDs in incoming headers and preserves them, or generates new ones if absent
• Response Headers: Request IDs are automatically added to response headers for client visibility

​

UUID v4 Format

• Uses 16 random bytes from crypto/rand
• Version bits (byte 6): Set to 0x40 to indicate version 4
• Variant bits (byte 8): Set to 0x80 to indicate RFC 4122 variant 2
• Final format: 32 hexadecimal characters in 5 groups (8-4-4-4-12)

​

Context Key Design

type contextKey struct{}

​

Flow

1. Extract request ID from incoming header (if present)
2. If no header, generate new ID using configured generator
3. Store ID in request context with private key
4. Set ID in response header
5. Continue to next handler

​

Best Practices

• Add early in middleware chain
• Include in all logs
• Pass to downstream services
• Use for error correlation

​

Testing

​

Related Middlewares

• timing - Performance tracing
• recover - Panic recovery with context