DEV Community: TOKUJI

Does a from-scratch async server actually hold up? 16,384 Slowloris connections and a 2-hour soak

TOKUJI — Mon, 20 Jul 2026 12:50:59 +0000

It's one thing for a from-scratch server to pass a conformance suite on a good day. It's another for it to survive a client that opens sixteen thousand connections and then just… stops talking. Writing your own HTTP server is a great way to learn protocols; it's also a great way to discover, in production, that you never handled the slow-client case. So before I trust BlackBull — my pure-Python protocol framework — with anything, I wanted two boring numbers: does it stay responsive under a Slowloris attack, and does it leak over a long soak? Here's how I measured both, and what came back.

(Part of my ongoing BlackBull series. Earlier posts cover the HTTP/2 and multi-protocol internals; this one is purely about robustness.)

Test 1: Slowloris — the attack of doing nothing, slowly

Slowloris is the laziest denial of service there is. You don't flood the server; you open a connection, send part of a request — a request line and one header — and then dribble a byte every few seconds, forever. Each half-open request ties up a slot. Open enough of them and a naive server runs out of room to accept anyone real. There's no bandwidth spike to alarm on; the server is simply, quietly, full.

The defence is a deadline. BlackBull gives every request a header-completion budget (BB_HEADER_TIMEOUT, 10 s by default): if the request headers aren't finished in time, the connection is reaped with a 408 before it ever reaches a handler or occupies a request task. That's the design. The question is whether it works — and, more usefully, what the curve looks like as the attacker scales up.

So I wrote a characterisation that holds N Slowloris connections open — each having sent a partial request head and nothing more — and then, while they're held, fires a burst of ordinary, legitimate requests and measures how long each one takes to be accepted and served. Sweep N from 0 to 16,384. A healthy server keeps serving real traffic with flat latency; a vulnerable one climbs, then starts timing out. On a clean c7i.2xlarge, 200 legitimate probes per point:

Slowloris connections held	legitimate p99	failures
0	4.2 ms	0
1,024	2.9 ms	0
4,096	3.1 ms	0
8,192	3.1 ms	0
16,384	3.0 ms	0

Fresh-connection latency is flat at ~3 ms all the way to 16,384 held connections, with zero failures across a thousand probes. The curve has no knee. The deadline reaper frees each slow slot before it can crowd the accept path, so the slow connections never occupy a request task — they cost a socket and nothing more.

The nice part is that the server tells you it's happening. With logging at INFO, each reaped connection prints exactly why:

408 Request Timeout (slowloris defence) — peer=('10.0.0.7', 41288)
    sent 23 bytes in 10.0s without completing headers

That's the mechanism the number is measuring, made visible.

Test 2: the soak — leaks don't show up in five seconds

A throughput benchmark runs for 30 seconds and tells you nothing about a slow resource leak. File descriptors that never close, actor inboxes that grow unbounded, a buffer that's retained one request too long — these only show up over hours, and only if you're watching the right counters. So the second test is a soak: a fixed, moderate load held for a long time, with the process sampled the whole way through.

Two hours, 256 concurrent connections, mixed traffic (plaintext, JSON, a 1 KiB body), sampling RSS, file descriptors, connection count, and tracemalloc totals every 60 seconds. The pass/fail question is simple: after the initial warm-up, does anything trend?

metric	start	end	2nd-half drift
VmRSS	48 MB	78 MB	+0.1 %
tracemalloc.current	9.1 MB	6.1 MB	−33 %
established connections	256	0	—
open file descriptors	265	8	—

Reading it: RSS climbs once during warm-up (workers fork, buffers and steady-state structures allocate) and then plateaus — the drift across the second hour is +0.1 %, i.e. flat. Python-tracked allocations actually trend down over the run, the opposite of a leak. And when the load stops, connections drain to zero and file descriptors fall back to eight — everything the run acquired, it gave back. Verdict: leak-free plateau. 120 samples with no trend is a much stronger statement than a clean 30-second window.

Why it holds: the actor model does the bookkeeping

Neither result is an accident of tuning; both fall out of how connections are structured. Every connection is owned by a ConnectionActor with its own lifecycle, and the deadline subsystem is a single scanner that reaps connections whose header/body/idle budgets have expired. There's no per-connection timer to leak and no shared lock to contend on — a slow or idle connection is just an entry the scanner will collect. When a connection ends, its actor and everything it owns are torn down together, which is why the file-descriptor count returns exactly to baseline.

The honest caveats, because a single run is a single run:

Not a security audit. This is a resilience characterisation, not adversarial red-teaming. Real hostile testing covers many more shapes — HTTP/2 RST_STREAM floods, malformed-frame fuzzing, header-table attacks. This measures one well-known attack and one stability question.
One soak, moderate load. Two hours at 256 connections is enough to catch an obvious leak; it isn't days at saturation. A genuinely slow leak, or one that only appears under a specific protocol mix, could still be hiding. It's a floor, not a proof.
Single-host numbers. The absolute latencies include loopback and co-tenancy; treat the shape (flat, no trend) as the result, not the millisecond values.

Try it

The Slowloris characterisation and the soak harness are both in the repo, and both are self-contained — the Slowloris tool even boots its own server, so it's a one-liner against a clean box:

pip install blackbull
git clone https://github.com/TOKUJI/BlackBull && cd BlackBull

# Slowloris: sweep held-connection counts, measure legitimate-request latency
python bench/hostile_repro/characterize_slowloris.py \
    --sweep 0,1024,4096,8192,16384 --probes 200

Point it at your own server if you like — the interesting question isn't whether BlackBull holds up, it's whether yours does. If your framework doesn't enforce a header-completion deadline, the curve above is the one to go looking for.

Source, the harnesses, and the full numbers are at github.com/TOKUJI/BlackBull. The rest of the series covers how the pure-Python HTTP/2 and multi-protocol layers underneath actually work.

BlackBull v0.57.0, 2026-07-18.

gRPC Without grpcio: How BlackBull Serves All Four RPC Shapes in Pure Python

TOKUJI — Tue, 14 Jul 2026 15:23:13 +0000

If you have ever wanted to serve a gRPC endpoint from Python without compiling grpcio's C++ core — or wondered what gRPC actually looks like on the wire — this post is for you. It introduces BlackBull, a pure-Python ASGI framework I've been building, and walks through how its gRPC support works, what it's good for, and — just as importantly — what it's not for. By the end you'll have a server that a stock grpcurl can call: pip install, one file, no certificates, no protoc, no config.

