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:

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

What to remove from stored exchanges. The default() credentials are always removed; the functions below only add to the lists.

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.

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.

✨ Search Document