docs: UDP tunnel POC summary — shape validated end-to-end
17 tests pass (7 codec + 10 integration). The producer/consumer shape, ADR-049 establishment integration, codec decision, and typed establishment errors all validated over alkcall 0.5.0 channels. Key findings folded into the ledger: - OQ-TN-05 resolved for stream substrates: no backend trait — pump_halves generic over boxed halves (TCP into_split, UDP UdpHalf adapter); remaining thread is only the hub re-produce composition question - OQ-TN-06 convergence test satisfied: producer pump and consumer pump are the same shape modulo channel side; extraction decidable in Phase 1 - New finding for the alkcall ledger: OpenHandler JoinHandle semantics are load-bearing and undocumented — a handler that returns before the data plane starts tears the channel down at birth (the POC found this by hanging; the pump must be awaited inline). Plus: Establishment should carry the channel plan (the reserved extension point) to kill the establisher handoff side-channel - UdpHalf truncation semantics flagged for the Phase 1 ADR (recommend fail-loud over silent truncation) POC crate: /workspace/alktunnels-udp-poc (db224cc).
This commit is contained in:
@@ -512,12 +512,15 @@ so the question:
|
||||
surface as-is? If a helper is warranted, it may share shape with the
|
||||
substrate dial/listen trait — which would argue for the trait.
|
||||
|
||||
**Status:** open — needs a survey of what backends would actually
|
||||
implement (local TCP? docker exec? ssh -w?) before deciding trait vs
|
||||
no-trait. Half-answer (hunch): a thin trait (or just a fn alias) for
|
||||
"obtain a bidirectional substrate stream for a target," possibly no
|
||||
trait at all if the only meaningful backends are local sockets — decide
|
||||
after surveying candidate backends.
|
||||
**Status: resolved for stream substrates, 2026-09-06 (POC).**
|
||||
`pump_halves` is generic over `(AsyncRead, AsyncWrite)` halves — TCP
|
||||
contributes `into_split()` halves, UDP contributes the `UdpHalf`
|
||||
socket adapter, the pump never knows which. "Produce boxed halves for
|
||||
a resource" is a function, not a trait; the `TunnelBackend` trait
|
||||
question resolves to *no trait* for substrate access. The only
|
||||
remaining thread is the hub re-produce composition question (above) —
|
||||
a Phase 1 spec question, and now decidable against the validated
|
||||
producer/consumer surface.
|
||||
|
||||
### OQ-TN-06: The two-pump helper — extract now?
|
||||
|
||||
@@ -539,6 +542,13 @@ consumer (POC tunnel was the first; SSH `direct-tcpip` would be a third).
|
||||
not a blocker for the spec. Half-answer: the helper probably belongs
|
||||
upstream (alkcall, near the channels-adapter handler-integration
|
||||
conventions) but only if the two shapes genuinely converge.
|
||||
**Convergence input 2026-09-06 (POC):** the producer pump
|
||||
(`pump_halves`) and the consumer pump (`take_halves` + copy) are the
|
||||
same shape modulo channel side — the ADR-078 convergence test is
|
||||
satisfied; extraction is decidable in Phase 1. Also surfaced by the
|
||||
POC: the `OpenHandler` JoinHandle semantics (see `poc-summary.md` §
|
||||
Issues Surfaced #1) are where such a helper would pin the teardown
|
||||
contract.
|
||||
|
||||
### OQ-TN-07: ALPN strategy
|
||||
|
||||
@@ -707,6 +717,10 @@ Phase 0 may need (in rough priority order, per the SDD process's
|
||||
fit: chunk-size vs datagram-size interaction, MTU cap against the
|
||||
channels bounded buffers, idle-expiry mapping, and the chosen
|
||||
endpoint-addressing shape. Derisks OQ-TN-02 (and OQ-TN-07's option B).
|
||||
|
||||
**Done 2026-09-06** — see `poc-summary.md`. 17 tests pass; the
|
||||
producer/consumer shape validated end-to-end over alkcall 0.5.0
|
||||
(establisher + two-pump + codec + typed establishment errors).
|
||||
2. **Reverse-flow POC** — `-R`-style: the accept side listens, the far
|
||||
side carries. Derisks OQ-TN-03's advertisement/lifecycle shape.
|
||||
Template available: SSH's `tcpip-forward` global-request
|
||||
@@ -807,7 +821,18 @@ Candidate reading for the research specialist (to be expanded):
|
||||
OQ-TN-05 trait shape
|
||||
- [ ] Decision input: backend trait vs no-trait (OQ-TN-05), now
|
||||
including the hub re-produce composition question
|
||||
- [ ] Targeted POC(s) run + summary (OQ-TN-10) — UDP first, reverse
|
||||
flow second
|
||||
- [ ] Targeted POC(s) run + summary (OQ-TN-10) — UDP POC DONE
|
||||
(2026-09-06, `poc-summary.md`); reverse-flow POC remains
|
||||
- [x] Two-pump helper convergence input gathered (OQ-TN-06) — the POC
|
||||
gives both shapes (producer `pump_halves`, consumer
|
||||
`take_halves` + copy): same shape modulo channel side; the
|
||||
alknet ADR-078 convergence test is satisfied, extraction now
|
||||
decidable in Phase 1
|
||||
- [x] OQ-TN-05 executable input (backend trait vs no-trait) — POC
|
||||
confirms stream substrates need no trait: `pump_halves` is
|
||||
generic over boxed halves (TCP `into_split`, UDP `UdpHalf`
|
||||
adapter); "produce halves for a resource" is a function. The
|
||||
hub re-produce composition question is the only remaining
|
||||
OQ-TN-05 thread
|
||||
- [ ] Open questions promoted to Phase 1
|
||||
`docs/architecture/open-questions.md` with statuses
|
||||
Reference in New Issue
Block a user