Skip to content

blackbull.fault_injection.oracle_h1

blackbull.fault_injection.oracle_h1

Differential oracle for HTTP/1.1 implementation comparison.

Public surface for differentially comparing two HTTP/1.1 implementations against the same :class:~blackbull.fault_injection.Scenario — typically a reference (e.g. nginx) against a target under test.

Useful externally for client-library / proxy authors who want to assert behavioural parity between two implementations under wire-level fault injection.

Components:

  • :class:Category — the 9-way enum that buckets each example.
  • :data:ACCEPTED_CATEGORIES — pass-through set (OK, BOTH_REJECTED); divergences sit outside.
  • :class:SideOutcome — what one server returned (response, or exception / timeout) in normalised form.
  • :func:normalize_response, :func:categorize — the pure functions that compare the two sides.
  • :func:run_scenario — the async wrapper that drives a :class:~blackbull.fault_injection.Scenario against (host, port) and returns (SideOutcome, wire_bytes).
  • :data:PER_REQUEST_TIMEOUT_S — wall budget cap per side.

Test-suite-specific glue (fixtures, Hypothesis strategies, corpus capture, DiffContext) continues to live in the conformance harness — it is not part of the public surface.

Category

Bases: str, Enum

Why a differential example was (not) accepted.

Subclassing str makes the values JSON-serialisable directly and keeps assert ctx.category == 'OK'-style sites readable.

SideOutcome dataclass

One side's response in a differential pair.

Exactly one of (response, exception) is populated. timed_out is True if the failure was an :class:asyncio.TimeoutError from the per-example wait_for; we record it separately because timeouts are semantically distinct from other transport errors.

categorize(ng, bb)

Bucket a differential example into a :class:Category.

Order of the checks matters: both-rejected wins over individual transport failures so we don't flag inputs that nginx also refused.

normalize_response(resp)

Drop volatile / framing-only headers; preserve status + body.

run_scenario(host, port, scenario) async

Execute scenario against (host, port) and return (outcome, wire_bytes).

Drives the scenario through :meth:HTTP1Client.execute_scenario, which itself never raises; this wrapper only adds an outer asyncio.wait_for so a runaway scenario (e.g. trickled bytes plus a long read timeout) can't blow the per-side budget.

Returns the captured wire bytes (both servers receive identical bytes, so a single capture is enough for failure diagnostics).