docs: Phase 1 architecture spec — ADRs 001..006, spec docs, OQ promotion
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
This commit is contained in:
@@ -0,0 +1,168 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-09-07
|
||||
---
|
||||
|
||||
# alktunnels — Wire Format
|
||||
|
||||
The `alk/tunnel` wire surface. Two layers: the **open op** (JSON
|
||||
params on the channels call plane — structured, schema-validated,
|
||||
typed errors) and the **data plane** (bytes/datagrams inside the
|
||||
channel `BiStream` — the codec, ADR-003). The channels layer strips
|
||||
its own 8-byte header transparently (alknet ADR-093); the tunnel
|
||||
protocol owns everything inside the `BiStream`.
|
||||
|
||||
Design decisions live in the ADRs ([001](decisions/001-open-params-layout.md),
|
||||
[002](decisions/002-alpn-strategy.md), [003](decisions/003-codec-and-udp-framing.md));
|
||||
this document is the normative WHAT.
|
||||
|
||||
## The Open Op (`channels/tunnel/sub`)
|
||||
|
||||
`Sub`-typed operation (alkcall ADR-047): the reply carries
|
||||
`{ "channel_id": <u32> }` once; the data plane flows on the channel's
|
||||
`BiStream` — never in the call response stream.
|
||||
|
||||
### Input (params)
|
||||
|
||||
```json
|
||||
{
|
||||
"resource": "postgres-primary",
|
||||
"substrate": "tcp"
|
||||
}
|
||||
```
|
||||
|
||||
- `resource`: string, required — the producer's stable resource name
|
||||
(NOT an address; the producer's registry maps it to its backing).
|
||||
- `substrate`: string, required, enum `["tcp", "udp", "unix"]` — the
|
||||
extensible discriminator (ADR-001); selects the data-plane framing.
|
||||
- `input_schema` pins both as required strings; unknown substrate
|
||||
values fail schema validation (typed error — loud, not silent).
|
||||
- Extensibility: a new substrate is a new enum value, not a format
|
||||
change. An older producer rejecting a newer substrate is the SSH
|
||||
"unknown channel type" posture.
|
||||
|
||||
### Reply / errors
|
||||
|
||||
- Success: `{ "channel_id": <u32> }` — the channel is open, the
|
||||
establishment phase (dial) succeeded, the pump handler is running.
|
||||
- Failure: a typed `channel:open_failed` call error with
|
||||
`details: { reason, message }` — `reason ∈ dial_failed` /
|
||||
`unknown_resource` / `resource_shortage` / `handler_error` /
|
||||
`timeout` (alkcall ADR-049 §3). The registry's ACL gate runs before
|
||||
the wrapper (`FORBIDDEN` for a scope-less identity); the 256-channel
|
||||
cap is `channel:too_many_channels`. **A failed open never returns a
|
||||
`channel_id`** — no phantom channel (the SSH contract, POC-verified
|
||||
from the consumer side).
|
||||
- The scope gate: the open op's `AccessControl.required_scopes` is
|
||||
`["tunnel:open"]` (the `TUNNEL_OPEN_SCOPE` constant). Caller
|
||||
identity resolves in the alkcall 0.7.0 precedence order: payload
|
||||
`auth_token` > `ServingConfig.identity` > transport identity (CF-005);
|
||||
the establisher and pump handler receive the per-call opener
|
||||
identity (CF-006).
|
||||
|
||||
## The Data Plane
|
||||
|
||||
One data stream per direction on one channel — the channel ID is the
|
||||
flow key (no conn-id, no sub-demux). Two codecs by substrate
|
||||
(ADR-003):
|
||||
|
||||
### 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 is
|
||||
genuinely EOF (stream semantics).
|
||||
|
||||
Both pumps run `alkcall::channels::pump_bidi(channel, peer_read,
|
||||
peer_write)` — the two-pump contract (alknet ADR-078, pinned upstream
|
||||
ADR-050): when one direction's source EOFs, the pump shuts the
|
||||
OPPOSITE sink down (the EOF sentinel crosses the mux; the peer sees a
|
||||
clean half-close), and the helper completes when both pumps finish,
|
||||
returning `(u64, u64)` copy counts. Copy errors are EOF-shaped
|
||||
(abrupt close); there is no `Err` state.
|
||||
|
||||
### Datagram substrate (`udp`): mandatory length framing
|
||||
|
||||
Every datagram rides `[len: u16 BE][datagram]` on BOTH directions —
|
||||
mandatory for correctness (the F-2 rationale lives in ADR-003; the
|
||||
short form: raw pass-through cannot carry an empty datagram). Under
|
||||
the codec:
|
||||
|
||||
- **Framing (`frame_datagram`):** `len: u16 BE` + payload. Datagrams
|
||||
> 65535 bytes are rejected at frame time (`Oversize`) — never a
|
||||
wire overflow (the u16 length field would wrap).
|
||||
- **Decoding (`DatagramReader`):** incremental — datagrams split
|
||||
across channel chunks, batch into single chunks, and survive
|
||||
partial headers. The decoder buffers state across reads; it is the
|
||||
only consumer-visible decode path.
|
||||
- **`len = 0` is a legal empty datagram** (DNS-over-TCP-style
|
||||
zero-payload probes). EOF is exclusively the channels-level
|
||||
sentinel (`BiStream` EOF after draining); the codec never emits
|
||||
zero-length reads, so the layers never collide. A `recv_datagram`
|
||||
returns `Some(bytes)` per datagram (possibly empty), `None` only on
|
||||
stream EOF.
|
||||
- **Chunk-size independence:** datagram boundaries survive chunk
|
||||
splitting, batching, and any channels-layer re-chunking — verified
|
||||
end-to-end at 7-byte chunk splits (forward POC).
|
||||
- **MTU discipline:** 1400-byte datagrams (a conservative MTU-safe
|
||||
payload, not the theoretical 1472 max) ride the bounded-buffer path;
|
||||
the 64-parked-chunks bound (alkcall early-arrival cap) is upstream
|
||||
sizing, not tunnel policy.
|
||||
- **Truncation:** a receive buffer smaller than the datagram fails
|
||||
loudly at the adapter level (OQ-TN-13, resolved fail-loud per
|
||||
ADR-003); silent truncation would corrupt the framing invariants.
|
||||
|
||||
### Sentinels and lifecycle (both codecs)
|
||||
|
||||
- **EOF:** the channels-level zero-length chunk, written by
|
||||
`pump_bidi`'s shutdown-on-completion or by a channel teardown
|
||||
(wrapper exit, `channel/close`, transport EOF → demux sender drop).
|
||||
EOF is per-direction (half-close): one direction EOFs, the other
|
||||
keeps pumping until its own EOF.
|
||||
- **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, and
|
||||
idle-expiry mapping is a producer-registry concern, not wire).
|
||||
- **No establishment frame.** The open op's reply IS the
|
||||
establishment result (ADR-049); the pre-ADR-049
|
||||
"JSON ack before data" hunch is superseded — the wire carries zero
|
||||
tunnel-level control framing in v1.
|
||||
- **BAST:** the binary framing (the UDP codec) carries its BAST
|
||||
document — [bast.md](bast.md) (AGENTS.md convention 12; the
|
||||
stream pass-through has no binary framing to describe).
|
||||
|
||||
## Normative byte diagrams
|
||||
|
||||
Stream substrate, one direction's wire view (inside the channel
|
||||
`BiStream`, after the channels layer's 8-byte header per chunk):
|
||||
|
||||
```
|
||||
<payload bytes> ... <EOF sentinel: channels-level length=0 chunk>
|
||||
```
|
||||
|
||||
UDP substrate, one direction's wire view:
|
||||
|
||||
```
|
||||
[len:u16 BE][datagram bytes] [len:u16 BE][datagram bytes] ...
|
||||
len == 0: an empty datagram (legal payload, NOT EOF)
|
||||
EOF: the channels-level sentinel, outside the codec
|
||||
```
|
||||
|
||||
## Open Questions
|
||||
|
||||
- **OQ-TN-13**: resolved (fail-loud, ADR-003) — see the Truncation
|
||||
bullet
|
||||
- **OQ-TN-02**: resolved — see the ADR-003 mandate
|
||||
|
||||
## References
|
||||
|
||||
- [ADR-001](decisions/001-open-params-layout.md) (params),
|
||||
[ADR-002](decisions/002-alpn-strategy.md) (ALPN),
|
||||
[ADR-003](decisions/003-codec-and-udp-framing.md) (codec),
|
||||
[ADR-005](decisions/005-consumer-session-owns-teardown.md) (session
|
||||
teardown)
|
||||
- Forward POC `docs/research/poc-summary.md` (codec + sentinel
|
||||
layering, 17 tests); reverse POC
|
||||
`docs/research/reverse-poc-summary.md` (F-2 mandate, W4 half-close)
|
||||
- alkcall ADR-047 (open ops), ADR-049 (establishment/typed errors),
|
||||
ADR-050 (`pump_bidi`); alknet ADR-071/093 (channels wire)
|
||||
Reference in New Issue
Block a user