blackbull.client.scenario_oracle

blackbull.client.scenario_oracle

Deprecation shim — moved to :mod:blackbull.fault_injection.

Sprint 46 grouped the HTTP/1.1 differential oracle alongside the scenario model under :mod:blackbull.fault_injection. Import from there going forward::

from blackbull.fault_injection import Category, run_scenario  # ...

This shim re-exports the names that used to live here and will be removed no earlier than BlackBull v0.45.0 (and not before 2026-09-16) — three releases ahead AND one month, whichever is later, per the project's deprecation policy.

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).