bengal-zoomies 0.1.0

Free-threading-native QUIC and HTTP/3 for Python 3.14t — sans-I/O, typed

⚡ Zoomies

Free-threading-native QUIC and HTTP/3 for Python 3.14t — sans-I/O, typed

from zoomies.core import QuicConnection, QuicConfiguration
from zoomies.events import HandshakeComplete

config = QuicConfiguration(certificate=cert, private_key=key)
conn = QuicConnection(config)

# Sans-I/O: feed datagrams in, get events out
events = conn.datagram_received(datagram, addr)
for event in events:
    if isinstance(event, HandshakeComplete):
        ...
for dg in conn.send_datagrams():
    sock.sendto(dg, addr)

---

What is Zoomies?

Zoomies is a sans-I/O protocol library for QUIC (RFC 9000) and HTTP/3 (RFC 9114). Native to the b-stack (Pounce, Chirp), it has no b-stack dependencies and works anywhere — pure Python, cryptography only, free-threaded Python 3.14t. Alpha: full TLS 1.3 handshake, Handshake + 1-RTT packets.

What's good about it:

• Sans-I/O — Protocol layer consumes bytes, produces bytes. No socket access. Caller owns I/O.
• Types as contracts — Frozen dataclasses for events, Protocols for handlers.
• Free-threading native — No C extensions with limited API. Uses cryptography (3.14t-compatible).
• Composition — Packet → Crypto → Stream → Connection → HTTP/3. Each layer testable in isolation.

---

What it does

API	Description
QuicConnection.datagram_received()	Feed UDP datagram in, get protocol events
QuicConnection.send_datagrams()	Get outbound datagrams to transmit
H3Connection	HTTP/3 connection state machine (QPACK, streams)
encode_headers / decode_headers	QPACK header compression
pull_quic_header()	Parse QUIC packet headers (Initial, Handshake, etc.)

---

Installation

pip install zoomies

Requires Python 3.14+

---

Quick Start

QPACK encode/decode

from zoomies.h3 import Header, decode_headers, encode_headers

headers = [
    Header(name=":method", value="GET"),
    Header(name=":path", value="/api/users"),
    Header(name=":scheme", value="https"),
]
encoded = encode_headers(headers)
decoded = decode_headers(encoded)

Parse QUIC Initial packet

from zoomies.encoding import Buffer
from zoomies.packet import pull_quic_header

buf = Buffer(data=raw_bytes)
header = pull_quic_header(buf, host_cid_length=None)
print(f"Version: {header.version:#x}, CID: {header.destination_cid}")

Sans-I/O connection (server)

from zoomies.core import QuicConnection, QuicConfiguration
from zoomies.events import HandshakeComplete

with open("cert.pem", "rb") as f:
    cert = f.read()
with open("key.pem", "rb") as f:
    key = f.read()
config = QuicConfiguration(certificate=cert, private_key=key)
conn = QuicConnection(config)

events = conn.datagram_received(datagram, addr)
for event in events:
    if isinstance(event, HandshakeComplete):
        print("Handshake done!")
for dg in conn.send_datagrams():
    sock.sendto(dg, addr)

Run the examples (from repo root):

uv run python -m examples.qpack_roundtrip
uv run python -m examples.parse_initial_packet
uv run python -m examples.sans_io_connection

---

Examples

Example	Description
examples/qpack_roundtrip.py	QPACK header encode/decode
examples/parse_initial_packet.py	Parse QUIC Initial packet header
examples/sans_io_connection.py	Sans-I/O QuicConnection demo (uses test fixtures)

---

Usage

Events — Frozen dataclasses for protocol state changes

from zoomies.events import (
    DatagramReceived,
    HandshakeComplete,
    StreamDataReceived,
    ConnectionClosed,
)

for event in conn.datagram_received(datagram, addr):
    match event:
        case HandshakeComplete():
            ...
        case StreamDataReceived(stream_id=id, data=data):
            ...
        case ConnectionClosed():
            ...

HTTP/3 — H3Connection for request/response

from zoomies.h3 import H3Connection, H3HeadersReceived, H3DataReceived

h3 = H3Connection(is_client=False)
# Feed H3 frames from QUIC streams into h3.receive_*()
# Handle H3HeadersReceived, H3DataReceived events

Free-threading — Python 3.14t

Zoomies uses frozen dataclasses, no shared mutable state, and cryptography (3.14t-compatible). Safe to run multiple QuicConnection instances from different threads.

---

Development

git clone https://github.com/lbliii/zoomies.git
cd zoomies
uv sync --group dev
pytest

Lint and types:

ruff check src tests
ty check

---

Related: The Bengal Ecosystem

Zoomies is developed as part of the b-stack but is standalone. No imports from Bengal, Chirp, or Pounce. A structured reactive stack — every layer written in pure Python for 3.14t free-threading.

ᓚᘏᗢ	Bengal	Static site generator	Docs
∿∿	Purr	Content runtime	—
⌁⌁	Chirp	Web framework	Docs
=^..^=	Pounce	ASGI server	Docs
)彡	Kida	Template engine	Docs
ฅᨐฅ	Patitas	Markdown parser	Docs
⌾⌾⌾	Rosettes	Syntax highlighter	Docs
⚡	Zoomies	QUIC/HTTP/3 ← You are here	—

Python-native. Free-threading ready. No npm required.

---

License

MIT License — see LICENSE for details.