replayproxy

package
v0.6.1 Latest Latest
Warning

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

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

Documentation

Overview

Package replayproxy is a record/replay HTTP proxy for what a server under test fetches from the internet: a media server's metadata providers, a podcast feed, an artwork CDN.

A tool that asks its server to look something up never makes the call itself: the server, in a container, does. That puts the call out of reach of anything that hooks Go's http.RoundTripper, so go-vcr and friends cannot see it. The only layer that can is a proxy in front of the container.

The container is started with HTTPS_PROXY naming this proxy and made to trust the certificates it signs: a .NET server on Linux trusts whatever SSL_CERT_FILE points at, so it is handed the authority in Options.CACert, and a Node server can be told not to check (NODE_TLS_REJECT_UNAUTHORIZED=0, safe in a throwaway container). In Replay mode - the default, and what CI uses - the answers are served from the cassettes on disk and no network is touched. Record mode calls the real service for a request no cassette holds and writes what comes back, leaving every recording already there alone; Rerecord mode refreshes those too, and Verify mode holds each recording against what the service answers now without writing anything.

A client in the same process, such as an SDK under test, goes through the same proxy with 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 one recorded interaction whose live response no longer has the shape the cassette captured.

Only the shape is compared, never the values: which result a service ranks first this week is none of our business, but a field appearing, vanishing or changing type is exactly what breaks decoding, in the server or in a client of ours, and with it everything that depends on the lookup.

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 what comes
	// back against the cassette, without writing. The recorded response is
	// still what gets served, so a test outcome never depends on what a
	// service happened to return today - drift is reported separately.
	Verify
	// Rerecord is Record refreshing what is recorded as well: the first time
	// the proxy sees a request it calls the real service and the answer
	// replaces the recording, and the same request again in that run is
	// served the fresh answer without another call.
	Rerecord
)

type Options

type Options struct {
	// Mode defaults to Replay.
	Mode Mode
	// CassetteDir holds one JSON file per host.
	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 from every request before
	// it is keyed and recorded: an API key changes from one operator to the
	// next, and a version or an architecture from one machine to the next,
	// and none of them may decide whether a cassette matches, nor be
	// committed with it.
	RedactQuery []string
	// RedactBodyFields names JSON fields whose string value is replaced in a
	// recorded response body. A service's login answers with a bearer token
	// for the server's own account, which is a credential the repository must
	// not carry; replay needs none of it, because the proxy answers the calls
	// that token would authorise.
	RedactBodyFields []string
	// IgnoreHosts are hosts this proxy answers 204 for and never records: the
	// server talking to itself on its own container address, which NO_PROXY
	// cannot exclude because the address is only known once the container is
	// running, or to a service whose answers are no part of what these
	// cassettes are about (a clock, a news feed, a what-is-my-address).
	IgnoreHosts []string
	// Trim cuts a response down before it is recorded, keyed by host and
	// path ("lists.example.org/v1/everything"): a service's list of
	// everything it knows runs to megabytes, of which a suite reads the few
	// entries for its own fixtures. Only a 200 is trimmed. The trimmed body
	// is what is stored and served, in Record and Verify alike, so replay
	// sees the same.
	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 the returned func is called. It is for the hosts a test plays itself - a podcast feed whose episodes it adds as it goes - which have no service to record: nothing for such a host is recorded, replayed or counted as a miss. The host needs no DNS: the container sends the whole url to the proxy.

A host and a path, written as Trim's keys are ("clock.example.org/v1/time"), is that one path alone: an answer no recording can hold, the time of day, from a service whose other paths replay as they were recorded.

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