requestid

README

Request ID

Unique Identifier for each HTTP request. Useful for logging, propagation and e.t.c.

Installation

The only requirement is the Go Programming Language.

$ go get github.com/kataras/requestid

Getting Started

Import the package:

package main

import "github.com/kataras/requestid"

Wrap a handler with the Handler function and retrieve the request ID using the Get function:

import "net/http"

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request){
        id:= requestid.Get(r)
        w.Write([]byte(id))
    })

    http.ListenAndServe(":8080", requestid.Handler(mux))
}

By-default the requestid middleware uses the X-Request-Id header to extract and set the request ID. It generates a universally unique identifier when the request header is missing. Use custom logic to extract and set the request ID using HandlerWithGenerator:

import "net/http"

func main() {
    // extract from a request header and set to the response header.
    gen := func(w http.ResponseWriter, r *http.Request) string {
        id:= r.Header.Get("X-Custom-Id")
        if id == "" {
            // [custom logic to generate ID...]
        }
        w.Header().Set("X-Custom-Id", id)
        return id
    }

    // [...]
    router := requestid.HandlerWithGenerator(mux, gen)
    http.ListenAndServe(":8080", router)
}

When you want an identifier of request based on the headers, body and e.t.c. use the HashGenerator helper. Note that, the request id will be the same if the same client sends the same requests (that's the goal here):

func main() {
    // [...]

    includeBodyOnHash := false
    gen := requestid.HashGenerator(includeBodyOnHash)

    requestid.HandlerWithGenerator(mux, gen)

    // [...]
}

License

This software is licensed under the MIT License.

Documentation

Index

• Variables
• func Get(r *http.Request) string
• func Handler(next http.Handler) http.HandlerFunc
• func HandlerWithGenerator(next http.Handler, gen Generator) http.HandlerFunc
• func Hash(r *http.Request, includeBody bool) string
• func Set(r *http.Request, id string) *http.Request
• type Generator
  • func HashGenerator(includeBody bool) Generator

Variables

var ErrorHandler http.Handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusInternalServerError)
	fmt.Fprint(w, http.StatusText(http.StatusInternalServerError))
})

ErrorHandler is the handler that is executed when a Generator returns an empty string.

Functions

func Get

func Get(r *http.Request) string

Get returns the Request ID of this request. A prior call to the Handler or HandlerWithGenerator is required.

func Handler

func Handler(next http.Handler) http.HandlerFunc

Handler wraps a handler with the requestid middleware using the `DefaultGenerator`. See `Get` package-level function to retrieve the generated-and-stored request id. See `HandlerWithGenerator` to use a custom request ID generator.

func HandlerWithGenerator

func HandlerWithGenerator(next http.Handler, gen Generator) http.HandlerFunc

HandlerWithGenerator same as `Handler` function but it accepts a custom `Generator` to extract (and set) the request ID.

func Hash

func Hash(r *http.Request, includeBody bool) string

Hash returns the sha1 hash of the "r" request. It does not capture error, instead it returns an empty string.

func Set

func Set(r *http.Request, id string) *http.Request

Set manually sets a Request ID for this request. Returns the shallow copy of given "r" request contains the new ID context value. Can be called before Handler execution to modify the method of extraction of the ID.

Note: Caller should manually set a response header for the client, if necessary.

See `Get` package-level function too.

Types

type Generator

type Generator func(w http.ResponseWriter, r *http.Request) string

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

var DefaultGenerator Generator = func(w http.ResponseWriter, r *http.Request) string {
	id := w.Header().Get(xRequestIDHeaderKey)
	if id != "" {
		return id
	}

	id = r.Header.Get(xRequestIDHeaderKey)
	if id == "" {
		uid, err := uuid.NewRandom()
		if err != nil {
			return ""
		}

		id = uid.String()
	}

	setHeader(w, id)
	return id
}

DefaultGenerator is the default `Generator`. It extracts the ID from the "X-Request-Id" request header value or, if missing, it generates a new UUID(v4) and sets the response header.

See `Get` package-level function too.

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.