transport

README

Go HTTP transports & middlewares for outgoing HTTP requests

Chaining transports is a pattern originally inspired by this article https://dev.to/stevenacoffman/tripperwares-http-client-middleware-chaining-roundtrippers-3o00. This pattern is similar to middleware pattern which is used to enrich a context of http request coming to your application. There are multiple use-cases where this pattern comes handy such as request logging, caching, authentication and even implementation of retry mechanisms.

Examples

Set up HTTP client, which sets User-Agent, Authorization and TraceID headers automatically:

authClient := http.Client{
    Transport: transport.Chain(
        http.DefaultTransport,
        transport.SetHeader("User-Agent", userAgent),
        transport.SetHeader("Authorization", authHeader),
        transport.TraceID,
    ),
    Timeout: 15 * time.Second,
}

Or debug all outgoing requests globally within your application:

debugMode := os.Getenv("DEBUG") == "true"

http.DefaultTransport = transport.Chain(
    http.DefaultTransport,
    transport.If(debugMode, transport.LogRequests),
)

Authors

• Golang.cz
• See list of contributors.

License

MIT license

Documentation

Index

• func Chain(base http.RoundTripper, mw ...func(http.RoundTripper) http.RoundTripper) *chain
• func CloneRequest(orig *http.Request) *http.Request
• func If(condition bool, transport func(http.RoundTripper) http.RoundTripper) func(http.RoundTripper) http.RoundTripper
• func LogRequests(next http.RoundTripper) http.RoundTripper
• func Retry(baseTransport http.RoundTripper, maxRetries int) func(http.RoundTripper) http.RoundTripper
• func SetHeader(header string, value string) func(http.RoundTripper) http.RoundTripper
• func SetHeaderFunc(header string, fn func(req *http.Request) string) func(http.RoundTripper) http.RoundTripper
• type RoundTripFunc
  • func (f RoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error)

Functions

func Chain

func Chain(base http.RoundTripper, mw ...func(http.RoundTripper) http.RoundTripper) *chain

Chain wraps given base RoundTripper, which is used to make HTTP requests (e.g. http.DefaultTransport) with RoundTripper middlewares.

The middlewares can print, debug or modify request/response headers, cookies, context timeouts etc.

Note: Per stdlib docs, RoundTrip should not modify the original request, except for consuming and closing the request's body. Thus, it's advised to clone the original request before modifying it, e.g. golang.org/x/oauth2: https://cs.opensource.google/go/x/oauth2/+/refs/tags/v0.13.0:transport.go;l=50.

A typical use case is to set User-Agent, Authorization or TraceID headers:

authClient := http.Client{
    Transport: transport.Chain(
        http.DefaultTransport,
        transport.SetHeader("User-Agent", userAgent),
        transport.SetHeader("Authorization", authHeader),
        transport.SetHeader("x-extra", "value"),
		transport.TraceID,
    ),
    Timeout: 15 * time.Second,
}

Or debug all outgoing requests in a debug mode:

http.DefaultTransport = transport.Chain(
	http.DefaultTransport,
	transport.LogRequests,
)

func CloneRequest

func CloneRequest(orig *http.Request) *http.Request

CloneRequest creates a shallow copy of a given request to comply with stdlib's http.RoundTripper contract:

RoundTrip should not modify the request, except for consuming and closing the Request's Body. RoundTrip may read fields of the request in a separate goroutine. Callers should not mutate or reuse the request until the Response's Body has been closed.

func If

func If(condition bool, transport func(http.RoundTripper) http.RoundTripper) func(http.RoundTripper) http.RoundTripper

If sets given transport if given condition is true. Otherwise it sets nil transport, which will be ignored.

Example:

http.DefaultTransport = transport.Chain(
  http.DefaultTransport,
  transport.If(debugMode, transport.LogRequests),
)

func LogRequests

func LogRequests(next http.RoundTripper) http.RoundTripper

func Retry

func Retry(baseTransport http.RoundTripper, maxRetries int) func(http.RoundTripper) http.RoundTripper

func SetHeader

func SetHeader(header string, value string) func(http.RoundTripper) http.RoundTripper

func SetHeaderFunc

func SetHeaderFunc(header string, fn func(req *http.Request) string) func(http.RoundTripper) http.RoundTripper

Types

type RoundTripFunc

type RoundTripFunc func(r *http.Request) (*http.Response, error)

RoundTripFunc, similar to http.HandlerFunc, is an adapter to allow the use of ordinary functions as http.RoundTrippers.

func (RoundTripFunc) RoundTrip

func (f RoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error)