(This continues my earlier series: BlackBull goes multi-protocol and How a from-scratch HTTP/2 server actually works. You don't need either to follow along.)

What is BlackBull?

BlackBull is a pure-Python ASGI 3.0 web framework that implements HTTP/1.1, HTTP/2, and WebSocket at the protocol level — its own frame parsing, its own HPACK, its own flow control. No C extensions, no wrapping a foreign HTTP library. A few things distinguish it:

Zero-ceremony deploy. app.run() is the whole story. There is no separate ASGI runner to pick, no gunicorn -k some.worker.Class, no YAML. For a static site, blackbull serve ./public gives you ETag handling and HTTP/2 in one command.
Every byte is debuggable. Because there are no C extensions, you can set a breakpoint anywhere — inside HPACK header decoding, inside the flow-control window accounting — and step through it with pdb. If you've ever tried to figure out why a server sent RST_STREAM, you know why this matters.
Multi-protocol, one process. HTTP/1.1, HTTP/2, WebSocket, gRPC, and MQTT 5.0 are all served from a single python app.py. Not five servers behind a reverse proxy — one process, and for the HTTP/2-based protocols, one port.
Actor-model internals. Each connection is owned by a ConnectionActor that spawns per-connection protocol actors, each with its own inbox loop. Isolation between connections comes from the actor structure, not from shared locks.
RFC-grade conformance. The HTTP/2 stack passes h2spec, the WebSocket stack passes the Autobahn test suite, and HTTP behaviour is checked by a differential oracle against nginx.
Typed throughout (PEP 561), and — unusually — programmable fault injection: the same protocol code can be told to misbehave on command, so you can use BlackBull in CI to test how your HTTP clients handle a server that sends malformed frames or stalls mid-response.

One honest disclosure up front: BlackBull is a personal learning project. Correctness over the wire matters more than API stability, and the versioning is ZeroVer (0.MINOR.PATCH — v0.53.3 as of this writing). If you need a stability guarantee, that's a real consideration. If you want to understand or test protocols, it's arguably a feature.

gRPC is just HTTP/2 (mostly)

Here is the observation that makes BlackBull's gRPC support possible: gRPC is not a separate transport. It is HTTP/2 with a few extra rules:

Requests are POST /package.Service/Method with content-type: application/grpc.
Each message on the wire is length-prefixed: 1 byte of compression flag, 4 bytes of big-endian length, then the payload.
The status code (grpc-status) is delivered in HTTP/2 trailing headers after the last message.

That's most of it. If you already have a complete HTTP/2 implementation — frames, HPACK, flow control, trailers — then gRPC is a thin layer on top. And BlackBull does, so its entire gRPC layer is about six files in blackbull/grpc/: the registry, the codec (that 5-byte prefix), compression, status codes, and the bridge to the framework. No new protocol actor, no second listening socket. A gRPC call is just another HTTP/2 stream to the connection layer.

The simplest possible gRPC server

from blackbull import BlackBull
from blackbull.grpc import GrpcServiceRegistry, GrpcStatus

app = BlackBull()
grpc = GrpcServiceRegistry()


@grpc.method('/echo.Echo/Echo')
async def echo(request: bytes, context) -> bytes:
    if not request:
        context.abort(GrpcStatus.INVALID_ARGUMENT, 'empty request message')
    return request


# Server-streaming: an async generator that yields response messages.
@grpc.method('/echo.Echo/Split')
async def split(request: bytes, context):
    for token in request.split():
        yield token


app.enable_grpc(grpc)


@app.route(path='/')
async def index():
    return 'REST here; gRPC service echo.Echo on the same port.'


app.run(port=50051)   # cleartext HTTP/2 — add certfile=/keyfile= for TLS

Install with pip install 'blackbull[grpc]' and run the file. That's it — note what's missing: no certificate step, no protoc, no config. gRPC normally rides on TLS + ALPN, but BlackBull also accepts cleartext HTTP/2 (h2c, prior knowledge), so any stock gRPC client in plaintext mode — grpcurl -plaintext, ghz --insecure, a grpcio insecure_channel — can call /echo.Echo/Echo on localhost:50051 immediately. (For a production-like setup, pass certfile=/keyfile= and the same code serves TLS + ALPN.) The / route in the same file is not decoration: REST, WebSocket, and gRPC genuinely share one port. BlackBull dispatches on the content-type, so there is no separate gRPC server process to run or proxy to.

All four RPC shapes, detected from the signature

gRPC defines four call shapes, and BlackBull supports all of them. You never declare which one a handler is — the registry infers it:

Unary: async def handler(request: bytes, context) -> bytes — one message in, one out.
Server-streaming: write the handler as an async generator and yield each response message.
Client-streaming: take a request_iter parameter instead of request — an async iterator of incoming messages — and return one response.
Bidirectional: request_iter in, async generator out.

Error handling goes through the context: context.abort(GrpcStatus.NOT_FOUND, 'no such thing') ends the call with a proper status in the trailers, and context.metadata(name) reads call metadata (request headers). An unexpected exception in a handler is isolated and reported as INTERNAL — a handler bug never takes down the connection or its sibling streams.

Bring your own protobuf

Notice what the example above doesn't import: protobuf. BlackBull's gRPC handlers exchange raw bytes. The framework handles the HTTP/2 and gRPC framing; message serialisation is entirely yours. Use grpc_tools.protoc-generated classes, the protobuf package directly, or hand-roll the encoding — the handler contract is the same:

@grpc.method('/helloworld.Greeter/SayHello')
async def say_hello(request: bytes, context) -> bytes:
    req = helloworld_pb2.HelloRequest.FromString(request)
    reply = helloworld_pb2.HelloReply(message=f'Hello, {req.name}!')
    return reply.SerializeToString()

This is a deliberate layering decision, not a missing feature. gRPC-the-protocol and protobuf-the-format are separable, and keeping them separate means the core has no codegen step and no protobuf dependency.

When you do want the batteries, pip install 'blackbull[protobuf]' adds a separate integration layer: servicer classes (register a whole service from generated stubs), server reflection (grpc.reflection.v1alpha — so grpcurl and Postman can discover and call your service with no local .proto file), health checking (grpc.health.v1, the protocol Kubernetes probes and load balancers expect), and rich error details delivered in grpc-status-details-bin trailers.

The repo's examples/grpc_greeter.py sits nicely in the middle: it implements the canonical helloworld.Greeter service with real protobuf on the wire, but hand-rolls the (trivial) encoding of its two single-field messages in ~20 lines — so it needs no protoc step, yet a stock grpcurl or grpcio client using the standard helloworld.proto talks to it unmodified.

The parts you'd only notice if they were missing

A few implementation details are worth calling out, because they're the difference between "speaks the protocol" and "usable":

Write-coalescing for server-streaming. A naive implementation sends one DATA frame per yielded message, paying a full trip through the event loop's sender each time. BlackBull batches consecutive small messages into a single DATA frame — valid on the wire, since gRPC clients frame on the 5-byte length prefix, not on DATA frame boundaries. For streams of thousands of small messages this removes almost all of the per-message overhead.
Message size cap. Incoming messages are capped at 4 MiB by default — the same default as grpcio — so a misbehaving client can't buffer you into the ground.
Deadline enforcement. The grpc-timeout request header is honoured; an expired call is terminated with DEADLINE_EXCEEDED, including mid-stream.
Compression. gzip message compression is supported, with a minimum-size threshold so that compressing tiny messages doesn't make them larger (gzip has fixed overhead that swamps small payloads).

And it's not just self-certified: the CI pipeline includes a grpc-interop job that runs real grpcio clients against BlackBull over h2c sockets — success paths, every error status, streaming, and concurrent multiplexed calls. Interop with the reference implementation is tested on every push, not assumed.

Who is this for?

Honest positioning time. BlackBull + gRPC is a good fit if you are:

Avoiding the native stack. grpcio ships a large C++ core. If you're on an unusual platform or ARM board where wheels are scarce, or you just don't want a compiled dependency in the way, a pure-Python server that stock gRPC clients can talk to is genuinely useful.
Building IoT or edge gateways. One Python process serving HTTP for a dashboard, gRPC for device RPCs, and MQTT 5.0 for telemetry — on constrained hardware, collapsing three servers into one process is the whole value proposition.
Building protocol-level test tooling. Because the fault-injection hooks reach the protocol layer, you can stand up a gRPC server in CI that misbehaves on command — truncated messages, stalled streams, hostile frames — and verify your client's error handling actually works. That's very hard to do with a production-grade server that's engineered never to misbehave.
Learning how gRPC actually works. You can put a breakpoint in the HPACK decoder and step through an entire gRPC call — header decompression, length-prefixed message framing, trailer delivery — in pdb. No other stack I know of lets you do that in pure Python end to end.

And it is not for you if you need the full gRPC ecosystem today: client-side load balancing, xDS, gRPC-Web proxying. BlackBull is a server-side framework that speaks the gRPC wire protocol well; it is not a gRPC platform, and it isn't trying to be one.

Try it (60 seconds, no certificates)

The library comes from PyPI; the runnable examples live in the repo:

pip install 'blackbull[grpc]'       # core gRPC (raw bytes)
git clone https://github.com/TOKUJI/BlackBull && cd BlackBull

python examples/grpc_greeter.py --port 50051   # the canonical helloworld.Greeter

No cert step — this serves gRPC over cleartext HTTP/2 on localhost:50051. To call it with grpcurl, save the canonical proto as helloworld.proto so it knows how to encode the request (the core install deliberately has no reflection — that ships in the [protobuf] extra):

syntax = "proto3";
package helloworld;
service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
  rpc SayManyHellos (HelloRequest) returns (stream HelloReply);
}
message HelloRequest { string name = 1; }
message HelloReply   { string message = 1; }

grpcurl -plaintext -proto helloworld.proto \
  -d '{"name": "BlackBull"}' localhost:50051 helloworld.Greeter/SayHello

{ "message": "Hello, BlackBull!" }

