blackbull-htcpcp

A BlackBull extension implementing HTCPCP — the Hyper Text Coffee Pot Control Protocol from RFC 2324 (1998 April Fool's) and its tea-pot extension RFC 7168 (2014 April Fool's).

The joke is well-known. The reason to actually ship it is that HTCPCP is a small, frozen RFC that uses every awkward corner of HTTP at once — a custom method, a custom status code, a custom content type, an application-defined request header with its own grammar, and error semantics that aren't really about HTTP itself. Implementing it end-to-end in roughly 350 lines on top of an unmodified web framework makes a fine worked example for how far HTTP can be pushed as an application-protocol carrier.

Here is what the package actually puts on the wire:

BREW /pot HTTP/1.1                ← the real RFC 2324 verb (POST still works as an alias)
Host: localhost:8000
Accept-Additions: cream; sugar

HTTP/1.1 200 OK
Content-Type: message/coffeepot

{"pot-type": "coffee", "state": "ready", "additions": ["cream", "sugar"]}

Ask a teapot to brew coffee, and it answers honestly:

POST /pot HTTP/1.1
Host: localhost:8000

HTTP/1.1 418 I'm a teapot
Content-Type: message/coffeepot

{"error": "I'm a teapot", "pot-type": "teapot"}

All of it sits on BlackBull's documented init_app(app) extension surface — no framework fork, no monkey-patches. See src/blackbull_htcpcp/extension.py.

Install

pip install blackbull-htcpcp

Use

from blackbull import BlackBull
from blackbull_htcpcp import HtcpcpExtension

app = BlackBull()
HtcpcpExtension(app=app, pot_type='coffee')   # or pot_type='teapot'

# Deferred form, if you configure the app elsewhere:
ext = HtcpcpExtension(pot_type='teapot')
ext.init_app(app)

# Multiple pots on one app — pick a path per instance (default '/pot'):
HtcpcpExtension(app=app, pot_type='teapot', path='/teapot')  # RFC 7168 teapot

After init_app(app) the live extension sits at app.extensions[f'htcpcp:{path}'] ('htcpcp:/pot' by default). Four routes (BREW / PROPFIND / WHEN / GET) are registered on the mount path, a readiness route at f'{path}/when', plus an app.on_error(418) handler so any 418 the rest of the app emits gets the same message/coffeepot body.

The RFC 2324 verbs are exposed as a public StrEnum, and 418 is re-exported for discoverability:

from http import HTTPMethod

from blackbull_htcpcp import HtcpcpMethod, IM_A_TEAPOT

# StrEnum: members compare equal to plain strings and mix freely
# with http.HTTPMethod in route registrations.
@app.route(path='/my-pot', methods=[HtcpcpMethod.BREW, HTTPMethod.POST])
async def my_brew(scope, receive, send): ...

assert HtcpcpMethod.BREW == 'BREW'
assert IM_A_TEAPOT == 418          # http.HTTPStatus.IM_A_TEAPOT

What it implements

• BREW — start brewing. Registered as a first-class BREW route on /pot (BlackBull ≥ 0.42.1 dispatches arbitrary method tokens); POST is kept as a backwards-compatible alias.
• PROPFIND — inspect the pot's metadata. Exposed via GET in the same window; native PROPFIND verb gated on the same framework change.
• WHEN — readiness check (GET /pot/when).
• 418 I'm a teapot — RFC 2324 §2.2.2. A teapot brewing anything that isn't tea returns 418. Coffee pots return 200 for any brew request.
• message/coffeepot — content type on every /pot response, success or error.
• Accept-Additions — cream; sugar; vanilla etc. Parsed, lower-cased, validated.

Configuration

Security

HTCPCP is a joke; the parser isn't. Accept-Additions is rejected when an addition token contains:

• CRLF or bare LF (response splitting),
• a NULL byte,
• non-printable control characters (other than horizontal tab — valid OWS per RFC 9110 §5.6.3),
• more than 256 characters,

or when the request carries more than 64 addition tokens. BREW request bodies are capped at 1 MiB. See tests/test_htcpcp.py for the full S001–S015 matrix.

How it fits

blackbull-htcpcp is the second external extension built on BlackBull's init_app(app) convention, after blackbull-session. It exists partly to prove that the extension surface can carry a non-trivial application protocol — custom methods, custom content types, custom error semantics — without modifications to the framework itself. The cultural reference is IPoAC (RFC 1149, implemented by Bergen Linux User Group in 2001): the joke RFCs are funny because they could actually be implemented, and implementing them teaches something about the layer underneath.

License

Apache License 2.0 — © TOKUJI.