http_gun/cassette
Loads, saves and records HTTP exchanges as cassette files.
Record once against a live server, then replay offline:
// Recording, for example behind a flag in a test helper.
let assert Ok(cassette.Recorded(client:, recording:)) =
cassette.record(settings, "test/cassettes/orders.json", cassette.options())
let _ = http_gun.send(client, req)
let assert Ok(_path) = cassette.finish(recording, duration.seconds(5))
http_gun.stop(client)
// Playback.
let assert Ok(script) = cassette.load("test/cassettes/orders.json", 1_048_576)
let assert Ok(client) = testing.playback(script, settings)
A cassette is readable JSON ("http_gun": 3), laid out over many
lines: a body or chunk that is valid UTF-8 containing a newline is stored
as {"lines": [..]}, one string per line, other UTF-8 as
{"text": ..}, and anything else as {"base64": ..}. Every body reads
back byte for byte. A file of another version fails with
UnsupportedVersion; describe_error says how to convert a schema 2
file written by HTTP Gun 0.1.x.
What a cassette stores follows the configuration’s redaction
(config.with_redaction). By default credential headers are removed, and
credential query parameters and credential fields of form and JSON
bodies are replaced by REDACTED; a form or JSON body that cannot be
scanned is stored as REDACTED-UNPARSABLE. Unlisted headers, parameters
and fields, and bodies of other content types, are stored exactly and can
contain secrets; add redaction for them.
A recording writes each exchange as it completes, within a byte budget,
and publishes the file atomically when finish succeeds. Capture
failures are separate from HTTP outcomes: the live client keeps working.
Exchanges are staged in a private <path>.http-gun-* directory next to the
destination. Success, abort, a failed finish, a capture failure, the
death of the process that called record and a crash of the recorder all
remove it. A writer stuck in a blocking file operation delays removal until
that operation returns. Nothing can remove it if the VM is killed or halted
mid-recording; such a directory is safe to delete.
Types
Why a cassette could not be loaded or parsed.
pub type CassetteError {
Missing
Io(operation: FileOperation, cause: FileCause)
Corrupt
UnsupportedVersion(version: Int)
TooLarge(limit: Int, observed: Int)
}
Constructors
-
Missing -
Io(operation: FileOperation, cause: FileCause) -
CorruptNot UTF-8 JSON in the cassette schema.
-
UnsupportedVersion(version: Int)A schema this version does not read. Schema 2, written by HTTP Gun 0.1.x, is converted on an earlier commit;
describe_errorsays how. -
TooLarge(limit: Int, observed: Int)
Why a filesystem operation failed.
pub type FileCause {
FileMissing
AlreadyExists
PermissionDenied
NoSpace
ReadOnlyFilesystem
NotDirectory
IsDirectory
CrossFilesystem
UnknownIoFailure
}
Constructors
-
FileMissing -
AlreadyExists -
PermissionDenied -
NoSpace -
ReadOnlyFilesystem -
NotDirectory -
IsDirectory -
CrossFilesystem -
UnknownIoFailure
A filesystem operation that failed.
pub type FileOperation {
OpenFile
ReadFile
WriteFile
CloseFile
CreateDirectory
SetPermissions
PublishFile
}
Constructors
-
OpenFile -
ReadFile -
WriteFile -
CloseFile -
CreateDirectory -
SetPermissions -
PublishFile
Why finish returned without a published file.
pub type FinishError {
Busy
WaitTimeout
CaptureFailed(RecordError)
}
Constructors
-
BusyRequests are still in flight; only an immediate finish returns this.
-
WaitTimeoutThe wait ended; finishing continues and a later call sees the outcome.
-
CaptureFailed(RecordError)
Why a recording could not start or failed while capturing.
pub type RecordError {
ClientFailed(http_gun.StartError)
CaptureLimit
IoFailure(operation: FileOperation, cause: FileCause)
DestinationExists
RecordingClosed
Interrupted
}
Constructors
-
ClientFailed(http_gun.StartError) -
CaptureLimitThe capture exceeded its byte budget or 10,000 exchanges, or the budget cannot hold the 42 bytes of envelope charged at start, or is above 16 MiB.
-
IoFailure(operation: FileOperation, cause: FileCause) -
DestinationExistsThe destination exists and
replace_existingwas not set. -
RecordingClosedThe recording is finishing or finished.
-
InterruptedThe recording’s owner exited, or a writer crashed.
How a recording publishes its file.
pub opaque type RecordOptions
A started recording: a live client and the capture to finish.
pub type Recorded {
Recorded(client: http_gun.Client, recording: Recording)
}
Constructors
-
Recorded(client: http_gun.Client, recording: Recording)
Values
pub fn abort(recording: Recording) -> Result(Nil, RecordError)
Abandon the capture; the live client keeps working. The staging directory beside the destination is removed before this returns, and nothing is published. A file already published is not removed.
pub fn describe_error(problem: CassetteError) -> String
pub fn describe_finish_error(problem: FinishError) -> String
pub fn describe_record_error(problem: RecordError) -> String
pub fn encode(script: testing.Script) -> String
Lay a script out as cassette text, schema 3, and nothing else: no
redaction is applied, so every header, query value and body is written as
the script holds it. A recording redacts as it captures; to keep
credentials out of a hand-built or older script, redact it first. A
stored cassette converts to schema 3, every body kept, as
parse(text, max_bytes) then encode. An exchange whose target a client
could not send (an empty host, port 0, a path without a leading /) is
written, but parse refuses the file as Corrupt.
pub fn finish(
recording: Recording,
wait: duration.Duration,
) -> Result(String, FinishError)
Publish the recording. Zero or less finishes now if nothing is in flight
and returns Busy otherwise. A positive wait refuses new requests, waits
up to wait for the requests in flight, then publishes. Once finished
or failed, every later call returns the same outcome.
pub fn load(
path: String,
max_bytes: Int,
) -> Result(testing.Script, CassetteError)
Read and parse a cassette file of at most max_bytes, reading no more
than max_bytes plus one byte. Never opens a network connection.
pub fn options() -> RecordOptions
Store at most 16 MiB and refuse to replace an existing file.
pub fn parse(
text: String,
max_bytes: Int,
) -> Result(testing.Script, CassetteError)
Parse a cassette of at most max_bytes.
pub fn record(
settings: config.Config,
path: String,
options: RecordOptions,
) -> Result(Recorded, RecordError)
Start a live client that records every exchange to path. Finish the
recording with finish and stop the client separately.
pub fn redact(
script: testing.Script,
redaction: redaction.Redaction,
) -> testing.Script
Apply redaction to stored exchanges, as a recording under it would have
stored them: requests redacted, response headers, trailers and the
headers a stored failure holds filtered,
and a rewritten response body held as one chunk. The matching settings of
script are kept.
Compare the result with the script to find what a grown policy would
still change in old cassettes, and encode the result to clean them
without recording again; writing the file is the caller’s, without the
recorder’s atomic publication or file mode, and cleaning a file does not
withdraw a secret already published in it. Both rely on redacting a stored
form once more changing nothing: redact twice and compare to tell an
unstable body function from a policy change.
pub fn replace_existing(options: RecordOptions) -> RecordOptions
Replace the destination file if it exists.
pub fn with_max_bytes(
options: RecordOptions,
bytes: Int,
) -> RecordOptions
The capture’s byte budget, from the 42 bytes of envelope charged at
start to 16 MiB. It is
charged on every byte the file will hold, and also on a response body
held for redaction, whose bytes stay charged, so a recording within the budget loads
with the same max_bytes. A session that needs more is split into several
recordings.