http_gun/redaction
Decides which request and response data cassettes never store.
default() removes the credential headers authorization,
proxy-authorization, cookie, set-cookie, x-api-key, api-key,
x-goog-api-key, x-auth-token, x-access-token,
x-amz-security-token and x-csrf-token. One list of credential names,
key, api_key, apikey, access_token, token, client_secret,
code, refresh_token, id_token, signature, sig,
x-amz-security-token, x-goog-api-key, x-amz-signature,
x-amz-credential, password, secret and authorization, selects
what else is replaced by REDACTED:
- the value of a query parameter with a listed name;
- in an
application/x-www-form-urlencodedrequest or response body, the value of a pair with a listed name, with pairs split at∧; - in an
application/jsonor+jsonbody, the value of an object key with a listed name at any depth, which becomes"REDACTED". Every other byte of the body is kept.
request_fields_only limits the last two to request bodies, so response
bodies are stored as received apart from the body function.
Names are compared without case and ignoring - and _, so api_key
also selects API-KEY, apiKey and ApiKey. Escapes in a JSON key are
not decoded: the value of any key that contains a backslash escape is
replaced, whatever it spells, so an escaped credential name never
survives. A form or JSON body that cannot be
scanned (a form body that is not UTF-8, JSON with an unterminated string
or a missing value, as a truncated or aborted body has) or that is above
16 MiB is replaced as a whole by REDACTED-UNPARSABLE. Bodies with
another content type are kept; use with_body for those. Add your own
secrets, then pass the redaction to config.with_redaction:
let redaction =
redaction.default()
|> redaction.with_headers(["x-signature"])
|> redaction.with_query_parameters(["session"])
|> redaction.with_body_fields(["card_number"])
|> redaction.with_body(fn(bytes) { scrub_card_numbers(bytes) })
config.default() |> config.with_redaction(redaction)
A recording client stores requests and responses with the redaction
applied: listed headers are removed, listed query parameters keep their
name with the value REDACTED, credential body fields are replaced, and
the body function rewrites request bodies and whole response bodies. A
request-body rewrite (with_request_body) applies to request bodies only,
so it can normalise volatile request values without touching an answer. A
playback client applies the same redaction to the scripted request and to
each incoming request before comparing them, so a recorded cassette
matches the live code that made it. A redacted value therefore matches
any live value. The live request on the network is never changed.
Failures and telemetry events never contain a URL, query or body, nor a
request header. A send or batch failure after the response head
arrived keeps the response headers (error.headers) with the listed
headers removed. A waiting request’s headers are held in a closure that
crash reports print as a function reference. A playback client keeps the
requests it refused, redacted, for testing.verify; a crash report of
that client can print them.
Types
Values
pub fn body(redaction: Redaction, bytes: BitArray) -> BitArray
Apply the body function, if any. Credential fields are not replaced; use
body_for.
pub fn body_for(
redaction: Redaction,
headers: List(#(String, String)),
bytes: BitArray,
) -> BitArray
Rewrite a request or response body with the content-type in headers:
replace the credential fields of a form or JSON body, then apply the body
function, if any. This ignores request_fields_only, so it does not
predict a recorded response under that option; cassette.redact does.
The request-body rewrite is not applied; request applies it.
pub fn default() -> Redaction
Remove the credential headers, and replace credential query parameters and credential fields in form and JSON bodies, as the module documentation lists.
pub fn headers(
redaction: Redaction,
headers: List(#(String, String)),
) -> List(#(String, String))
Remove the redacted headers from a header list. The request header
allow-list is not applied; request applies it.
pub fn keeping_request_headers(
redaction: Redaction,
names: List(String),
) -> Redaction
Store and compare only these request headers, compared without case, and
content-type, which field redaction reads. A request header nobody named
is then left out of recordings and out of matching on both sides, so a
new header a client starts sending is never stored. The removed headers
still apply: a named credential header is removed. Repeated calls add
names. Response headers, trailers and the headers a failure keeps are not
affected.
pub fn request(
redaction: Redaction,
req: request.Request(BitArray),
) -> request.Request(BitArray)
Apply the redaction to a request: keep only the allowed request headers,
if any are named, remove headers, replace query values,
rewrite the body for its content-type, as body_for does, then apply the
request-body rewrite, if any.
pub fn request_fields_only(redaction: Redaction) -> Redaction
Replace credential fields in request bodies and the query only, and
store response bodies as received apart from with_body: with no body
function, a response body keeps its received chunks. Use it when a
recorded answer must replay exactly, for example a JSON error body with a
code field; you then own keeping secrets, such as an OAuth token answer,
out of your cassettes. It is the one call that stores more, it cannot be
undone, and calling it again changes nothing.
pub fn rewrites_bodies(redaction: Redaction) -> Bool
Whether this redaction has a body function. Credential fields are replaced
whatever this returns (in responses too, unless request_fields_only);
see rewrites_body_for.
pub fn rewrites_body_for(
redaction: Redaction,
headers: List(#(String, String)),
) -> Bool
Whether body_for can change a body with these headers: a body function
is set, or the content type is form or JSON. Like body_for, this
ignores request_fields_only; cassette.redact shows what a recording
stores.
pub fn with_body(
redaction: Redaction,
redact: fn(BitArray) -> BitArray,
) -> Redaction
Rewrite stored bodies with redact, after the credential fields are
replaced: each request body, and each response
body as a whole. A recording buffers a response body until it ends, within
the recording’s byte budget, and stores the rewritten body as one chunk,
so a secret split across chunks is still seen whole. Playback applies
redact to the scripted and the incoming request bodies before
comparing. Calling it again replaces the function.
pub fn with_body_fields(
redaction: Redaction,
names: List(String),
) -> Redaction
Also replace the value of these fields in form and JSON bodies, compared
as with_query_parameters compares names. Query parameters and body
fields share one list, so the names also apply to the query.
pub fn with_headers(
redaction: Redaction,
names: List(String),
) -> Redaction
Also remove these headers, compared without case, from stored requests and responses, including trailers, and from the response headers a failure keeps.
pub fn with_query_parameters(
redaction: Redaction,
names: List(String),
) -> Redaction
Replace the value of these query parameters with REDACTED, compared by
percent-decoded name without case and ignoring - and _. The parameter
order and every other byte of the query stay as sent. Query parameters
and body fields share one list, so the names also apply to form and JSON
bodies.
pub fn with_request_body(
redaction: Redaction,
rewrite: fn(BitArray) -> BitArray,
) -> Redaction
Rewrite request bodies only, after the credential fields are replaced and
after with_body: the body a recording stores, and both the scripted and
the incoming body that playback compares. Response bodies are never
passed to rewrite, so normalising volatile request values (a time, an
id, inline image data) cannot edit a recorded answer. Playback redacts a
stored body again, so redacting the rewrite’s output once more must change
nothing: rewrite, the credential fields and with_body must each leave
it as it is. Calling it again replaces the function.