glm-5.3-flash
bd7d1ad8ec
The Phase 0 OQ ledger (OQ-TN-01..10) promoted into
docs/architecture/open-questions.md (now OQ-TN-01..14, with four
new Phase 1 residues). Six ADRs and four spec docs, all Draft, all
decision-shaped per the SDD process (ADRs carry the WHY; specs carry
the WHAT and reference by number):
ADRs:
- 001 open-params-layout: params = {resource, substrate} — the
producer's stable name, not an address; wire-stable from the first
consumer; unknown substrates fail loudly at schema time
- 002 alpn-strategy: single alk/tunnel ALPN (option A); substrate in
params selects the framing; prior art (SSH/SOCKS5/udpgw) gives no
reason for the split
- 003 codec-and-udp-framing: raw pass-through (stream) / mandatory
[len: u16 BE] (UDP) — F-2 mandate recorded (the codec is mandatory
for correctness, not cosmetics); len=0 = legal empty datagram;
OQ-TN-13 resolved fail-loud (truncation)
- 004 no-backend-trait: halves functions at the assembly layer;
listen is an establisher shape; hub re-produce deferred(OQ-TN-12);
trait re-evaluated at the alknet ADR-078 convergence threshold
- 005 consumer-session-owns-teardown: TunnelSession with
open/adopt/stream_halves/take_halves/pump_against/close/join/Drop —
the W3 adopter gap closes structurally; Drop is the best-effort
fallback
- 006 access-control-posture: the open gate is the boundary;
TUNNEL_OPEN_SCOPE = tunnel:open (stable once published); op-level
ACL; ownership seam; no allowlists in v1; identity = 0.7.0's
precedence chain
Spec docs:
- overview.md: purpose, resource model, deps (alkcall 0.7.0,
wasm-clean default, local feature), module map
- wire.md: the open op (params/reply/typed errors), the data plane
by substrate, sentinels + half-close, byte diagrams
- producer.md: spec, establisher (dial + listen shapes), pump
handler (pump_bidi inline, R-02), registration API, ACL posture
- consumer.md: TunnelSession (forward open + reverse adopt
construction), data plane, teardown API (close/join/Drop incl.
pump-less join semantics)
- bast.md: the BAST doc for the UDP codec (convention 12's trigger
fired — the framing IS binary beyond pass-through)
- open-questions.md: OQ-TN-01..14; 01..10 promoted (faithful to the
phase-0 ledger's final states), 11 partially resolved (collision
domain = per-producer registry per ADR-001; lifecycle open),
12 deferred(scope), 13 resolved fail-loud (ADR-003), 14 open
Verified by an architecture-reviewer pass (2 criticals, 6 majors,
10 minors — all fixed: ADR-001/003-vs-OQ decision-state contradictions
resolved; the Layer-2 mislabel corrected to the ADR-047 §4 per-session
fork; alktty/alknet ADR misattributions fixed; codec placement pinned
to the establisher (pump stays substrate-agnostic); reverse-path
construction named (TunnelSession::adopt + pump_against); security
posture promoted to ADR-006; BAST doc written; F-2 rationale deduped;
README tables completed; channel_id > 0; MTU wording fixed; ADR-047 §5
attributions corrected; impacts lines added to unresolved OQs; review/
ledger pointer paths added to README references).
Verification: doc set internal cross-refs all resolve; cargo test,
fmt --check, doc --no-deps clean
111 lines
5.5 KiB
Markdown
111 lines
5.5 KiB
Markdown
# ADR-003: Data-Plane Codec — Raw Pass-Through (Stream) / Mandatory Length Framing (UDP)
|
|
|
|
## Status
|
|
|
|
Accepted (2026-09-07; supersedes the Phase 0 "codec direction" hunch
|
|
by making the UDP framing mandatory — reverse POC finding F-2)
|
|
|
|
## Context
|
|
|
|
The tunnel data plane rides a channels data channel: raw bytes inside
|
|
the channel `BiStream` (the channels layer strips its 8-byte header
|
|
transparently — alknet ADR-093/ADR-071; AGENTS.md convention 5). The
|
|
tunnel protocol owns whatever framing it puts inside the `BiStream`.
|
|
A tunnel has one data stream per direction, so there is no
|
|
sub-demux key — a 5-byte header like alktty's (with `stream_type`)
|
|
would be pure overhead here.
|
|
|
|
The Phase 0 direction (`phase-0-findings.md` checklist, 2026-09-06):
|
|
raw pass-through for stream substrates (0 B tunnel overhead),
|
|
`[len: u16 BE]` per datagram for UDP (2 B/datagram), with the
|
|
empty-datagram (`len=0`) semantic left as a Phase 1 residue.
|
|
|
|
Two validation passes sharpened this:
|
|
|
|
1. **Forward POC (2026-09-06, 17 tests):** the codec round-trips
|
|
datagrams split across chunks, batched in one chunk, partial
|
|
headers, and empty datagrams (`len=0` is a legal payload, NOT EOF
|
|
— EOF is the channels-level `length=0` chunk sentinel; the two
|
|
coexist at different layers). The 1400-byte (max ethernet MTU
|
|
payload) datagram rides the bounded-buffer path; >65535 is
|
|
rejected at frame time.
|
|
2. **Reverse POC finding F-2 (2026-09-07, executable-pinned):** in
|
|
the RAW pass-through pump shape, an empty UDP datagram is a
|
|
zero-byte read from the substrate adapter — `tokio::io::copy`
|
|
treats `Ok(0)` as end-of-stream and shuts the pump down. An empty
|
|
datagram and the zero-length EOF sentinel are the SAME wire shape
|
|
at the pump level. The test pins the non-round-trip so the
|
|
conclusion is executable, not anecdotal.
|
|
|
|
## Decision
|
|
|
|
The data plane inside a `alk/tunnel` channel is:
|
|
|
|
- **Stream substrates (`tcp`, `unix`): raw pass-through.** The halves
|
|
are the tunnel; zero tunnel-level framing. The only wire overhead
|
|
is the channels 8-byte chunk header. A zero-length read on a stream
|
|
substrate is genuinely EOF (stream semantics) — no collision. Both
|
|
pumps run `alkcall::channels::pump_bidi` (ADR-050) over the raw
|
|
halves.
|
|
- **Datagram substrate (`udp`): mandatory `[len: u16 BE][datagram]`
|
|
framing, applied at the substrate/pump boundary.** One datagram per
|
|
length-prefixed frame, on BOTH directions:
|
|
- The **establisher** wraps the dialed UDP socket in the framed
|
|
adapter BEFORE returning the plan (the plan payload is the
|
|
adapter, not a raw socket) — the pump handler stays
|
|
substrate-agnostic (ADR-004's invariant; producer.md's placement).
|
|
- Consumer side: the `TunnelSession`'s datagram variant does the
|
|
same over the adopted halves.
|
|
- **`len=0` is a legal empty datagram** (DNS-over-TCP-style
|
|
zero-payload probes); it round-trips under the codec (forward
|
|
POC). EOF is exclusively the channels-level sentinel; the codec
|
|
never emits zero-length reads, so the layers never collide. This
|
|
is the load-bearing property F-2 validated from a second angle:
|
|
the length prefix makes an empty datagram two bytes — unambiguous
|
|
with EOF.
|
|
- **MTU discipline:** the codec rejects framing a >65535-byte
|
|
datagram (`Oversize` error at frame time, never a wire overflow —
|
|
the u16 length field would wrap). A truncated receive (caller
|
|
buffer smaller than the datagram) fails loudly at the adapter
|
|
level — resolved 2026-09-07 (OQ-TN-13, fail-loud): silent
|
|
truncation would corrupt the framing invariants (the same
|
|
invariant class F-2 protects).
|
|
- **Chunking is transparent.** Datagrams split across channel chunks,
|
|
batch into single chunks, and survive partial headers — the
|
|
incremental decoder is the only consumer-visible decode path
|
|
(forward POC: maximally awkward 7-byte chunk splits verified).
|
|
|
|
## Consequences
|
|
|
|
- **TCP/unix tunnels have 0 B tunnel overhead** — the SSH
|
|
`direct-tcpip` experience (the payload is the bytes).
|
|
- **UDP correctness requires the codec** — raw pass-through over UDP
|
|
is structurally broken for empty datagrams (F-2). The substrate
|
|
discriminator (ADR-001) is what tells both sides to engage the
|
|
codec; a consumer bypassing it for UDP is a spec violation, not a
|
|
degraded mode.
|
|
- **`tokio::io::copy`-shaped pumps fit UDP only through the framed
|
|
adapter** (the `UdpHalf` + codec wrapper presents
|
|
`AsyncRead`/`AsyncWrite` whose zero-length read never occurs for a
|
|
well-formed stream — `len=0` yields a 2-byte wire frame).
|
|
- **The BAST document exists** (AGENTS.md convention 12 — the
|
|
mandatory framing IS binary framing beyond pass-through, so the
|
|
trigger fired): `docs/architecture/bast.md` describes the
|
|
`[len: u16 BE]` datagram frame per the BAST meta-schema; the
|
|
hand-rolled codec remains the runtime implementation.
|
|
- **No mid-stream control frames.** Pump-phase failures are
|
|
EOF-shaped by design (alkcall ADR-049 §6); there is no tunnel-level
|
|
error frame, no KEEPALIVE (channels transport liveness is
|
|
upstream's), no flow-expiry frame (producer-side bookkeeping).
|
|
|
|
## References
|
|
|
|
- OQ-TN-02 (promoted), OQ-TN-13 (resolved by this ADR's fail-loud
|
|
posture)
|
|
- Forward POC: `docs/research/poc-summary.md` §3 (codec decision +
|
|
sentinel layering + MTU); reverse POC:
|
|
`docs/research/reverse-poc-summary.md` §F-2 (the mandate)
|
|
- `docs/research/ssh-socks5-survey.md` §UDP (tun2proxy udpgw framing
|
|
precedent — no CONN_ID, no FLAGS; boundary framing only)
|
|
- alknet ADR-071/093 (channels wire format; the zero-length sentinel)
|
|
- alkcall `channels::pump_bidi` (ADR-050) |