blackbull.fault_injection.h2_server

blackbull.fault_injection.h2_server

Programmable malformed HTTP/2 server.

Production mode is refused; non-loopback binds require allow_remote=True. Use raw-byte steps when normal frame encoding cannot express a fault.

H2FaultServer

Programmable HTTP/2 server emitting a ScenarioH2.

Async context manager: enter to bind + start accepting, exit to shut down. self.url is set after enter and gives the URL a real h2c client can dial.

Parameters

scenario: The ScenarioH2 the executor walks for each accepted connection. host: Bind host. Defaults to '127.0.0.1' — binding to a non-localhost interface is rejected unless allow_remote is set (the misbehaviour mode is for local tests only). port: Bind port. Defaults to 0 (kernel-assigned random port). allow_remote: Bypass the localhost-only safety check. Off by default. ssl_context: Optional ssl.SSLContext. When provided, the server terminates TLS and self.url is https://...; ALPN must offer h2 so clients negotiating H/2 over TLS (httpx, curl --http2, …) connect cleanly. When None (default), the server speaks plaintext h2c — usable with prior-knowledge clients only.

Attributes

url: http://<host>:<port>/ after start, or https://... when a TLS context is provided. last_result: ScenarioH2Result from the most recently completed connection. None before any client has connected.

wait_for_connection_done(timeout=5.0) async

Block until a client has connected and the scenario finished.

H2FaultServerError

Bases: RuntimeError

Raised when H2FaultServer cannot start.

The most common cause is running in a production context: the deliberate-misbehaviour machinery refuses to start when the framework's production signal (BLACKBULL_ENV=production) — or the explicit BB_PRODUCTION override — is set, regardless of how it was reached.

serialize_frame(frame)

Convert a FrameBase instance to wire bytes.

Restricted to the classes in ROUND_TRIP_FRAME_CLASSES, and to frames require_canonical accepts; anything else goes through SendRawBytes.