json_body

Versions marked “overview” do not contain this page. Selecting one opens that version’s documentation overview.

Rewrites JSON request bodies with JSON Pointer add, remove, replace, and extract, and response bodies with remove and extract.

Configuration Notes

Applies mutating operations in one pass over a StreamBuffer-held body. Extract copies a pointer’s JSON into filter_metadata, structured metadata, or a request header without changing the body. filter_metadata values over 256 bytes are dropped; use structured metadata for nested or larger values. Extract promotion requires a single JSON value with only trailing whitespace after the document; non-whitespace trailing content blocks all extract destinations. Header values over 256 bytes or containing control characters are also skipped. Mutating pointers must not overlap (equal or prefix) within a direction. Duplicate extract pointers are rejected; nested extract pointers are allowed. Unused subtrees are copied as byte spans. Missing parents, missing replace/extract targets, and missing context values skip that operation (the original member is left unchanged). Duplicate object member names are not canonicalized. Remove drops every matching member. Replace and add-over-existing rewrite every matching member; add injects once only when no match exists. Extract keeps the last matching value. Add /- appends to arrays only; on an object the operation is skipped (same as a missing parent). Invalid JSON follows on_invalid ([OnInvalidBehavior]).

Extract-only directions are ReadOnly and defer extract until end of stream so promotion sees the full StreamBuffer body. Mixed extract and rewrite uses one walk; metadata-sourced add/replace resolve lazily at each splice site and are skipped when the extract value is not yet available.

Body signature preservation: extract-only directions never modify the body bytes, so upstream HMAC or signature checks remain valid. Directions with any mutating op (add, remove, replace) may alter inter-token whitespace even when the op has no runtime effect (e.g., a replace whose target is missing). Callers that need a stable body signature should not combine extract and mutating ops in the same direction; use a separate extract-only json_body filter earlier in the pipeline.

Response Content-Length is already committed when body hooks run. response_add and response_replace are rejected at config time. response_remove shrinks are padded with trailing spaces so the transferred byte count matches the committed Content-Length. This achieves redaction, not bandwidth reduction.

Content-type gating: when content_types is set, only bodies whose Content-Type matches one of the listed prefixes (case-insensitive) are processed; non-matching bodies pass through unchanged. When the list is empty (the default), all content types are processed. The compression filter has an equivalent knob.

Memory usage: peak heap per concurrent request is approximately 2 × max_body_bytes per mutating direction (the StreamBuffer input and the rewrite output coexist during the walk). Extract-only directions allocate no output buffer, so their peak is 1 × max_body_bytes. Size max_body_bytes for the workload, not the default.

Configuration

Example

filter: json_body
content_types:
  - application/json
request_extract:
  - pointer: /model
    metadata: original.model
  - pointer: /stream
    header: X-Stream
request_add:
  - pointer: /tenant
    value: acme
  - pointer: /api_key
    env_var: TENANT_API_KEY
  - pointer: /original_model
    metadata: original.model
request_remove:
  - /password
request_replace:
  - pointer: /model
    value: forced-model
response_remove:
  - /internal