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

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:

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:

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:

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:

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.