That is a stock gRPC client talking to a pure-Python server, end to end. Call SayManyHellos instead to watch server-streaming deliver three messages; curl http://localhost:50051/ hits the REST route on the same port. The raw-bytes echo server from earlier in this post is examples/grpc_server.py, and pip install 'blackbull[protobuf]' adds the servicer/reflection/health layer.

For a TLS setup (what you'd deploy), generate a dev cert and add --cert/--key:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj '/CN=localhost'
python examples/grpc_greeter.py --port 8443 --cert cert.pem --key key.pem
grpcurl -insecure -proto helloworld.proto \
  -d '{"name": "BlackBull"}' localhost:8443 helloworld.Greeter/SayHello

Source, examples, and docs are at github.com/TOKUJI/BlackBull — and if the idea of one debuggable Python process speaking five protocols appeals to you, the earlier series digs into how the HTTP/2 and multi-protocol layers underneath all this actually work.

BlackBull v0.53.3, 2026-07-14.

BlackBull goes multi-protocol (part 3) — one `app.py`, two protocols

TOKUJI — Wed, 01 Jul 2026 17:22:36 +0000

The first two posts were the engineering: part 1 rebuilt the connection
dispatcher so BlackBull's core stopped assuming HTTP, and part 2 put a lock-free,
single-owner MQTT 5 broker on top of that seam. This post is the payoff — what
all of it looks like from an application author's chair.

The short version: one file, one pip install, two protocols.

One decorator for HTTP, one for MQTT

from blackbull import BlackBull
from blackbull.mqtt import MQTTExtension, Message

app = BlackBull()
mqtt = app.add_extension(MQTTExtension(port=1883))

@app.route(path='/')
async def index():
    return "HTTP here; MQTT broker on :1883."

@mqtt.on_message(topic='sensors/{room}/temperature')
async def on_temperature(msg: Message, room: str):
    print(f"{room}: {msg.payload.decode()}")    # {room} captured like a path param

app.run(port=8000)    # HTTP on 8000, MQTT on 1883

mqtt.on_message deliberately mirrors app.route: both decorate an async
function, both match on an address pattern, and {room} captures a topic level
the same way {task_id} captures a URL path segment. The difference is
semantics — an HTTP route is the response; an MQTT tap observes the
broker's routing, which delivers to subscribers whether or not any handler is
registered.

MQTTExtension registers itself through the single extension seam
(app.add_extension) and binds :1883. The core BlackBull class carries zero
MQTT-specific code — the broker lives entirely in blackbull.mqtt.

Drive it with the tools you already have

It's a real MQTT 5 broker — CONNECT / SUBSCRIBE / PUBLISH at QoS 0–2, retained
messages, and Last-Will — so standard clients just work:

mosquitto_sub -t 'sensors/#' -p 1883 -V 5            # terminal 1
mosquitto_pub -t 'sensors/room1/temperature' \
    -m '21.5' -p 1883 -V 5                            # terminal 2

The message appears in the subscriber's terminal and fires the on_temperature
handler above. One process. No apt install mosquitto, no broker sidecar, no C
extension.

When HTTP and MQTT share a process

The real reason to put two protocols in one process isn't cleaner ops — it's
shared memory without a sidecar. Here's a tiny temperature dashboard that
would normally need a broker, a web server, and a Redis instance to bridge
them:

from blackbull import BlackBull
from blackbull.mqtt import MQTTExtension, Message

app = BlackBull()
mqtt = app.add_extension(MQTTExtension(port=1883))

# Plain dict — no locks, no Redis, no cross-process serialization.
latest: dict[str, float] = {}

@mqtt.on_message(topic='sensors/{room}/temperature')
async def ingest(msg: Message, room: str):
    latest[room] = float(msg.payload)

@app.route(path='/sensors')
async def dashboard():
    return latest   # {"room1": 21.5, "room2": 30.1}

app.run(port=8000)

A sensor publishes 21.5 to sensors/room1/temperature via MQTT. The broker
routes it to subscribers and fires ingest, which updates the dictionary. A
browser hits /sensors and sees the current state as JSON. One variable, two
protocols, zero glue infrastructure.

This is what "multi-protocol" buys you in practice: the broker and the web
server live in the same memory space, so the bridge between them is just a
function call that writes to a dict. No redis-py, no pika, no
serialization — just Python.

Machine-readable docs for both protocols

BlackBull already auto-generates an OpenAPI 3.1 document from your route
signatures:

app.enable_openapi()        # publishes /openapi.json and /docs

OpenAPI is an HTTP request/response vocabulary, though — it has nothing to say
about topics and publish/subscribe. The messaging world's counterpart is
AsyncAPI, and BlackBull ships the counterpart:

from blackbull.mqtt import AsyncAPIExtension

app.add_extension(AsyncAPIExtension(title='Sensor Gateway', version='1.0.0'))

After app.run() the document is served at /asyncapi.json, with a CDN-hosted
HTML viewer at /asyncapi (no new Python dependency). Each on_message topic
filter becomes a channel; each callback a receive operation. It's generated
lazily, so taps registered after the extension are still documented. Your HTTP
surface describes itself with OpenAPI; your MQTT surface describes itself with
AsyncAPI; same idea, right vocabulary for each.

The whole arc

Start to finish, that's the story:

BlackBull decided to be a multi-protocol server.
It prepared the ground — a protocol-agnostic dispatcher (peek-and-replay), built behind a regression oracle so the live HTTP server broke nothing.
It built on that ground — a lock-free, single-owner MQTT 5 broker on the actor model, with HTTP throughput actually a little higher than before.
And it stayed one app.py: HTTP and MQTT side by side, sharing memory, each self-documenting — no sidecars, no C extensions.

What's next

MQTT is the first consumer of the multi-protocol seam, not the last.
@app.raw_handler already lets you bind raw TCP to a port and handle the
reader/writer yourself for custom protocols. A first-class gRPC handler — riding
the existing HTTP/2 stream, flow-control, and trailers machinery — is the
natural next step. Same pattern: register a ProtocolBinding, let the core
detect and dispatch. The core won't have to learn a thing about gRPC. That's
the whole point.

Try it

pip install 'blackbull[mqtt]'
python examples/mqtt_broker.py

Source: github.com/TOKUJI/BlackBull
Docs: tokuji.github.io/BlackBull

BlackBull goes multi-protocol (part 2) — an MQTT 5 broker with no locks and a single owner

TOKUJI — Sun, 28 Jun 2026 11:24:24 +0000

Part 1 rebuilt BlackBull's connection dispatcher so BlackBull's core no longer
assumes every connection is HTTP. With that seam in place, a non-HTTP protocol
can register a binding and be served like any other. This post is the first real
consumer of that seam: a full MQTT 5.0 publish/subscribe broker, running in
the same process as your HTTP routes, on the standard 1883 port.

If you haven't crossed paths with MQTT: it's a lightweight
publish/subscribe protocol that powers most IoT sensor-to-cloud communication.
Clients publish messages to topics (like sensors/room1/temperature), and
a broker routes them to every client that subscribed to a matching pattern.
No polling, no request/response pairing — a sensor just publishes and moves on.
It's simple on the outside; building the broker that routes those messages
correctly under concurrency is where it gets interesting.

A broker is the hard case for concurrency. Subscriptions, sessions, retained
messages, and Last-Will templates are all shared mutable state, touched by every
connection at once. The obvious implementation reaches for locks. BlackBull's
reaches for the actor model — and the result needs to own that state safely in
two dimensions: within a worker process, and across several of them.

---

Dimension one: three guarantees inside a worker

The actor model gives the broker three things that a lock-based design would
have to build by hand: shared state without locks, trivial lifetime
management, and backpressure isolation. All three fall out of the same
rule — one actor owns the state, no one else touches it.

No locks on shared state

Inside a single process the broker is three kinds of actor, each in its own
module:

Actor	Count	Owns	Inbox carries
`BrokerActor`	1 per process	all routing / session / retained state	client control events
`MQTT5Actor`	1 per connection	one socket's write side	outbound packets
`TapActor`	1 per process	nothing (stateless dispatch)	published messages for `on\_message` taps

The load-bearing property: BrokerActor processes its inbox serially. Two
PUBLISH packets from two different connections are handled one after another, never
concurrently. So the routing table and the session dictionaries are plain Python
objects — no locks, no asyncio.Lock, no shared mutable state reached from two
tasks at once. That is the core reason to use the actor model here: serial
inbox processing turns "shared mutable state" into "state owned by exactly one
actor," and the need for locks evaporates.

**Actor model vs locks — when does each win?**

Scenario Actor (serial inbox) Lock (asyncio.Lock)

Many writers, one shared state **Wins.** Messages queue; throughput stays flat regardless of writer count. Contention grows with writers; throughput degrades.

Few writers, mostly reads Message dispatch overhead per access — paid even when uncontested. **Wins.** Fast acquire/release; reads often lock-free with asyncio patterns.

Parallelism within the state owner Can't. One actor = one task = one core. **Wins.** Fine-grained locking lets multiple cores work on different parts.

Debugging Harder. Bugs span actor boundaries; stack traces don't cross send() calls. **Wins.** PYTHONASYNCIODEBUG=1 surfaces slow locks; deadlock detection built in.

Deadlock risk Low, but not zero. Circular send() between two actors each awaiting the other's reply can deadlock. **Real risk.** Two locks acquired in different order → classic deadlock.

Error isolation **Wins.** A crashed actor doesn't corrupt its peers' state. One task holding a lock that crashes can poison the lock (needs try/finally discipline).

A broker hits the first row on every connection: many writers converging on one
routing table. That's why the actor model fits here — not because it's always
better, but because the access pattern aligns with what actors are good at.
For a different workload (say, a connection pool with mostly reads), a lock
may well be the simpler, faster choice.

Scenario	Actor (serial inbox)	Lock (`asyncio.Lock`)
Many writers, one shared state	Wins. Messages queue; throughput stays flat regardless of writer count.	Contention grows with writers; throughput degrades.
Few writers, mostly reads	Message dispatch overhead per access — paid even when uncontested.	Wins. Fast acquire/release; reads often lock-free with `asyncio` patterns.
Parallelism within the state owner	Can't. One actor = one task = one core.	Wins. Fine-grained locking lets multiple cores work on different parts.
Debugging	Harder. Bugs span actor boundaries; stack traces don't cross `send()` calls.	Wins. `PYTHONASYNCIODEBUG=1` surfaces slow locks; deadlock detection built in.
Deadlock risk	Low, but not zero. Circular `send()` between two actors each awaiting the other's reply can deadlock.	Real risk. Two locks acquired in different order → classic deadlock.
Error isolation	Wins. A crashed actor doesn't corrupt its peers' state.	One task holding a lock that crashes can poison the lock (needs `try/finally` discipline).

MQTT5Actor is the sole writer to its socket. Its run() loop drains an
inbox of outbound packets; a sibling reader task decodes the wire and sends
control messages to the BrokerActor. Even replies the connection could answer by
itself — PINGRESP, AUTH — are routed back through its own inbox, so run()
stays the only thing that ever touches the socket's write side. No cross-task
write races, by construction.

Why Last-Will delivery is free with actors

MQTT's Last-Will-and-Testament is a message the broker delivers on behalf of a
client that disconnects uncleanly — "if I disappear, tell everyone X." The
hitch: by the time the broker notices the disconnect, the client's connection
actor is already tearing itself down. Who owns the Will at that moment?

Because BrokerActor outlives every connection, the answer is straightforward:
the dying MQTT5Actor hands the Will template to BrokerActor during
teardown, and BrokerActor routes it to live subscribers. No global registry
kept alive just for cleanup, no cross-actor lifetime coupling — the long-lived
broker makes Will delivery a trivial handoff between two actors that already
exist.

Slow observers can't stall the broker

@mqtt.on\_message handlers — application taps that observe broker traffic —
run on a separate plane via TapActor, which consumes a bounded inbox. The
connection offers each published message without blocking and returns
immediately. If taps fall behind, the newest message is dropped and a running
dropped-count is logged (silent loss is the one unacceptable outcome, so the
count is always surfaced). A slow tap back-pressures nothing.

Here is a controlled side-by-side — one build, one machine, one session, with the
dispatch mode (inline vs actor) as the only variable, tap queue depth 256:

tap delay	inline throughput	actor throughput	inline p99	actor p99
0	61,063/s	52,529/s	5.64 ms	6.59 ms
1 ms	881/s	52,835/s	448.66 ms	6.31 ms
5 ms	193/s	59,817/s	2,047.97 ms	5.81 ms
25 ms	39/s	59,500/s	10,135.94 ms	5.82 ms

Inline delivery collapses as 1/delay with p99 climbing past ten seconds; actor
delivery stays flat — ~52–60k msg/s independent of tap speed. The trade is
explicit: stable delivery bought with bounded tap coverage (and a logged drop
count under overload).

A historical note worth its own line: MQTT is the first production code in
BlackBull that uses the actor inbox for real. The HTTP actors override run()
and call each other through direct method calls — the inbox was defined but
latent on that path. The broker is what proves the inbox works at scale (451
conformance tests, all green).

---

Dimension two: a single owner across workers

Serial inboxes solve concurrency inside one process. But BlackBull runs HTTP
across multiple worker processes for throughput — and that collides head-on with
a broker.

The MQTT 5 spec assumes one logical broker: a client's session, its queued
messages, and its subscriptions are one coherent piece of state. Shard the
broker across four worker processes with no shared store and a client that
reconnects to a different worker finds its session gone. So the broker must
have a single owner.

The naive resolution is "any stateful protocol forces workers=1 for the whole
process" — which throws away HTTP's multi-worker scaling to satisfy MQTT. v0.44.1
does something better:

The master process binds the broker's :1883 socket once and hands it to worker 0 only. The broker lives there, single-owner, exactly as the spec wants.
HTTP is stateless, so it scales on every worker. app.run(port=8000, workers=4) alongside MQTTExtension(port=1883) now runs HTTP on all four workers while MQTT runs on worker 0.
If worker 0 crashes, the master respawns it and it re-inherits the still-open listener — the broker's single-owner identity is tied to "worker 0," not to a particular PID.
BB\_SOCKET\_REUSEPORT=1 gives each HTTP worker its own kernel accept queue for the best load distribution; the broker port is always bound without SO\_REUSEPORT, by design — a single owner must not have its socket load-balanced away.

(Auto-reload (--reload) still pins workers=1 — the exec-based socket handoff
doesn't yet carry protocol listeners. A known edge, documented.)

So the two dimensions compose: within a worker, the actor model guarantees
lock-free state, trivial lifetimes, and backpressure isolation; across
workers, single-owner affinity means the broker stays coherent while HTTP
scales past it.

---

What it cost the HTTP path

Nothing. Adding the broker is a self-contained extension on the part-1 seam — the
core BlackBull class carries zero MQTT-specific code. The same release that
shipped the broker measured zero regression on the HTTP/1.1 hot path. A second
protocol arrived and the first one didn't notice.

A closing thought. BlackBull already has a second extension on PyPI —
blackbull-htcpcp, an
implementation of HTCPCP (RFC 2324), the HTTP extension for controlling
coffee pots. Now imagine an MQTT-enabled coffee machine: the HTCPCP extension
could serve BREW /pot on :80 while the broker receives brew-complete
notifications on :1883, sharing the pot's state in one Python dict. Two
RFCs, one process, no sidecar. The MQTT broker is just the first proof that
the part-1 seam delivers on that promise.

Next, part 3: what all this looks like from an application author's chair — one
app.py, two protocols, and machine-readable docs for both.

---

Source: github.com/TOKUJI/BlackBull
Docs: tokuji.github.io/BlackBull

BlackBull goes multi-protocol (part 1) — first it had to forget it was HTTP

TOKUJI — Fri, 26 Jun 2026 11:03:38 +0000

What does it take to teach an HTTP server to speak a protocol that isn't HTTP at
all? Not "add a WebSocket upgrade" — that still starts with an HTTP handshake.
I mean a protocol that arrives on its own port, speaks its own wire format, and
has never heard of a request-line.

That's the problem I walked into with BlackBull, a pure-Python ASGI framework
with its own HTTP/1.1, HTTP/2, and WebSocket stack. I'd recently gotten it to a
stable, spec-passing HTTP server — and hit a wall. A clean HTTP server, however
well-built, is a solved problem; there are dozens. What I actually wanted to
know was whether BlackBull's foundation could carry something HTTP couldn't
reach: a second, unrelated protocol sharing the same process. And HTTP alone
couldn't tell me — every connection was being handled by machinery that quietly
assumed HTTP from the first byte.

So I decided to add an MQTT 5 broker (part 2 of this series) — a protocol with
no request-line, no status codes, no HTTP at all. The first thing I discovered:
the core didn't know how to welcome a second protocol. It assumed every
connection was HTTP — not as a bug, but as an identity. Before BlackBull could
host anything else, it had to forget it was an HTTP server.

And it had to do that surgery under a working HTTP server, without breaking a
single feature. That constraint — change the foundation, break nothing — is
the whole story. Whether the foundation actually held is the question the rest of
this post answers.

Where HTTP was hiding in the dispatcher

Every incoming TCP connection is owned by a ConnectionActor. Its job is to
figure out what protocol the peer is speaking and hand the socket to the right
handler. The trouble: "figure out what protocol" had HTTP baked into it in three
places.

The ALPN path read exactly 24 bytes — the length of the HTTP/2 connection preface (PRI * HTTP/2.0\r\n\r\n…, RFC 9113 §3.4).
The cleartext path read until \r\n — the HTTP/1.1 request-line delimiter.
The slowloris timeout wrote back HTTP/1.1 408 Request Timeout — an HTTP string, on a connection we hadn't yet proven was HTTP.

For an HTTP-only server this is fine; the assumptions are always true. But a
protocol whose detection needs a different number of bytes, or a different
delimiter, or that should never receive an HTTP 408, cannot participate at
all. The dispatcher wasn't a dispatcher — it was an HTTP parser wearing a
dispatcher's coat.

Peek, then replay

The fix is a detection primitive that reads from the socket without consuming
what it read: PrefixReader. It peeks at the opening bytes, lets each registered
protocol look at them, and then — crucially — replays those same bytes to
whichever protocol claims the connection, so the handler sees the stream from
byte zero as if nothing had been read.

class ProtocolBinding:
    # How many bytes detection needs before it can decide.
    detection_read: int = -1     # -1 = until \r\n, 0 = none, N = exactly N

    def detect(self, prefix: bytes, alpn: str | None) -> bool: ...
    async def serve(self, conn: ConnectionView) -> None: ...

ConnectionActor no longer knows what 24 means, or why \r\n matters. It groups
the registered bindings by their declared detection_read, peeks exactly what
the group needs, offers the prefix to each binding's detect(), and calls
serve() on the winner. HTTP/1.1, HTTP/2, and WebSocket became three ordinary
bindings. The HTTP knowledge moved out of the dispatcher and into the HTTP
bindings, where it belongs.

One honest caveat about that API: detection_read only expresses two shapes —
read N fixed bytes or read until \r\n. The \r\n sentinel is a pragmatic
default, not a universal delimiter; a protocol that frames on something else (a
C-style \0, say) can't yet describe its own detection need. The seam is in the
right place — a binding declares what detection requires — but the vocabulary
isn't fully protocol-neutral. Generalizing detection_read to a per-binding
predicate is the natural next step, and a known one.

Two structural things fell out of this.

Why a whole class could be deleted

RawProtocolActor is gone — and why it could go is the real point. To feel the
deletion you have to know what it did. In the old design ConnectionActor was
HTTP-shaped: it spoke in request-lines and response writers, and it could only
hand a connection to something that fit that shape. A non-HTTP handler didn't. So
there was an adapter — an extra actor layer everyone called "L2" — whose entire
job was to wrap a raw byte handler in enough HTTP-actor costume that the
dispatcher would deign to talk to it. It was pure translation, a class that
existed only because the dispatcher couldn't address anything that wasn't HTTP.

Once serve(conn) became the single door every protocol walks through, that
translation had no one left to translate for — there was only one shape now. L2
wasn't refactored; it was obviated. The clearest sign a seam is in the right
place is when a whole layer that existed to bridge two shapes wakes up to find
there's only one.

A lifecycle event that finally fires everywhere

connection_closed now fires for HTTP too. Because teardown used to live on the
HTTP-specific path, the lifecycle event never fired for HTTP connections — only
for the raw ones. Unifying the path fixed that asymmetry as a side effect.

The headline payoff is forward-looking: a new protocol now registers a binding
and changes zero lines of ConnectionActor. gRPC, Redis RESP, a raw TCP echo —
each is a ProtocolBinding, not a dispatcher edit.

The part that actually mattered: breaking nothing

Rewriting the code that decides what every connection is — under an HTTP server
that already passes h2spec and Autobahn — is the kind of change that quietly
introduces a regression you discover in production six weeks later. So the
refactor was gated on two things, both built before the dispatcher was
touched:

A regression oracle. A golden-path test suite (test_connection_dispatch_golden.py) pins the exact detection outcome for every protocol/ALPN/prefix combination — HTTP/1.1 cleartext, HTTP/2 prior knowledge, ALPN h2, WebSocket upgrade, the slowloris timeout. The refactor had to keep every one of those outcomes byte-identical. The oracle ran red first (proving it tests something), then stayed green through the change.
A performance gate. The detection path is on every connection, so a careless rewrite taxes every request. The change was held to a ±2% budget against the pre-refactor HTTP/1.1 throughput baseline, measured on the HttpArena suite.

The result cleared both bars. HttpArena's validation run came back unchanged —
47 passed / 0 failed, the full suite, plus 7/7 WebSocket — and HTTP/1.1
throughput held within the ±2% budget against baseline. No regression. The
foundation was rebuilt under the house and not one wall cracked.

Why tell this story before the MQTT one?

Because the MQTT broker (part 2) is the easy part. It's a self-contained
extension. The hard, valuable engineering was making BlackBull's core able to
receive a second protocol without the core learning anything HTTP-specific
about it — and proving the existing HTTP behavior survived the operation
unchanged.

Next: the broker itself — a publish/subscribe engine with no locks and a
single owner, built entirely on top of this seam.

Source: github.com/TOKUJI/BlackBull
Docs: tokuji.github.io/BlackBull

How a from-scratch HTTP/2 server actually works (part 2) — flow control, DATA, and security

TOKUJI — Sun, 21 Jun 2026 13:04:32 +0000

Recap from part 1: We traced a connection from the 24-byte preface through SETTINGS exchange, the 9-byte frame header, the seven-loop guard tower, and stream birth — how a HEADERS frame passes admission control and creates a new stream. The stream is now OPEN. This part follows what happens next: body delivery, stream death, connection shutdown, and the security guards every from-scratch implementer needs.

1. Body delivery — DATA, flow control, content-length (§6.1, §6.9.1)

Once the stream is OPEN, the peer sends DATA frames. Each DATA frame consumes flow-control credit — and HTTP/2 has two independent windows.

Why two windows?

The stream window stops any one stream from hogging the connection — fairness between streams. The connection window caps the total data in flight across all streams — a bound on how much the receiver has to buffer. Both must have positive credit before a DATA frame may be sent.

The connection window is the easy half to forget, and forgetting it fails late: credit only the stream window and everything works until ~65,535 cumulative bytes have flowed across all streams, at which point the shared connection window reaches zero and every stream stalls — even ones with plenty of their own credit.

After delivering a DATA frame to the application, HTTP2Actor._on_data_frame() sends two WINDOW_UPDATEs:

# HTTP2Actor._on_data_frame() — after delivering DATA to the application
await self.send_frame(factory.window_update(stream.stream_id, frame.length))  # stream
await self.send_frame(factory.window_update(0, frame.length))                  # connection

Back-pressure

The WINDOW_UPDATE is sent only after put_DATAFrame returns True — the recipient's queue accepted the frame. A full application queue withholds the credit, naturally stalling the peer. This is the RFC's intended back-pressure mechanism: flow control doubles as a signalling channel between the TCP receive buffer and the application handler.

Content-length enforcement (§8.1.2.6)

stream.received_data_bytes accumulates across DATA frames (padding excluded). If the declared content-length is exceeded on any frame → RST_STREAM PROTOCOL_ERROR immediately. If END_STREAM arrives and the total is short → same error. §8.1.1 makes the server, not the application, responsible for this check — a malformed request must never reach handler code.

HALF_CLOSED_REMOTE

When a DATA frame carries END_STREAM, the stream transitions from OPEN to HALF_CLOSED_REMOTE. The peer has finished sending. DATA on a stream already in HALF_CLOSED_REMOTE or CLOSED → RST_STREAM STREAM_CLOSED.

2. Stream death — cleanup and late frames (§5.1)

A stream reaches CLOSED when either the response END_STREAM is sent or an RST_STREAM is received. At that point HTTP2Actor._make_done_cb() — the task done-callback — fires:

# HTTP2Actor._make_done_cb()
self._closed_streams[stream_id] = False  # closed via END_STREAM (closed_via_rst=False)

The Stream node is pruned from the priority tree, but the stream ID lives on in _closed_streams: dict[int, bool]. This is important: keeping a full Stream object per completed request would cost hundreds of bytes each; a dict entry costs ~72 bytes. The boolean tracks how the stream closed — False means clean END_STREAM, True means RST_STREAM — which affects which error code a late frame triggers.

Late frames on a closed stream still hit the CLOSED branch of §5.1 validation using just an integer lookup. PRIORITY is always allowed through; HEADERS and CONTINUATION on a closed stream are a connection STREAM_CLOSED error; everything else gets a stream-level RST_STREAM.

3. Connection death — GOAWAY (§6.8)

GOAWAY is asymmetric.

Incoming (HTTP2Actor._on_goaway_frame()): the peer is closing the connection. We echo a GOAWAY back so the peer knows which stream IDs we processed, then inject http.disconnect into every active recipient and return from _frame_loop:

async def _on_goaway_frame(self, last_stream_id: int) -> None:
    await self.send_frame(self.factory.goaway(last_stream_id))
    _signal_recipients(self._recipients)

Outgoing (HTTP2Actor._connection_error()): we detected a protocol error and must close. Build a GOAWAY with _last_peer_stream_id (the highest stream we've ever seen from the peer), flush it, then call writer.close() so the peer sees FIN after the GOAWAY. The _goaway_sent flag makes this idempotent — a second connection error doesn't send a second GOAWAY.

Sidebar: WebSocket over HTTP/2 (RFC 8441) — the actor reuse trick

RFC 8441 bootstraps WebSocket over HTTP/2 via an extended CONNECT request with :protocol=websocket. There's no 101 Switching Protocols — the response is a 200 HEADERS frame and data flows as DATA frames on the same stream.

BlackBull reuses WebSocketActor without modification. WebSocketActor._send() reads a callback from scope['_ws_send_101']. For HTTP/2 WebSocket, that callback is replaced with _ws_send_200, which sends a 200 HEADERS frame instead of 101. The actor never knows it's running over HTTP/2.

HTTP2WSReader and HTTP2WSWriter bridge the HTTP/2 frame-level I/O to the WebSocket actor's readexactly / write interface, and they implement backpressures_via_credit = True — flow control credit is withheld until the reader buffer drains, using HTTP/2's own flow-control mechanism as the back-pressure signal.

Sidebar: Three security guards

Rapid Reset (CVE-2023-44487, RFC 9113 §10.5). Disclosed in October 2023, this attack sends HEADERS + RST_STREAM in a tight loop — the server spawns a task for each stream, but the stream is already reset by the time the handler starts. SETTINGS_MAX_CONCURRENT_STREAMS doesn't help because the streams close too fast to accumulate. BlackBull uses a rolling 1-second RST_STREAM rate limit (default 20/sec) in _frame_loop(), checked before stream-state validation so RSTs on idle/unknown streams also count. Exceeded → GOAWAY ENHANCE_YOUR_CALM.

CONTINUATION flood (CVE-2024-27983, RFC 9113 §10.5.1). A HEADERS frame with END_HEADERS=0 followed by unlimited CONTINUATION frames can grow the header accumulator until the process OOMs. BlackBull checks len(header_frame.raw_block) > self._header_max_total (default 64 KiB — the same budget as HTTP/1.1) and resets with ENHANCE_YOUR_CALM before calling parse_payload(). nginx and Envoy use the same approach and the same error code.

stream_id==0 for stream-only frames (RFC 9113 §6.1, §6.2, §6.4, §6.6, §6.10). Less flashy but load-bearing: DATA, HEADERS, RST_STREAM, PUSH_PROMISE, PRIORITY, and CONTINUATION MUST NOT appear on stream 0. _STREAM_ONLY_FRAME_TYPES is a class-level frozenset that consolidates six independent checks into one lookup. Violation → connection PROTOCOL_ERROR. BlackBull fixed the PUSH_PROMISE and RST_STREAM cases (previously missing from the individual checks) in v0.42.1 and v0.42.2 respectively.

Where to go from here

The full RFC→code table, with section numbers, method names, and file:line references, lives at
docs/about/rfc9113-implementation.md in the BlackBull docs.

Part 1 covered the connection preface, frame reading, the seven-loop guard tower, and stream birth — read it if you want the full lifecycle from the beginning.

The source is blackbull/server/http2_actor.py — 1200+ lines, nearly every block annotated with its RFC cite. gRPC over HTTP/2 is the natural next step: the frame layer already handles multiplexed streams; what's missing is the Protobuf framing and trailers.

BlackBull is a personal learning project — pure-Python HTTP/1.1, HTTP/2, and WebSocket, no C extensions in the protocol stack. Issues and PRs welcome.

How a from-scratch HTTP/2 server actually works (part 1) — connection to first request

TOKUJI — Sun, 21 Jun 2026 13:02:39 +0000

RFC 9113 is 80 pages. What does it take to turn those 80 pages into working code?

BlackBull is a pure-Python ASGI web framework whose HTTP/2 stack is built directly on TCP — no h2 library, no C extensions in the protocol layer. Because the frame layer and the server integration live in the same source files, you can trace a single RFC requirement end-to-end: from the 9-byte header parse through stream state validation to the application queue that withholds flow-control credit for back-pressure. Nearly every block carries the RFC section number it implements, so you can grep for §6.9.1 and land on the dual-window logic, then follow the call chain in both directions.

A note on h2: The most widely used Python package for HTTP/2 is the
h2 library — a sans-I/O
state machine where you call receive_data(bytes) and react to a list of
events (RequestReceived, DataReceived, WindowUpdated…). h2 is a
frame parser. It does not tell you how to wire those events into an event
loop, manage stream state across concurrent tasks, propagate back-pressure to
handlers, or shut down a connection cleanly — those concerns live in a
separate codebase (Daphne, Hypercorn, etc.).

1. The connection preface — how HTTP/2 begins (§3.4, §6.5)

Before any frames flow, the client must prove it speaks HTTP/2. RFC 9113 §3.4 specifies a 24-byte magic string:

PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n

BlackBull handles this in ConnectionActor — the per-TCP-connection supervisor that detects the protocol and spawns the appropriate handler. The preface string is the same regardless of TLS; what differs is how the server knows to expect it. When TLS negotiates ALPN h2, the protocol is already decided — ConnectionActor._dispatch() reads exactly 24 bytes and validates them:

# ConnectionActor._dispatch() — ALPN-h2 path
preface = await self._reader.readexactly(24)
expected = _HTTP2_PREFACE_FIRST_LINE + _HTTP2_PREFACE_REMAINDER
if preface != expected:
    # Send a raw GOAWAY before closing so a legitimate HTTP/2 peer
    # gets a clean diagnosis rather than a mysterious TCP RST.
    ...
    raise ValueError(f'Invalid HTTP/2 preface: {preface!r}')

On a cleartext connection there is no ALPN, so the same dispatch method sniffs the first line: if it matches PRI * HTTP/2.0\r\n, the remaining 8 bytes are read and the same validation runs. If it doesn't match, the connection falls through to HTTP/1.1.

Once the preface is validated, HTTP2Actor takes over. Its run() method immediately sends the server's SETTINGS frame (§6.5):

# HTTP2Actor.run() — sends SETTINGS as the very first frame
await self.send_frame(self.factory.settings(
    enable_connect_protocol=cfg.h2_enable_websocket,
    initial_window_size=cfg.h2_initial_window_size,
    max_concurrent_streams=self.max_concurrent_streams,
))

SETTINGS is how both endpoints agree on parameters: initial flow-control window, maximum frame size, header table size, and whether server push or WebSocket-over-H2 is enabled. Incoming SETTINGS (with and without ACK) are handled by SettingsResponder.respond(), which validates every parameter against RFC 9113 §6.5.2 ranges — SETTINGS_INITIAL_WINDOW_SIZE must not exceed 2³¹−1, SETTINGS_MAX_FRAME_SIZE must be between 16384 and 16777215, and so on.

After SETTINGS, the connection optionally expands its inbound flow-control window beyond the RFC default of 65535 bytes, then enters _frame_loop.

2. Reading a frame — the 9-byte header (§4.1)

Every HTTP/2 frame starts with a 9-byte header:

+-----------------------------------------------+
|                 Length (24)                   |
+---------------+---------------+---------------+
|   Type (8)    |   Flags (8)   |
+-+-------------+---------------+-------------------------------+
|R|                 Stream Identifier (31)                      |
+=+=============================================================+

HTTP2Actor.receive() reads exactly 9 bytes, extracts the frame length, then reads exactly that many more:

# HTTP2Actor.receive()
data = await self._reader.readexactly(9)
frame = self._parser.parse(data)
size = frame.length
if size > 0:
    payload = await self._reader.readexactly(size)
    frame = self._parser.parse_payload(frame, payload)
return frame

Nine lines. The complexity lives in what happens next.

3. The frame loop guard tower — seven checks before dispatch (§4.2, §5.5, §6.3, §6.4, §6.10)

_frame_loop processes one frame at a time. Before dispatching to a specific handler, it runs a sequence of guards — checks that apply regardless of stream state. The ordering matters: each guard catches cases that would otherwise be misclassified by a later check.

Guard 1 — CONTINUATION expectation (§6.10)

If the previous HEADERS or PUSH_PROMISE had END_HEADERS=0, the only legal next frame is CONTINUATION. Any other type → connection PROTOCOL_ERROR. This must be checked first because a stray HEADERS or DATA arriving mid-header-block would otherwise be dispatched to the wrong handler:

# HTTP2Actor._frame_loop() — Guard 1
if waiting_continuation and frame_type != FrameTypes.CONTINUATION:
    await self._connection_error(ErrorCodes.PROTOCOL_ERROR, ...)
    return

Guard 2 — unknown frame types (§5.5)

Frames with unrecognized type codes MUST be silently ignored for forward compatibility:

# HTTP2Actor._frame_loop() — Guard 2
if frame_type is None:
    continue

Guard 3 — Rapid Reset rate limit (CVE-2023-44487)

The Rapid Reset attack sends HEADERS immediately followed by RST_STREAM in a tight loop — the server spawns a task for each stream, but by the time the handler starts the stream is already reset. max_concurrent_streams doesn't catch it because the stream lifecycle is too short.

BlackBull uses a rolling 1-second window. More than 20 RST_STREAMs per second → GOAWAY ENHANCE_YOUR_CALM. This check runs before stream-state validation so that RST_STREAM on idle/unknown streams also counts toward the budget.

Guard 4 — frame size check (§4.2)

A frame whose payload exceeds the receiver's advertised SETTINGS_MAX_FRAME_SIZE is a FRAME_SIZE_ERROR. The severity depends on the frame type: header-block and connection-state frames (HEADERS, CONTINUATION, PUSH_PROMISE, SETTINGS) are connection-fatal — they corrupt shared HPACK state. Everything else is stream-fatal. _FRAME_SIZE_CONNECTION_ERROR_TYPES is a class-level frozenset that encodes this distinction.

Guard 5 — stream_id==0 for stream-only frames (§6.1, §6.2, §6.4, §6.6, §6.10)

DATA, HEADERS, RST_STREAM, PUSH_PROMISE, PRIORITY, and CONTINUATION MUST NOT appear on stream 0 — that's reserved for connection-control frames (SETTINGS, PING, GOAWAY). _STREAM_ONLY_FRAME_TYPES is a class-level frozenset:

# HTTP2Actor._frame_loop() — Guard 5
if frame_type in _STREAM_ONLY_FRAME_TYPES and frame.stream_id == 0:
    await self._connection_error(ErrorCodes.PROTOCOL_ERROR, ...)
    return

Guard 6 — CONTINUATION without preceding HEADERS (§6.10)

A CONTINUATION that arrives outside an open header block (i.e., waiting_continuation is not set) is a connection PROTOCOL_ERROR. This check must precede stream-state validation — otherwise a stray CONTINUATION on a half-closed or closed stream would be rejected with the wrong error type (STREAM_CLOSED instead of PROTOCOL_ERROR).

Guard 7 — PRIORITY frame length (§6.3)

A PRIORITY frame MUST be exactly 5 octets; anything else is a stream FRAME_SIZE_ERROR. This is enforced before stream-state lookup so a malformed PRIORITY on a not-yet-seen stream still gets the correct error.

After all seven guards, the remaining frames enter a match dispatch on frame type.

4. Stream birth — HEADERS, state machine, CONTINUATION (§5.1, §6.2, §6.10)

A stream is an independent, bidirectional flow of frames within an HTTP/2 connection, identified by a 31-bit integer. Multiple streams coexist on a single TCP connection — this is multiplexing, the defining feature of HTTP/2. Every stream follows a strict lifecycle through a set of states defined in RFC 9113 §5.1.

The RFC defines eight stream states; four matter for a server. Here is the complete lifecycle of a single request:

IDLE  →(HEADERS received)→  OPEN
OPEN  →(END_STREAM received on DATA)→  HALF_CLOSED_REMOTE
OPEN or HALF_CLOSED_REMOTE  →(response END_STREAM sent)→  CLOSED
any  →(RST_STREAM)→  CLOSED

This section covers the IDLE→OPEN transition — everything that happens when a HEADERS frame first arrives.

Stream ID rules (§5.1.1)

Before accepting a HEADERS frame, HTTP2Actor._frame_loop() validates the stream identifier. Peer-initiated streams MUST use odd identifiers, strictly increasing — an even id or one ≤ _last_peer_stream_id is a connection PROTOCOL_ERROR. This monotonic-odd rule is what lets both ends allocate stream IDs without a round-trip; a violation means the peer's state has diverged from ours and the connection is no longer trustworthy.

The HEADERS admission gauntlet

HTTP2Actor._on_headers_frame() runs three checks before any application code sees the request:

Concurrency check — if _active_stream_count >= max_concurrent_streams, respond RST_STREAM REFUSED_STREAM immediately. This is a stream-level error, not a connection error: the client did nothing wrong, it just bumped into a ceiling the server set for itself. The client keeps all its other in-flight streams.
END_HEADERS check — if END_HEADERS=0, the header block continues across CONTINUATION frames. The method returns False and the caller sets waiting_continuation = True, stashing the frame for accumulation.
Malformed check (§8.1.1) — after parse_payload() + parse_headers() decode the header block, the malformed flag is checked. Missing pseudo-headers, invalid field characters, connection-specific headers → RST_STREAM PROTOCOL_ERROR before the request ever reaches a handler.

HTTP2Actor._validate_stream_state(stream, frame_type) encodes the legal frame set for each state. A HEADERS frame arriving on a stream that is already OPEN, for instance, is rejected — the RFC forbids a second HEADERS on an active stream.

CONTINUATION — assembling split header blocks

When END_HEADERS=0, HTTP2Actor._on_continuation_frame() accumulates header_frame.raw_block across subsequent CONTINUATION frames. Only when END_HEADERS=1 does it call header_frame.parse_payload() + parse_headers() once on the complete block — the same concurrency check and malformed check then run on the assembled HEADERS.

CONTINUATION flood protection is covered in the security sidebar in part 2.

What's next — part 2 covers the rest of the lifecycle

Part 1 traced the connection from the 24-byte preface through the first request's arrival. Part 2 follows what happens after the stream is OPEN: flow control and DATA delivery, stream death and cleanup, connection shutdown via GOAWAY, and three security guards every from-scratch implementer needs. It also covers WebSocket over HTTP/2 (RFC 8441) — where the same WebSocketActor runs unmodified over HTTP/2 DATA frames.

Want the full RFC→code map? Every section of RFC 9113, every BlackBull method, with file references, lives at docs/about/rfc9113-implementation.md.

The source is blackbull/server/http2_actor.py — 1200+ lines, nearly every block annotated with its RFC cite.

BlackBull is a personal learning project — pure-Python HTTP/1.1, HTTP/2, and WebSocket, no C extensions in the protocol stack. Issues and PRs welcome.

Brewing Coffee Over HTTP: A Python Implementation of RFC 2324 and RFC 7168 (HTCPCP)

TOKUJI — Thu, 18 Jun 2026 13:00:13 +0000

One terminal session. Copy, paste, watch it run.

pip install blackbull-htcpcp

# ---- Coffee mode: start the server ----
python -c "
from blackbull import BlackBull
from blackbull_htcpcp import HtcpcpExtension

app = BlackBull()
HtcpcpExtension(app=app, pot_type='coffee')
app.run(port=8000)
" &

sleep 1  # wait for the server to bind

# ---- Brew coffee with additions ----
curl -w '\n' -X POST -H 'Accept-Additions: cream; sugar; vanilla' http://localhost:8000/pot

# ---- Inspect the pot ----
curl -w '\n' http://localhost:8000/pot

# ---- Ask when it'll be ready ----
curl -w '\n' http://localhost:8000/pot/when

# ---- Teapot mode ----
kill %1 && wait 2>/dev/null
python -c "
from blackbull import BlackBull
from blackbull_htcpcp import HtcpcpExtension
app = BlackBull()
HtcpcpExtension(app=app, pot_type='teapot')
app.run(port=8000)
" &

sleep 1  # wait for the server to bind

# Ask a teapot to brew coffee → 418
curl -w '\n' -X POST http://localhost:8000/pot

# Ask a teapot to brew tea → 200
curl -w '\n' -X POST -H 'Accept-Additions: milk; honey' http://localhost:8000/pot

kill %1 && wait 2>/dev/null

You'll see five JSON responses, each with Content-Type: message/coffeepot:

#	What you did	Status	Key detail
1	POST with `cream; sugar; vanilla`	200	Additions echoed back in the response
2	GET the pot state	200	`"state":"ready"`
3	GET when it's ready	200	`"ready":true`
4	Teapot + no additions	418	`"I'm a teapot"` — RFC 7168 §2.1
5	Teapot + `milk; honey`	200	Tea brewing succeeds — RFC 7168

Native method support: BREW, PROPFIND, and WHEN are registered as first-class HTTP methods when the underlying BlackBull framework is ≥ 0.42.1. Before BlackBull 0.42.1, POST served as the fallback for BREW and GET covered PROPFIND / WHEN — both paths produce identical wire behaviour.

blackbull-htcpcp is the first PyPI package to implement both RFC 2324 (the core HTCPCP spec) and RFC 7168 (its tea-pot extension). 53 tests. A documented threat model. And every feature is wired through the framework's public extension API — zero core modifications.

The real goal: stress-test an extension surface

HTCPCP is a joke, but it is a joke with excellent test coverage of HTTP's extension points. A protocol that exercises all five of these in 350 lines is a useful validation tool:

Extension point	HTCPCP usage
Custom HTTP method	`BREW`, `PROPFIND`, `WHEN` — non-IANA verbs as first-class routes
Custom status code	`418 I'm a teapot` with application-level semantics
Custom content type	`message/coffeepot` on every `/pot` response
Application-defined header	`Accept-Additions: cream; sugar; whisky` with its own grammar
Error semantics	418 is not "server error" or "client error" — it means "wrong pot type"

If you can ship all five purely on app.route(), app.on_error(), and app.extensions, the extension surface is real. If you need to modify the framework core, it is not.

Spoiler: no core modifications were needed.

The extension surface

BlackBull's extension model is deliberately minimal — no plugin registry, no dependency injection, no auto-discovery:

# app.route — accepts any RFC 9110 section 5.6.2 token since v0.42.1
@app.route(path='/pot', methods=['BREW', HTTPMethod.POST])
async def brew_handler(scope, receive, send): ...

# app.on_error — custom handler for any HTTP status
@app.on_error(HTTPStatus.IM_A_TEAPOT)
async def teapot_handler(scope, receive, send): ...

# app.extensions — plain dict, stable key
app.extensions['htcpcp'] = self

That is the entire API surface the extension touches. Four @app.route decorators, one app.on_error(418), and one dict assignment. The remaining 300 lines are the Accept-Additions parser, the pot state machine (idle -> brewing -> ready), and the teapot discrimination logic from RFC 7168 section 2.1.

What teapot discrimination looks like in code

RFC 7168 adds nuance: a teapot does not always return 418. Asked to brew tea (with explicit tea additions like milk, lemon, honey), it returns 200. Asked to brew coffee, or asked with no additions at all, it returns 418:

if self._pot_type == 'teapot':
    has_coffee = any(a in COFFEE_ADDITIONS for a in additions)
    has_tea    = any(a in TEA_ADDITIONS for a in additions)
    if not has_tea or has_coffee:
        await send(self._teapot_response())  # 418
        return
# ...proceed to brew (200)

This is the kind of detail that separates "I made a 418 joke endpoint" from "I implemented the RFC." Prior Python implementations (HyperTextCoffeePot, 78 stars, Flask, archived 2015) handled 418 but not RFC 7168 teapot/coffee-pot discrimination.

Security: the threat model

HTCPCP inherits HTTP's full attack surface. Accept-Additions is a semicolon-delimited header parsed from untrusted input — it needs the same hardening as any other HTTP header parser. The test suite documents 15 security cases (S001–S015); the most illustrative are shown below:

Case	Category	Threat	Mitigation
S001–S003	Header injection	CRLF / LF / NULL byte in addition tokens	Rejected at parse -> 400
S004–S005	DoS	Token > 256 chars, or > 64 tokens	Rejected -> 400
S006–S007	DoS	Concurrent BREW, body > 1 MiB	409 / 413
S008	Control chars	Non-printable chars below 0x20 (except HTAB)	Rejected -> 400
S010	418 abuse	Cache poisoning via 418 + `Cache-Control`	No permissive cache headers on 418
S014	Smuggling	BREW + Content-Length / Transfer-Encoding games	Body capped, not interpreted
S015	Replay	Race: two BREW requests simultaneously	State machine guards brewing state

Every rejection — 400, 409, 413 — returns Content-Type: message/coffeepot. The error format is consistent regardless of which security boundary was hit. The protocol is absurd; the parser is not.

Prior art

Roughly 105 HTCPCP repos on GitHub across all languages. The top implementations by stars:

Implementation	Language	Stars	Last updated	RFC 7168
HyperTextCoffeePot	Python (Flask)	78	2015	No
madmaze/HTCPCP	C	49	2011	No
node-htcpcp	Node.js	36	2013	No
htcpcp-delonghi	JS (Tessel 2)	29	2023	No
blackbull-htcpcp	Python (BlackBull)	—	2026 (active)	Yes

blackbull-htcpcp is the first Python package on PyPI implementing HTCPCP, one of two known implementations covering both RFCs, the only ASGI-native one, and actively maintained with 53 automated tests.

Why joke RFCs matter

RFC 1149 (IP over Avian Carriers, 1990) was implemented by the Bergen Linux User Group in 2001 — 9 packets over 5 km, 55% packet loss, mostly pigeon-related. The #save418 movement in 2017 kept status 418 in Python, Go, and Node.js. Google serves google.com/teapot.

The cultural through-line is that implementing joke protocols is a form of protocol literacy. HTCPCP is small enough to implement in an afternoon, but it touches custom methods, custom status codes, custom content types, header parsing, and error semantics — the same extension points a real application protocol would need.

How this was tested

Every claim above was tested against the published packages before writing.

Test suite: 53/53 passing (pytest tests/ -v in blackbull-htcpcp).

HTTP method validation: BREW, PROPFIND, WHEN all pass BlackBull's RFC 9110 §5.6.2 tchar check, added in v0.42.1 specifically to unblock this extension (changelog).

Framework surface audit: The extension imports only from blackbull (public top-level): BlackBull, Response, read_body, Headers. No blackbull._*, no blackbull.server.*, no monkey-patches.

End-to-end wire output: All responses shown in the terminal session at the top of this article were verified against the published packages using blackbull.testing.TestClient; the curl commands shown produce identical output.

blackbull-htcpcp is on PyPI and GitHub. BlackBull is a pure-Python ASGI server with HTTP/1.1, HTTP/2, and WebSocket at the protocol level.