stringid

README

About

Package stringid provides string based ID generators, and accompanying middleware for assigning a request ID to standard HTTP request contexts.

Installing

Install in the usual Go fashion:

$ go get -u github.com/kenshaw/stringid

Using

stringid can be used similarly to the following:

// examples/goji/main.go
package main

import (
	"fmt"
	"net/http"

	goji "goji.io"
	"goji.io/pat"

	"github.com/kenshaw/stringid"
)

func main() {
	mux := goji.NewMux()
	mux.Use(stringid.Middleware())
	mux.HandleFunc(pat.New("/"), func(res http.ResponseWriter, req *http.Request) {
		fmt.Fprintf(res, "request id: %s\n", stringid.FromContext(req.Context()))
	})

	http.ListenAndServe(":3000", mux)
}

Please see the GoDoc listing for the full API listing.

Documentation

Overview

Package stringid provides string based ID generators, and accompanying middleware for assigning a request ID to standard HTTP request contexts.

Index

• func FromContext(ctxt context.Context) string
• func FromRequest(req *http.Request) string
• func Generate() string
• func HeaderMiddleware(headers ...string) func(http.Handler) http.Handler
• func Middleware(opts ...MiddlewareOption) func(http.Handler) http.Handler
• func WithID(ctxt context.Context, id string) context.Context
• func WithRequest(req *http.Request, id string) *http.Request
• type Generator
  • func NewUUIDGenerator() Generator
• type GeneratorFunc
  • func (f GeneratorFunc) Generate() string
• type GeneratorMiddleware
  • func (gm *GeneratorMiddleware) Handler(h http.Handler) http.Handler
• type MiddlewareOption
  • func WithGenerator(generator Generator) MiddlewareOption
  • func WithPrefix(prefix string) MiddlewareOption
• type PushGenerator
  • func NewPushGenerator(r *rand.Rand) *PushGenerator
  • func (pg *PushGenerator) Generate() string
  • func (pg *PushGenerator) String() string

Functions

func FromContext

func FromContext(ctxt context.Context) string

FromContext returns the ID previously set on the context.

func FromRequest

func FromRequest(req *http.Request) string

FromRequest returns the ID previously set on the request's context.

func Generate

func Generate() string

Generate generates a ID using the DefaultGenerator.

func HeaderMiddleware

func HeaderMiddleware(headers ...string) func(http.Handler) http.Handler

HeaderMiddleware creates a standard HTTP middleware handler that sets the request ID as read from one of the supplied headers.

Note: this should be used in a middleware chain only *AFTER* verifying the request header can be trusted.

func Middleware

func Middleware(opts ...MiddlewareOption) func(http.Handler) http.Handler

Middleware creates a standard HTTP middleware handler that sets a request ID on the HTTP context.

If no options are supplied, then a new push-style generator will be used.

By default, the Prefix will be set as "<hostname>/".

func WithID

func WithID(ctxt context.Context, id string) context.Context

WithID creates a new context with the supplied ID.

func WithRequest

func WithRequest(req *http.Request, id string) *http.Request

WithRequest returns the supplied HTTP request with a new context containing the supplied ID.

Types

type Generator

type Generator interface {
	// Generate generates a string ID.
	Generate() string
}

Generator is the common interface for ID generators.

var DefaultGenerator Generator

DefaultGenerator is the default ID generator.

func NewUUIDGenerator

func NewUUIDGenerator() Generator

NewUUIDGenerator creates a ID generator that generates UUIDv4 style IDs.

type GeneratorFunc

type GeneratorFunc func() string

GeneratorFunc wraps a standard func as a ID generator.

func (GeneratorFunc) Generate

func (f GeneratorFunc) Generate() string

Generate satisfies the Generator interface.

type GeneratorMiddleware

type GeneratorMiddleware struct {
	Prefix    string
	Generator Generator
}

GeneratorMiddleware provides standard HTTP middleware that sets a HTTP request ID based on the Prefix and a Generator's generated ID.

Useful for logging / tracing purposes.

func (*GeneratorMiddleware) Handler

func (gm *GeneratorMiddleware) Handler(h http.Handler) http.Handler

Handler returns a standard HTTP middleware handler for the generator.

type MiddlewareOption

type MiddlewareOption func(*GeneratorMiddleware)

MiddlewareOption is a middleware option.

func WithGenerator

func WithGenerator(generator Generator) MiddlewareOption

WithGenerator is a middleware option to set the generator used.

func WithPrefix

func WithPrefix(prefix string) MiddlewareOption

WithPrefix is a middleware option to set a prefix on generated IDs.

type PushGenerator

type PushGenerator struct {
	// contains filtered or unexported fields
}

PushGenerator is a push-style ID generator that satisifies the Generator interface.

func NewPushGenerator

func NewPushGenerator(r *rand.Rand) *PushGenerator

NewPushGenerator creates a new push ID generator.

func (*PushGenerator) Generate

func (pg *PushGenerator) Generate() string

Generate generates a unique, 20-character push-style ID.

func (*PushGenerator) String

func (pg *PushGenerator) String() string

String satisfies the fmt.Stringer interface.