Make HTTP client recordings easier and safer

[dcrockwell]

Why

• Real-world HTTP recording/playback needs deterministic request identity that’s often more specific than “method + URL” (e.g. include/exclude headers/body, normalize volatile fields).
• Fixtures can contain secrets in both requests and responses (Authorization, cookies, tokens, PII). We need first-class hooks to scrub both before committing recordings.
• The previous API made it hard to express those needs cleanly, and the docs/examples had drift where some snippets were not representative of the tested code.

What changed (high level)

Breaking: dream_http_client recording/matching redesign (4.0.0)

• Recorder configuration is now builder-based: recorder.new() |> ... |> start().
• Matching is now key-function based: you provide a MatchKey = fn(RecordedRequest) -> String.
• Request transformer hook: RequestTransformer = fn(RecordedRequest) -> RecordedRequest runs before keying and before persistence.
  • API: recorder.request_transformer(...)
• Response transformer hook: ResponseTransformer = fn(RecordedRequest, RecordedResponse) -> RecordedResponse runs before persistence (Record mode only).
  • API: recorder.response_transformer(...)
• Ambiguous playback errors: if multiple recordings map to the same key during playback, lookup returns an Error (forces refining key/transformer).
• client.new in dream_http_client is now client.new() (function) for consistency with other builders.

Docs/snippets are now representative and tested

• Updated modules/http_client/README.md so recording docs cover:
  • modes (record/playback/passthrough)
  • request keys
  • request + response transformers
  • ambiguous-match behavior
  • per-request file storage and filename format
• Added runnable snippet coverage under modules/http_client/test/snippets/ (including response scrubbing) and ensured the README points at those snippets.
• Normalized example style: module.new() qualified (e.g. client.new(), recorder.new()), chained builder functions unqualified via import module.{...}.

Storage behavior

• Recording filenames include both a key hash and content hash:
  • {method}_{host}_{path}_{key_hash}_{content_hash}.json

Cross-module compatibility note (important)

• Some modules in this monorepo pin older major versions of dream_http_client.
  • Example: dream_opensearch pins dream_http_client >= 2.1.0 and < 3.0.0, so it must use client.new (value) rather than client.new().
  • This PR keeps those consumers compatible while updating dream_http_client itself.

How it works now (recording flow)

• Record:
  1. request_transformer runs on the incoming request.
  2. Key function computes a string key from the transformed request.
  3. response_transformer runs using (transformed_request, response).
  4. Scrubbed recording is persisted immediately to a per-request JSON file.
• Playback:
  1. Recordings are loaded from disk at startup.
  2. Incoming request is transformed + keyed and looked up.
  3. If multiple recordings share the key → Error("Ambiguous recording match …").

Test plan

• modules/http_client: make format && make check && make docs
• modules/opensearch: make check
• CI passes

Migration notes for users upgrading dream_http_client

• Replace old recorder start APIs with the builder pattern.
• Use request_transformer to normalize/scrub requests before keying/persistence.
• Use response_transformer to scrub recorded responses before persistence (Record mode only).
• Treat “Ambiguous recording match” as a signal to refine key/transformer (don’t disable the error).

[dcrockwell]

Restored modules/http_client/releases/release-3.0.0.md to match develop (historical release notes should not be updated to reflect newer APIs). Force-pushed amended commit accordingly.