chore: rename project quicnprotochat -> quicproquo (binaries: qpq)
Rename the entire workspace:
- Crate packages: quicnprotochat-{core,proto,server,client,gui,p2p,mobile} -> quicproquo-*
- Binary names: quicnprotochat -> qpq, quicnprotochat-server -> qpq-server,
quicnprotochat-gui -> qpq-gui
- Default files: *-state.bin -> qpq-state.bin, *-server.toml -> qpq-server.toml,
*.db -> qpq.db
- Environment variable prefix: QUICNPROTOCHAT_* -> QPQ_*
- App identifier: chat.quicnproto.gui -> chat.quicproquo.gui
- Proto package: quicnprotochat.bench -> quicproquo.bench
- All documentation, Docker, CI, and script references updated
HKDF domain-separation strings and P2P ALPN remain unchanged for
backward compatibility with existing encrypted state and wire protocol.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
116
docs/src/design-rationale/adr-006-rest-gateway.md
Normal file
116
docs/src/design-rationale/adr-006-rest-gateway.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# ADR-006: SDK-First Adoption — Native QUIC + Cap'n Proto, No REST Gateway
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (supersedes earlier REST gateway proposal)
|
||||
|
||||
## Context
|
||||
|
||||
quicproquo uses QUIC + Cap'n Proto RPC as its native protocol. This
|
||||
combination delivers zero-copy serialization, multiplexed streams, and
|
||||
sub-RTT connection establishment — ideal for high-performance clients.
|
||||
|
||||
Cap'n Proto has limited language support compared to Protocol Buffers or
|
||||
JSON. Adding an HTTP/JSON REST gateway was considered to lower the barrier
|
||||
to entry. However, this would:
|
||||
|
||||
1. **Contradict the project identity.** The name is literally
|
||||
**quic**n**proto**chat. An HTTP gateway undermines the protocol-native
|
||||
philosophy.
|
||||
2. **Add base64 overhead (~33%)** for binary payloads (MLS ciphertext, key
|
||||
packages) that are already optimal in Cap'n Proto's wire format.
|
||||
3. **Create a second code path** to maintain, test, and secure.
|
||||
4. **Lose QUIC transport benefits** (0-RTT, multiplexing, congestion control)
|
||||
for clients that use the HTTP path.
|
||||
|
||||
## Decision
|
||||
|
||||
**No REST/HTTP gateway.** Instead, invest in native QUIC + Cap'n Proto
|
||||
SDKs for every viable language, plus WASM/FFI for the crypto layer.
|
||||
|
||||
The `.capnp` schema files ARE the interface definition — they serve the
|
||||
same role as an OpenAPI spec, but for the native protocol.
|
||||
|
||||
### SDK strategy
|
||||
|
||||
| Language | QUIC | Cap'n Proto | Approach |
|
||||
|----------|------|-------------|----------|
|
||||
| **Rust** | quinn | capnp-rpc | Existing reference client |
|
||||
| **Go** | quic-go | go-capnp | Native SDK, high confidence |
|
||||
| **Python** | aioquic | pycapnp | Native QUIC, manual RPC framing |
|
||||
| **C/C++** | msquic/ngtcp2 | capnproto | Reference impl, full RPC |
|
||||
| **Browser** | WebTransport | WASM bridge | QUIC transport via HTTP/3 |
|
||||
|
||||
### Browser access via WebTransport
|
||||
|
||||
Browsers cannot open raw QUIC connections, but they can use
|
||||
**WebTransport** — which runs over HTTP/3 (which runs over QUIC). The
|
||||
server adds a WebTransport listener alongside the Cap'n Proto QUIC
|
||||
listener. Cap'n Proto RPC is framed over WebTransport bidirectional
|
||||
streams, identical to the native path.
|
||||
|
||||
```
|
||||
Browser → WebTransport (HTTP/3 over QUIC) → Cap'n Proto RPC → Server
|
||||
Native → QUIC → Cap'n Proto RPC → Server
|
||||
```
|
||||
|
||||
Both paths use QUIC transport. The project name stays honest.
|
||||
|
||||
### Crypto layer distribution
|
||||
|
||||
MLS encryption/decryption must happen client-side. The `quicproquo-core`
|
||||
crate is compiled to:
|
||||
|
||||
- **WASM** — for browsers, Node.js, Deno
|
||||
- **C FFI** (`libquicproquo`) — for Swift, Kotlin, Python, Go (via cgo)
|
||||
- **Native Rust** — for Rust clients (existing)
|
||||
|
||||
### Why not REST?
|
||||
|
||||
1. **Protocol purity.** One protocol, one code path, one mental model.
|
||||
2. **No serialization tax.** No base64, no JSON parsing, no HTTP headers.
|
||||
3. **QUIC everywhere.** WebTransport gives browsers QUIC access without HTTP
|
||||
semantics leaking into the protocol.
|
||||
4. **Schema-driven.** `.capnp` files generate type-safe stubs in every
|
||||
supported language — the same developer experience as protobuf/gRPC.
|
||||
|
||||
### Why not gRPC?
|
||||
|
||||
1. **We already have Cap'n Proto** with zero-copy deserialization.
|
||||
2. Adding protobuf would mean three serialization formats in one project.
|
||||
3. Cap'n Proto's time-travel RPC (promise pipelining) is architecturally
|
||||
superior to gRPC's request-response model for chained operations.
|
||||
|
||||
gRPC may be reconsidered for server-to-server federation (Phase 7.3).
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- **Protocol coherence.** Every client speaks the same wire format.
|
||||
- **Performance.** No translation layer, no base64 overhead, no HTTP framing.
|
||||
- **Identity.** The project name accurately describes the protocol stack.
|
||||
- **Security.** One code path to audit, not two.
|
||||
- **WebTransport.** Browsers get native QUIC with the same RPC interface.
|
||||
|
||||
### Negative
|
||||
|
||||
- **Higher SDK effort.** Each language needs a QUIC + Cap'n Proto
|
||||
integration, not just an HTTP client.
|
||||
- **Cap'n Proto ecosystem gaps.** JavaScript and Swift lack mature Cap'n
|
||||
Proto RPC libraries; these languages rely on WASM bridges.
|
||||
- **WebTransport maturity.** Browser support is good (Chrome, Edge, Firefox)
|
||||
but not universal; Safari support is emerging.
|
||||
|
||||
### Neutral
|
||||
|
||||
- SDKs live in separate repositories (e.g., `quicproquo-go`,
|
||||
`quicproquo-py`) to avoid bloating the core workspace.
|
||||
- The C FFI crate (`quicproquo-ffi`) bundles both crypto and transport,
|
||||
so language bindings only need to call C functions.
|
||||
|
||||
## Related
|
||||
|
||||
- [ADR-002: Cap'n Proto over MessagePack](adr-002-capnproto.md) — why Cap'n Proto was chosen
|
||||
- [ROADMAP Phase 3](../../../ROADMAP.md) — SDK implementation plan
|
||||
- [FUTURE-IMPROVEMENTS § 6.2](../../../docs/FUTURE-IMPROVEMENTS.md) — WebTransport research
|
||||
Reference in New Issue
Block a user