alksocks/docs/research/poc-udp-associate-findings.md

status, last_updated

status	last_updated
complete	2026-09-14

alksocks POC findings — channels-native UDP ASSOCIATE

POC #2 from phase-0 §OQ-SK-07, run 2026-09-14. Crate: alksocks-udp-poc (standalone, /workspace/alksocks-udp-poc/), against alkcall 0.7.1 (crates.io), alktunnels 0.1.0 (crates.io, local feature), fast-socks5 1.0.0 (crates.io). 11 tests, all pass; cargo clippy --all-targets -- -D warnings and cargo fmt --check clean.

Validates OQ-SK-03's design baseline (the handle swap, settled 2026-09-13): one channel per association; [len: u16 BE][addr + data] frames in-band; channel EOF ends the association; the RFC UDP header codec lives only at vanilla-client front doors. Both producer egress variants are implemented behind the egress callback, and the composed variant's per-destination open cost is measured.

What was validated

1. The handle-swap data plane — confirmed end to end. The ASSOCIATE conversation and the datagram stage ride the same channel BiStream. The producer drives the typestate directly (accept_no_auth → read_command → reply_success(sentinel)) — run_udp_proxy_custom is not used (its unconditional udp_bind_random_port makes it unusable on channels, per the corrected §Prior art caveat; driving the typestate directly is the workaround the upstream ask would retire).
2. The in-band frame codec — confirmed. The wire is alktunnels' boundary-preserving length codec (frame_datagram/DatagramReader — empty payload legal, never EOF; frames split/batch across channel chunks transparently) over the RFC address encoding (TargetAddr::to_be_bytes() — ATYP + addr + port). RSV/FRAG do not ride the tunnel wire: fragmentation cannot even be expressed in-band; it is refused at front doors (FRAG ≠ 0 → refuse, the iroh-socks5 v1 posture). The RFC-header codecs (new_udp_header/parse_udp_request) are used only at the front-door boundary, exactly as the baseline specifies.
3. Per-datagram addressing, no flow table — confirmed. One relay loop per association; each frame carries its destination; the local-egress variant relays through one real UdpSocket with per-datagram send_to/recv_from (iroh-socks5's cut). Five in-order datagrams round-trip over one association (udp_multiple_datagrams_one_association).
4. Association lifetime = channel lifetime — confirmed. The consumer's shutdown() half-closes the stream; the mux's implicit-EOF sentinel (REQ-CH-01) reaches the producer's stage read as EOF; the stage exits and the connection stays healthy (a fresh associate succeeds immediately after). No extra control vocabulary needed — the channels-level EOF is the association's end-of-life signal, as the iroh-socks5 eval predicted.
5. Control silence is structurally enforced — confirmed. The frame's first byte is ATYP, so any post-reply control byte parses as a garbage ATYP and fails the association loud (udp_undecodable_frame_ends_association, with the unassigned ATYP 0x7F). The phase model needs no explicit mode byte: the reply itself synchronizes the mode switch.
6. Both egress variants — implemented and passing.
   • Local egress (LocalEgress): one real UDP socket per association; per-datagram addressing; no flow table. Domain-form destinations resolve at the egress (producer-side DNS — the ssh -D semantic, POC-resolved as "the egress owns resolution").
   • Composed egress (ComposedEgress): a lazy destination→alktunnels-udp-tunnel table (each new destination opens one alk/tunnel channel with substrate: udp), LRU-evicted at a cap; a relay task per tunnel drains replies into the association's shared inbound queue. Per-target ACL comes free (the tunnel resource's ACL governs each destination's egress). The full stack round-trips: SOCKS5 consumer → SOCKS5 producer → composed egress → alk/tunnel channel → tunnel producer → local UDP echo (udp_composed_egress_round_trip).
7. The open-cost measurement (the empirical OQ-SK-03 input). Per-destination tunnel open, N=20 fresh associations, in-process loopback transport: mean ≈ 810–825 µs, min ≈ 765–800 µs, p95 ≤ ~1.0 ms (three runs: 825/807/819 µs mean). Sub-millisecond; comfortable for DNS + browsing. The 256-channel default cap (ADR-040/041, configurable) bounds any single association's destination fan-out; the wire space itself is u32. The LRU cap + the dedup assertion (open_count == 1 for repeated same-resource destinations) are pinned by udp_composed_egress_lazy_table_lru_and_open_cost.
8. The front door — RFC codec composition at the vanilla boundary, confirmed. An in-process bridge exposes the association on a real UDP socket; the door's pump decodes RFC-header'd datagrams (parse_udp_request), sends {addr, data} frames in-band, and returns replies RFC-header'd (new_udp_header). An RFC datagram (the shape curl/tun2proxy present) round-trips through the door (udp_front_door_vanilla_client_round_trip). The full raw-pipe + reply-rewrite control door is the crate's component-2 assembly shape (the CONNECT front door in POC #1 already validated that pipe shape); this test pins the UDP-specific claim: RFC codec at the door, frames in-band, zero payload translation.
9. CONNECT on the same registration — regression-guarded. One ALPN (alk/socks5), one op (channels/socks5/sub), trivial params; the CONNECT path is the POC #1 data plane unchanged (connect_still_served_on_the_same_registration).
10. The identity-seam wiring requirement re-confirmed for the composed path: the tunnel producer's channel-0 accept hook must set the opener identity (set_identity), or scope-gated tunnel opens fail closed with FORBIDDEN "authentication required" — the same POC #1 finding, now witnessed from the consumer side of the composed stack.

Structural findings (the load-bearing discoveries)

The datagram stage is select!-driven, and the egress reply future's readiness contract is load-bearing. The stage runs channel reads and the egress's reply stream concurrently (tokio::select!). Three readiness hazards were hit and fixed in this POC — all of them generalizable API-design notes for the crate's Phase 1:

1. The poll-then-block window loses replies. The first iteration interleaved "drain egress replies (non-blocking), then block on the channel read" — the echo's reply arriving during the channel block was never picked up. The fix is the concurrent select shape, which is also the honest full-duplex shape (an egress may produce unsolicited inbound datagrams at any time).
2. An instantly-ready Ok(None) starves the other branch with biased. A next_reply that returns Ok(None) immediately (drained) makes the biased select take it every iteration — a livelock that starves the mux/demux on a current-thread runtime. The egress contract is therefore: next_reply must be Pending when no reply is ready (Ok(None) is a spurious wakeup, not a hot loop). The LocalEgress parks on readable() — note writable() is the wrong readiness for UDP (always ready, the send-readiness, spins forever); readable() is the datagram-arrival readiness. The ComposedEgress parks on the shared inbound queue's recv(); a closed queue (all relay tasks gone) must end the association (an error), never spin.
3. The length framing is applied exactly once, by the wire layer. Egress::next_reply returns the inner bytes (addr + data); the producer's write_frame adds the single length prefix. (The first iteration framed in the egress and prefixed in the producer — double framing; the client parsed the length field as ATYP 0x00.)

Double framing is the one wire bug the POC caught, and it localizes a Phase 1 API decision: the egress (dial-callback) layer speaks inner bytes; the length codec is the wire layer's. The consumer side mirrors it: UdpAssociation::send_datagram frames once, its DatagramReader state (mid-frame position + batched-datagram pending queue) persists across recv_datagram calls — a datagram split across channel chunks survives a caller-driven receive loop (the first cut dropped the reader state per call; the echo test's 2-byte-prefix chunks exposed it).

The per-association egress instance. EgressFactory is called once per ASSOCIATE; the datagram stage owns the egress; stage exit drops it (composed tunnels' write halves EOF their channels; the adopted channel entries are reaped by the sessions' Drop, alktunnels ADR-005). One structural bug here: the first cut bound the opened session to a local let _session = ... binding, which dropped at the end of the insert block — tearing the channel down at birth (the relay task saw EOF instantly). The session must live inside the table entry. The crate's Phase 1 equivalent: the egress owns its tunnels end-to-end, and the compiler should enforce it (no _ bindings).

Wire/API notes for the wrapper

• TargetAddr::to_be_bytes() is the in-band address encoding (ATYP + addr + port) — the RFC UDP header minus RSV/FRAG. unframe decodes it by hand (synchronously over a borrowed slice); fast_socks5::util::target_addr::read_address is the async in-stream equivalent. frame/inner/unframe in the POC's datagram.rs are the Phase 1 codec's direct sketch.
• alktunnels::wire::frame_datagram/DatagramReader are the length codec, reused unchanged — the shared framing story with alktunnels' udp substrate (per the user's codec decision: depend on alktunnels, do not hand-roll).
• The ASSOCIATE reply's BND.ADDR is the sentinel 127.0.0.1:0 on the channels path (the handle is the channel; the address is pure RFC-compatibility surface). The consumer session receives it (relay_addr) and never uses it for addressing. Only the front door has a real address to report.
• LocalEgress::next_reply frames replies with the sender's address (the RFC's per-datagram source semantics, recv_from's from) — not the original destination. For echo targets the two coincide; a real producer would attribute by egress socket (the composed variant's table entry carries the destination explicitly — its replies are attributed correctly by construction).
• The composed egress's per-destination attribution: the table's reply_addr is recorded at tunnel-open time (the datagram's original destination) — the tunnel IS the per-destination association, the eval's noted advantage of the composed shape.
• parse_udp_request is async (though it completes immediately over a borrowed slice); a sync mirror (unframe) is used where the decode must not be async. Phase 1 may want an upstream ask: sync pure address-decode helpers (the codec is pure; only its signature is async).

OQ status after this POC

• OQ-SK-03 (UDP ASSOCIATE): the handle-swap baseline is POC-validated end to end — one channel per association, {addr, data} frames in-band (RSV/FRAG only at front doors), channel EOF = association lifetime, per-datagram addressing without a producer flow table. The datagram framing is wire-stable once published — the Phase 1 ADR has empirical ground under it. The demux-vs-phase question (the one-way-door extensibility argument) stays an ADR decision for Phase 1 with the first consumer in sight, but the POC adds evidence for the phase model: no in-band control vocabulary was needed, and post-reply garbage is refused structurally.
• OQ-SK-01 (dial policy): the egress seam is the dial-callback shape extended to the datagram stage (EgressFactory — the DialFn analogue). Both egress variants behind the callback, the protocol layer sees neither — the no-trait, boxed-halves precedent now holds for the datagram plane too.
• OQ-SK-05 (target policy): the composed egress's per-target-ACL- for-free claim is validated (each destination rides its own tunnel channel, governed by the tunnel resource's ACL). The egress-owns-DNS resolution posture is POC-resolved for the local variant.
• OQ-SK-07: #1, #2, #4 complete; #3 (noq AsyncUdpSocket) remains.

POC placement

Standalone crate (global workspace, /workspace/alksocks-udp-poc/) per the placement conventions — it composes three published crates (alkcall 0.7.1, alktunnels 0.1.0, fast-socks5 1.0.0) and needs no code from this repo. Findings land here; the crate is the artifact.