replayproxy

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Oct 12, 2026 License: GPL-3.0 Imports: 31 Imported by: 1

Documentation

Overview

Package replayproxy records and replays what a server under test fetches from the internet: metadata providers, a podcast feed, an artwork CDN.

The server in its container makes those calls, out of reach of anything in the test process, so the only place to see them is a proxy in front of it: the container is started with HTTPS_PROXY naming this one and made to trust the certificates it signs (Options.CACert). Replay, the default, serves the cassettes and touches no network; Record fetches what no cassette holds; Rerecord refreshes everything; Verify compares the live shape without writing. A client in the same process uses Transport.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Drift

type Drift struct {
	Key           string
	StatusWas     int
	StatusIs      int
	FieldsAdded   []string
	FieldsRemoved []string
}

Drift is a recording whose live answer no longer has the same shape. Only the shape is compared, never the values: a field appearing, going or changing type is what breaks decoding.

func (Drift) String

func (d Drift) String() string

type Mode

type Mode int

Mode selects whether the proxy calls the real services.

const (
	// Replay serves from the cassettes and never reaches the network. A request with no recording is a loud failure, not an empty response.
	Replay Mode = iota
	// Record calls the real service for a request no cassette holds and writes what comes back; a request already recorded is served from its
	// recording, so recording a new test's lookups leaves every other recording as it was.
	Record
	// Verify calls the real service and compares the shape of its answer with the cassette, without writing; the recording is still what is served,
	// and drift is reported apart.
	Verify
	// Rerecord is Record refreshing what is recorded too: the first call of a request in a run replaces its recording, and the next is served the
	// fresh answer.
	Rerecord
)

type Options

type Options struct {
	// Mode defaults to Replay.
	Mode Mode
	// CassetteDir holds one JSON file per host. Empty is a proxy with no recordings at all, for a suite that keeps its server from the internet and
	// answers what it asks itself (Serve): it replays alone, and what no handler answers is a miss.
	CassetteDir string
	// Addr to listen on. Must be reachable from the container, so bind all interfaces (e.g. ":18080").
	Addr string
	// Logger receives replay misses and record notices; defaults to stderr.
	Logger *log.Logger
	// RecordHint ends the line logged for a request with no recording, saying how this suite records one ("record it with APP_TEST_RECORD=1").
	RecordHint string
	// CACert and CAKey are PEM files holding the certificate authority the proxy signs its per-host certificates with. When both are set the files
	// are loaded (created first if they do not exist), so the same authority can be mounted into a container that was started before the proxy. When
	// empty an in-memory authority is minted for this process.
	CACert, CAKey string
	// RedactQuery names query parameters dropped before a request is keyed and recorded: an API key or a version differs from one machine to the
	// next, and must neither decide a match nor be committed.
	RedactQuery []string
	// RedactBodyFields names JSON fields blanked in a recorded body: a login's token, which replay never needs since the proxy answers everything it
	// would authorise.
	RedactBodyFields []string
	// IgnoreHosts are hosts answered 204 and never recorded: the server talking to itself, or a service no cassette is about.
	IgnoreHosts []string
	// Trim cuts a 200 answer down before recording, by "host/path": a list of everything a service knows runs to megabytes, of which a suite reads a
	// few entries. The trimmed body is what is stored and served.
	Trim map[string]func(body []byte) ([]byte, error)
}

Options configure a Proxy.

type Proxy

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

Proxy is a MITM HTTP proxy backed by cassettes.

func New

func New(opts Options) (*Proxy, error)

New starts a proxy and returns it. Close stops it and, when it records, flushes the cassettes.

func (*Proxy) Addr

func (p *Proxy) Addr() string

Addr is the address the proxy is listening on.

func (*Proxy) Close

func (p *Proxy) Close() error

Close stops the proxy, writing any newly recorded cassettes.

func (*Proxy) Drifts

func (p *Proxy) Drifts() []Drift

Drifts returns the shape changes seen so far, in a stable order. Empty in any mode but Verify.

func (*Proxy) Misses

func (p *Proxy) Misses() []string

Misses returns the requests that had no recording, so a replay run can fail with the list rather than leaving tests to pass on empty responses.

func (*Proxy) Port

func (p *Proxy) Port() int

Port is the port the proxy is listening on.

func (*Proxy) Serve

func (p *Proxy) Serve(target string, h http.Handler) (stop func())

Serve answers every request for host with h instead of a cassette until stop is called, for a host the test plays itself. The host needs no DNS. "host/path" is that one path alone, for an answer no recording can hold, the time of day, while the host's other paths replay.

func (*Proxy) Transport

func (p *Proxy) Transport() *http.Transport

Transport is for a client in the same process, such as an SDK under test: it sends every request through the proxy, on the loopback address whatever the proxy listens on, and trusts the certificates the proxy mints.

Jump to

Keyboard shortcuts

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