interceptor

README

HTTP Client interceptor

HTTP client interceptor system for Go. Compose middleware around http.RoundTripper to inspect, modify, retry, or short-circuit requests and responses, enabling a clean and extensible way to enrich and control outgoing HTTP calls.

Install

go get github.com/fervbmx/interceptor

Usage

Import both packages:

import (
    "net/http"

    "github.com/fervbmx/interceptor"
    "github.com/fervbmx/interceptor/interceptors"
)

// Flow: RequestLogging → Header → BasicAuth → http.DefaultTransport
client := &http.Client{
    Transport: interceptor.NewTransport(
        nil,
        interceptors.Header("X-API-KEY", "secret"),
        interceptors.BasicAuth("user", "pass"),
        interceptors.RequestLogging(nil),
    ),
}

Pass nil as the first argument to use http.DefaultTransport, or pass a custom http.RoundTripper as the base transport.

Built-in interceptors

Interceptor	Description
Header(key, value)	Sets a header on every request
BasicAuth(user, password)	Sets Basic authentication
RequestLogging(opts)	Emits structured slog attributes

Custom interceptors

Write your own interceptor.Middleware to hook into the request/response lifecycle. Call next to continue the chain, or return early to short-circuit it.

// Log every request and its status code.
func Logging(req *http.Request, next interceptor.HandlerFunc) (*http.Response, error) {
    log.Printf("→ %s %s", req.Method, req.URL)
    resp, err := next(req)
    if err != nil {
        return nil, err
    }
    log.Printf("%s %s → %d", req.Method, req.URL, resp.StatusCode)
    return resp, nil
}

client := &http.Client{
    Transport: interceptor.NewTransport(
        http.DefaultTransport,
        Logging,
    ),
}

License

MIT

Documentation

Overview

Package interceptor provides an HTTP interceptor system. It allows composing middleware interceptors that can inspect, modify, retry, or short-circuit HTTP requests and responses flowing through a standard http.RoundTripper.

Index

• type HandlerFunc
• type Middleware
• type Transport
  • func NewTransport(defaultTransport http.RoundTripper, interceptors ...Middleware) *Transport
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)
  • func (t *Transport) Use(interceptors ...Middleware) *Transport

Types

type HandlerFunc

type HandlerFunc func(req *http.Request) (*http.Response, error)

HandlerFunc represents the next step in the interceptor chain. It takes an HTTP request and returns a response or error.

type Middleware

type Middleware func(req *http.Request, next HandlerFunc) (*http.Response, error)

Middleware defines an interceptor. It receives the outgoing request and a next function representing the next processing step in the interceptor chain.

type Transport

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

Transport implements http.RoundTripper by running a chain of interceptors in front of a default transport.

func NewTransport

func NewTransport(defaultTransport http.RoundTripper, interceptors ...Middleware) *Transport

NewTransport creates a new Transport with the given default RoundTripper and interceptors. If defaultTransport is nil, http.DefaultTransport is used. Interceptors are executed in the order provided.

// Using the default transport:

client := &http.Client{
		Transport: interceptor.NewTransport(nil, AInterceptor, BInterceptor),
}

// Using a custom default transport:

client := &http.Client{
		Transport: interceptor.NewTransport(customTransport, AInterceptor, BInterceptor),
}

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip executes the interceptor chain. The underlying transport is reached only if each interceptor calls next.

func (*Transport) Use

func (t *Transport) Use(interceptors ...Middleware) *Transport

Use appends one or more interceptors to the chain. They are appended after any interceptors already registered.

t := interceptor.NewTransport(nil, AuthInterceptor).Use(MetricsInterceptor)