truewire
Source on GitHub

ADR 0018: A request field minted per call is ignored by a located path under match.ignore

  • Status: accepted
  • Date: 2026-09-15

Context

ADR 0007 gave the mock redacted: flat key names stripped from a request before it is compared with a recording. Flat names were chosen because the comparison already knows which substructure it is looking at, and that covered every case at the time: a signed query string (signature, timestamp, recvWindow), a body key, a named-object JSON-RPC params entry.

It does not cover a WebSocket login. Bitget's is {"op": "login", "args": [{"apiKey", "passphrase", "timestamp", "sign"}]}: the per-connection timestamp and sign live inside an object inside a positional array. redacted never reaches into a positional params, because a bare list element has no name. A recording necessarily holds a stale signature, so no recorded login could ever match. Every private channel that logs in first could not replay: 9 Python cases were strict xfail in clients/bitget, and the TypeScript and Go ports skipped the same channels. The same shape (a signature nested in a frame, not at its top level) is common among exchange WebSocket logins and signed JSON-RPC bodies.

Stretching redacted to accept paths was considered and rejected. A flat name like ids[] or a.b is a legitimate query-parameter name, so one string could mean either a name or a path. Stripping a name at every depth was also rejected: it cannot tell a volatile sign from a same-named field that should still be compared.

A per-example volatile list was rejected too. Which fields a transport mints is a property of the endpoint's signing, not of one recording, just as redacted and envelope are declared per endpoint.

Decision

An endpoint declares match: {ignore: [<path>, ...]}, a sibling of redacted and envelope. Each entry is a path in the response-path grammar (dotted keys and bracket indices, [-1] for the last element; no $ root, wildcard or slice), rooted at the whole request value the mock compares: the parsed WebSocket frame, or the parsed HTTP JSON body. The addressed field is dropped from both the real request and the recording before any comparison, including selector and params extraction: a dict key is removed, and a list element is blanked to null so the other paths' indices keep naming the elements they were written for (Bybit's {"op": "auth", "args": [apiKey, expires, signature]} ignores args[1] and args[2]). A path that does not resolve on one side is skipped, so a keyed field need not be recorded at all. redacted then applies as before.

match is a block rather than a bare list so a later matching rule has a place to go without another top-level key.

A query item or header is flat, so redacted remains the declaration for those. The mock never compares headers.

As with redacted, match.ignore only widens what the mock accepts. It is never read when an example is replayed through the real client, and uniqueness checking (ADR 0007) runs after it: two recordings that differ only in an ignored field are ambiguous.

Consequences

A client whose login or signed body nests its volatile fields declares their paths on that endpoint and needs no change to the mock or to any language's replay helpers. @truewire/testing, twtest and truewire-testing all run truewire mock as a child process and pick the rule up unchanged. Private stream replays that previously had to be skipped can run.

A frame with no JSON-RPC method must also declare its selector (envelope.selector, envelope.params) for match_rpc to consider it at all. match.ignore does not remove that need.

Two endpoints recording the same login frame on one mock (Bitget's classic and UTA logins share a construction and a mock URL) would tie. The recording goes on one of them, and the other is answered from it.

A field whose position varies (args[*]) cannot be named. No wildcard is admitted, for the same reason the response-path grammar refuses one; it waits for a real case.