requestid

package
v14.0.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: BSD-3-Clause, BSD-3-Clause Imports: 5 Imported by: 0

README

Request ID Middleware

This middleware gives every request a unique ID and puts it in the X-Request-Id response header. When a client sends that header, its value is kept instead. The ID is what lets you follow one request through your logs, and across service boundaries when several services pass it along.

Features

  • Automatic Request ID Generation: Generates a unique request ID for each incoming request if not provided by the client.
  • Customizable ID Generation: Allows custom ID generation logic.
  • Header Management: Automatically sets the request ID in the response headers (X-Request-Id).
  • Integration with Iris Context: Reads the request ID straight off the Iris context.

Installation

To use the requestid middleware, you need to import it in your Iris application:

import (
    "github.com/kataras/iris/v14"
    "github.com/kataras/iris/v14/middleware/requestid"
)

Usage

Basic Setup

Here is a basic example of how to use the requestid middleware in an Iris application:

package main

import (
    "github.com/kataras/iris/v14"
    "github.com/kataras/iris/v14/middleware/requestid"
)

func main() {
    app := iris.New()
    app.Use(requestid.New())

    app.Get("/", func(ctx iris.Context) {
        ctx.WriteString(requestid.Get(ctx))
    })

    app.Listen(":8080")
}
Custom ID Generation

You can provide a custom ID generation function to the middleware. This function can implement any logic to generate the request ID.

package main

import (
    "github.com/kataras/iris/v14"
    "github.com/kataras/iris/v14/middleware/requestid"
)

func main() {
    app := iris.New()

    customGen := func(ctx iris.Context) string {
        return "custom-id"
    }

    app.Use(requestid.New(customGen))

    app.Get("/", func(ctx iris.Context) {
        ctx.WriteString(requestid.Get(ctx))
    })

    app.Listen(":8080")
}
Hash-Based ID Generation

The middleware also provides a hash-based ID generator that uses the request's hash to generate a fixed-length request ID. This can be useful for generating consistent IDs for similar requests.

package main

import (
    "github.com/kataras/iris/v14"
    "github.com/kataras/iris/v14/middleware/requestid"
)

func main() {
    app := iris.New()
    // True to include the request's body hash in the ID.
    app.Use(requestid.New(requestid.HashGenerator(true)))

    app.Get("/", func(ctx iris.Context) {
        ctx.WriteString(requestid.Get(ctx))
    })

    app.Listen(":8080")
}

Server-Generated IDs (v14)

DefaultGenerator reuses a client-supplied X-Request-ID header when present. If request IDs end up in logs and clients should not be able to choose or forge them (log injection), use ServerOnlyGenerator, which always generates a new server-side UUID and ignores the inbound header:

app.Use(requestid.New(requestid.ServerOnlyGenerator))

Documentation

Overview

Package requestid assigns an ID to every request and exposes it through Context.ID, the "X-Request-Id" header and the `Get` function.

Its entry point is New(generator ...Generator), which returns a Handler. The variadic parameter is NOT a functional-options list: it is an optional domain-typed Generator (at most one is read), so that `requestid.New()` and `requestid.New(requestid.ServerOnlyGenerator)` both read naturally. The package has no settings beyond that, so there is no Options struct.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Get

func Get(ctx *context.Context) string

Get returns the Request ID or empty string.

A shortcut of `Context.ID().(string)`.

func Hash

func Hash(ctx *context.Context, includeBody bool) string

Hash returns the hex-encoded sha256 hash of the request. It does not capture error, instead it returns an empty string.

func New

func New(generator ...Generator) context.Handler

New returns a new request id middleware. It optionally accepts an ID Generator. The Generator can stop the handlers chain with an error or return a valid ID (string). If it's missing then the `DefaultGenerator` will be used instead.

The variadic parameter is an optional Generator, not a functional-options list: only the first one is read.

Types

type Generator

type Generator func(ctx *context.Context) string

Generator defines the function which should extract or generate a Request ID. See `DefaultGenerator` and `New` package-level functions.

var DefaultGenerator Generator = func(ctx *context.Context) string {
	id := ctx.ResponseWriter().Header().Get(xRequestIDHeaderKey)
	if id != "" {
		return id
	}

	if v := ctx.Header(xRequestIDHeaderKey); isValidRequestID(v) {
		id = v
	}

	if id == "" {

		id = uid.NewString()
	}

	ctx.SetHeader(xRequestIDHeaderKey, id)
	return id
}

DefaultGenerator is the default `Generator` that is used when nil is passed on `New` package-level function. It extracts the ID from the "X-Request-ID" request header value or, if missing, it generates a new UUID(v4) and sets the header and context value.

Security note: DefaultGenerator trusts a client-supplied "X-Request-ID" header. If request IDs end up in logs or are otherwise trusted downstream and clients should not be able to choose or forge them (log injection / forgery), use ServerOnlyGenerator instead.

See `Get` package-level function too.

var ServerOnlyGenerator Generator = func(ctx *context.Context) string {

	if id := ctx.ResponseWriter().Header().Get(xRequestIDHeaderKey); id != "" {
		return id
	}

	id := uid.NewString()
	ctx.SetHeader(xRequestIDHeaderKey, id)
	return id
}

ServerOnlyGenerator is a `Generator` that always generates a new server-side UUID(v4) and ignores any client-supplied "X-Request-ID" request header. Use it instead of DefaultGenerator when clients must not be able to choose or forge the request ID, for example to prevent log forgery via the header:

app.Use(requestid.New(requestid.ServerOnlyGenerator))

func HashGenerator

func HashGenerator(includeBody bool) Generator

HashGenerator uses the request's hash to generate a fixed-length Request ID. Note that one or many requests may contain the same ID, so it's not unique.

Jump to

Keyboard shortcuts

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