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:

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

What to remove from stored exchanges. The default() credentials are always removed; the functions below only add to the lists, except request_fields_only, which stops replacing fields in response bodies.

pub opaque type Redaction

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.

✨ Search Document