moqtap-proxy

Transparent MoQT intercepting proxy — sits between a client and relay, forwarding all bytes bidirectionally while parsing MoQT frames inline to produce structured events.

crates.io | API docs

What it does

The proxy does not participate in MoQT state management. It observes and optionally mutates, but never acts as an endpoint. Supports every MoQT wire format from draft-07 through draft-17 at runtime via moqtap-codec’s dispatch layer — the draft is selected from the observed setup exchange.

1. Listen for inbound connections from MoQT clients (QUIC or WebTransport)
2. Connect upstream to a MoQT relay (QUIC or WebTransport)
3. Forward all streams (bidirectional, unidirectional) and datagrams between the two
4. Parse MoQT frames inline — control messages, data stream headers, object headers, datagrams
5. Emit structured ProxyEvents via the ProxyObserver trait (11 event types including setup detection)
6. Optionally mutate forwarded bytes via the ProxyHook trait (for fault injection, protocol testing)

Client ──QUIC/WT──▶ moqtap-proxy ──QUIC/WT──▶ Relay
                       │
                       ├─ parses frames inline (draft-07..17)
                       ├─ emits ProxyEvents
                       └─ applies ProxyHook mutations

Key types

Type	Description
TransparentProxy	Accept loop orchestrator — binds listener, spawns per-connection sessions
ProxySession	Per-connection forwarder — pipes streams + datagrams between client and relay
ProxyConfig	Top-level configuration (listener, session, listener mode)
ListenerMode	Client-facing transport: Quic or WebTransport
Listener	QUIC server endpoint that accepts inbound connections
WtListener	WebTransport server endpoint (behind webtransport)
UpstreamTransportType	Upstream relay transport: Quic or WebTransport { url }
ProxyObserver	Trait for receiving structured events (implement for logging, tracing, GUI)
ProxyHook	Trait for optional frame mutation (return Some(bytes) to replace, None to pass through)
ControlStreamParser	Stateful inline parser for control stream messages (draft-aware framing)
DataStreamParser	Stateful inline parser for data stream headers and objects
GeneratedCert	Self-signed certificate for development/testing (behind cert-gen)

Responsibility boundaries

moqtap-proxy IS responsible for:

• Accepting inbound connections (QUIC or WebTransport, server-side TLS)
• Self-signed certificate generation (behind cert-gen)
• Connecting to upstream relays (QUIC or WebTransport)
• Stream-level forwarding (bidirectional, unidirectional, datagrams)
• Inline MoQT frame parsing for observation (drafts 07 through 17)
• Automatic stream type detection (subgroup vs fetch) on unidirectional streams
• Setup message detection (CLIENT_SETUP / SERVER_SETUP emitted as distinct events)
• Event emission via ProxyObserver
• Optional byte mutation via ProxyHook
• Graceful shutdown via CancellationToken

moqtap-proxy is NOT responsible for:

• MoQT protocol state management (no subscribe/fetch/publish state machines)
• Deciding what to forward, filter, or modify (caller provides hooks)
• Trace file I/O (caller wires events to moqtap-trace)
• User interface

Feature flags

Feature	Default	Description
cert-gen	no	Self-signed certificate generation via rcgen
webtransport	no	WebTransport listener and upstream support via wtransport