blackbull.server.http1_actor

blackbull.server.http1_actor

HTTP/1.1 Actor classes for the BlackBull actor model.

HTTP1Actor drives the keep-alive loop for one TCP connection. RequestActor owns the lifetime of a single HTTP request.

BadRequestError

Bases: Exception

Raised by :meth:HTTP1Actor._parse on an RFC 9112 framing violation.

The actor's keep-alive loop catches this and sends a 400 Bad Request before closing the connection — never tries to dispatch the malformed request to the app.

HTTP1Actor

Bases: Actor

Drives the HTTP/1.1 keep-alive loop for one connection.

Supervisor strategy: isolate — an unhandled exception from a RequestActor closes the connection without crashing sibling connections.

If aggregator is None the actor falls back to the legacy direct- dispatcher path (fires events via app._dispatcher directly), so that BlackBull apps without a full EventAggregator still receive lifecycle events.

run() async

Keep-alive loop — process requests until connection closes.

HeaderTooLargeError

Bases: Exception

Raised when a request header line or the whole header block exceeds the configured limit (BB_HEADER_MAX_LINE / BB_HEADER_MAX_TOTAL).

The actor answers with 431 Request Header Fields Too Large (RFC 6585 §5) and closes the connection. Distinct from :class:BadRequestError because the response status differs.

NotImplementedFramingError

Bases: Exception

RFC 9112 §6.1 — the request used a Transfer-Encoding the server does not implement. Answered with 501 Not Implemented (a separate response code from :class:BadRequestError's 400).

RequestActor

Bases: Actor

Owns one request's app boundary: what the app is called with.

Shared by both protocol actors — H/1 reuses one instance per connection via :meth:bind; H/2 builds one per stream. Owns the app-facing representation (the native :class:Connection on the default lane, the materialized ASGI scope on BB_FORCE_ASGI_SCOPE=1), binds the raw recipient before any wrapper exists, and calls the app.

The request-lifecycle Level B events are emitted by the application layer (BlackBull._dispatch / __call__) — the cross-transport emission points — not here. The actor layer emits only the Level B error event, for exceptions that escape the app call (e.g. a raising global middleware).

bind(conn, recipient, send)

Point this actor at the next request on the same connection.

HTTP/1.1 dispatches one request at a time per connection, so the instance is free between requests and rebinding it is indistinguishable from building a new one — except for the allocation, which the keep-alive loop would otherwise pay on every request. app, aggregator and force_asgi are per-connection and stay put.

Deliberately not available to HTTP/2, whose streams are concurrent: two live requests sharing one actor would interleave their fields.

UnsupportedVersionError

Bases: Exception

RFC 9110 §15.6.6 — the request-line carried a well-formed HTTP/x.y version whose major version the server does not support (RFC9112-2.3-INVALID-VERSION). Answered with 505 HTTP Version Not Supported and the connection is closed. Distinct from :class:BadRequestError: the request grammar was valid.