glm-5.3-flash
69498b79cc
tasks/architecture/: - oq-promotion-sync (planning): back-pointers from the phase-0 ledger + AGENTS.md to the promoted OQ tracker (the convergence checklist's final half) - oq-tn-14-tracker: the Safe-Exit external-trigger tracker task for OQ-TN-14 (unix/stdio placement; [external-trigger, deferred-oq], risk trivial, level research per the two-halves rule) tasks/tunnels/ (the implementation graph, 8 generations): - crate-init: module skeleton per overview.md's module map - params: TunnelParams + open-op spec (ADR-001 wire-stable surface) - wire-codec: frame_datagram/DatagramReader + the 8 POC-pinned test families (ADR-003) - producer-open-op: establisher (dial, plan flow R-01) + pump handler (pump_bidi inline R-02) + registration; POC-ported integration tests - consumer-session: TunnelSession (open/adopt, data planes, teardown matrix — ADR-005); generalizes the reverse POC's ReverseTunnel - producer-listen: the listen establisher + AcceptQueue contract (ADR-004 shape 2) - local-socket-halves: the local feature (TCP/UDP/unix halves functions; truncation fail-loud per OQ-TN-13; unix ships per OQ-TN-14's lean-yes, stdio deferred) - review-core-crates: review-injection point before the downstream tasks build on the high-risk producer/consumer shapes - end-to-end-suite: 6 suites / >=20 tests consolidating both POC suites against the public API (the spec's executable form) - review-impl: the phase-gate review (wire/API/conventions/docs sync; findings doc per the alkhttp/alkcall house pattern) Graph verified with taskgraph: 12 tasks valid, no cycles, 8 generations; critical path = oq-promotion-sync -> crate-init -> params -> wire-codec -> producer-open-op -> consumer-session -> review-core-crates -> review-impl; risk concentrated in the two session tasks (both POC-validated); parallel groups available at generations 1 and 6
91 lines
3.3 KiB
Markdown
91 lines
3.3 KiB
Markdown
---
|
|
id: tunnels/wire-codec
|
|
name: Data-plane codec (frame_datagram / DatagramReader) + sentinel layering tests
|
|
status: pending
|
|
depends_on: [tunnels/crate-init, tunnels/params]
|
|
scope: narrow
|
|
risk: medium
|
|
impact: component
|
|
level: implementation
|
|
tags: [wire, codec, udp]
|
|
---
|
|
|
|
## Description
|
|
|
|
Implement `src/wire.rs` per ADR-003 + wire.md §The Data Plane + bast.md:
|
|
the mandatory UDP length-framing codec. This is a direct port of the
|
|
forward POC's `/workspace/alktunnels-udp-poc/src/wire.rs` (17 tests rode
|
|
it; the shape is settled) with the POC-to-crate generalizations the ADRs
|
|
pin.
|
|
|
|
### API
|
|
|
|
```rust
|
|
pub const MAX_DATAGRAM_LEN: usize = u16::MAX as usize; // 65535
|
|
|
|
pub struct DatagramCodecError { .. } // thiserror: Oversize(usize), InvalidLength(...)
|
|
|
|
pub fn frame_datagram(payload: &[u8]) -> Result<Bytes, DatagramCodecError>
|
|
// [len: u16 BE][payload]; len=0 is a legal empty datagram; >65535 = Oversize at frame time
|
|
|
|
pub struct DatagramReader { /* incremental decoder state */ }
|
|
impl DatagramReader {
|
|
pub fn new() -> Self
|
|
pub fn feed(&mut self, chunk: &[u8]) -> Result<Vec<Bytes>, DatagramCodecError>
|
|
// zero or more complete datagrams per chunk; buffers partial frames
|
|
// across chunk boundaries
|
|
}
|
|
```
|
|
|
|
### The invariants the tests MUST pin (all POC-validated; they are the
|
|
spec's executable form)
|
|
|
|
1. Single datagram round-trip (frame → feed → exact bytes out).
|
|
2. Empty datagram (`len=0`): survives as a real datagram — NEVER
|
|
confused with EOF (the F-2 invariant; the codec layer never emits a
|
|
zero-length read).
|
|
3. Split across chunks (feed a frame in awkward 7-byte chunks; exact
|
|
reassembly).
|
|
4. Two datagrams batched in one chunk (feed once, two out, in order).
|
|
5. Partial header at a chunk boundary (1-byte `len` prefix split).
|
|
6. Mid-datagram state observable (incremental decode correctness).
|
|
7. Oversize rejected at frame time (never a wire overflow).
|
|
8. Truncation fail-loud (OQ-TN-13): the adapter-level receive that
|
|
would truncate surfaces as an error — test at the codec boundary by
|
|
asserting `frame_datagram` + reader round-trip with a buffer
|
|
smaller than a full datagram is not silently accepted (the concrete
|
|
API shape lands with `tunnels/local-socket-halves`; here, pin the
|
|
codec-side invariant: a truncated stream yields an error, not a
|
|
partial datagram).
|
|
|
|
No `stream_type` byte, no 5-byte header — a tunnel has one data stream
|
|
per direction (ADR-003). No EOF sentinel in the codec — EOF is the
|
|
channels-level `length=0` chunk, a different layer (the two coexist;
|
|
the POC proved no collision).
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] All 8 test families above pass (the POC's 7 + the truncation pin)
|
|
- [ ] `frame_datagram` returns `Bytes` (zero-copy handoff to the mux)
|
|
- [ ] `DatagramReader` state is incremental across arbitrary chunk
|
|
boundaries
|
|
- [ ] `cargo clippy --all-targets -- -D warnings`, `cargo fmt --check`
|
|
clean
|
|
- [ ] wasm32 check passes (the codec is pure byte work — it must be
|
|
wasm-clean)
|
|
|
|
## References
|
|
|
|
- docs/architecture/decisions/003-codec-and-udp-framing.md
|
|
- docs/architecture/bast.md (the binary contract)
|
|
- docs/architecture/wire.md §The Data Plane (normative byte diagrams)
|
|
- POC reference: `/workspace/alktunnels-udp-poc/src/wire.rs` (port with
|
|
the crate's doc-comment style)
|
|
|
|
## Notes
|
|
|
|
> Agent fills during implementation.
|
|
|
|
## Summary
|
|
|
|
> Agent fills this on completion. |