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.
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 ¶
New starts a proxy and returns it. Close stops it and, when it records, flushes the cassettes.
func (*Proxy) Drifts ¶
Drifts returns the shape changes seen so far, in a stable order. Empty in any mode but Verify.
func (*Proxy) Misses ¶
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) Serve ¶
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.