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.
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
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.
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.
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.
pub fn request(
redaction: Redaction,
req: request.Request(BitArray),
) -> request.Request(BitArray)
Apply the redaction to a request: remove headers, replace query values and
rewrite the body for its content-type, as body_for does.
pub fn rewrites_bodies(redaction: Redaction) -> Bool
Whether this redaction has a body function. Credential fields are replaced
whatever this returns; 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.
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.