From 069350bd51be88f8549eb0cd7ca0fe1eeef263b4 Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Sun, 6 Sep 2026 06:43:53 +0000 Subject: [PATCH] docs: reframe OQ-TN-01 as resource identification, not addressing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four corrections from discussion: - ALPN prefix: alknet/ -> alk/ swap happened in alkcall v0.1.1; docs must not perpetuate the old prefix (consumers would bake it in) - XY problem: except in the -D/dynamic composition case, params only identify a produced resource + substrate discriminator (tcp/udp/ extensible); the producer owns where the resource comes from (most likely a local port); UDP must be structurally supported even though TCP dominates expected use - self-contained JSON open-op object accepted as the params path (alktty NegotiateRequest precedent) - russh has no UDP channel support at all — no direct-udp prior art; noted in OQ-TN-02 and the survey list; SOCKS5 relevance scoped to the -D composition path Residue for OQ-TN-01: resource naming shape, discovery mechanism, exact JSON layout (Phase 1 ADR before first consumer). --- docs/research/phase-0-findings.md | 79 +++++++++++++++++++++---------- 1 file changed, 54 insertions(+), 25 deletions(-) diff --git a/docs/research/phase-0-findings.md b/docs/research/phase-0-findings.md index 0953834..ba53ca2 100644 --- a/docs/research/phase-0-findings.md +++ b/docs/research/phase-0-findings.md @@ -199,8 +199,8 @@ addressing scheme was never decided. It must cover at minimum: - TCP dial (`host:port`) - UDP (associate-style or endpoint-style — see OQ-TN-02) - Unix domain sockets (path) -- Direction (who dials the target — see OQ-TN-03) -- Bind/listen vs dial semantics (see OQ-TN-04) +- Direction (who dials the target — see OQ-TN-03, resolved) +- Bind/listen vs dial semantics (see OQ-TN-04, mostly resolved) Considerations: @@ -212,23 +212,45 @@ Considerations: door). It must be substrate-extensible without format changes (a new substrate should be an additive `scheme` value, not a v2 format). - Prior art to survey: SSH forwarding models (`direct-tcpip`, - `forwarded-tcpip`, `direct-udpip` in some implementations), SOCKS5 - addressing (ATYP + addr + port — supports v4/v6/domain + UDP associate), - iroh/tun2proxy target encoding, quinn-proxy-poc. + `forwarded-tcpip`), SOCKS5 addressing (ATYP + addr + port), russh + (`/workspace/russh` — note: russh has no UDP channel type at all, so + there is no `direct-udp`-style prior art there; still useful for + channel-open framing and addressing-intel generally). +- ALPN convention check (2026-09-05): the ALPN prefix swap `alknet/` → + `alk/` happened alkcall v0.1.1, before the first published consumer. + Everything in this crate's docs referencing `alknet/tunnel` means + `alk/tunnel` — a small thing, but docs/ADRs must not perpetuate the + old prefix or consumers will bake it in. -**Status:** open — research needed. Half-answer (hunch): a scheme-tagged -JSON object rather than a URL-ish string, so params stay typed and -extensible; exact shape TBD. Strengthened 2026-09-05: the tun2proxy UDP -gateway (§Prior art) validates SOCKS5 ATYP addressing (v4/v6/domain) as -in-band prior art, and surfaces a fork — for UDP, remote addressing is -per-datagram (SOCKS5-style) rather than fixed-at-open like TCP. The -params design must account for both modes. Reframed 2026-09-05 by the -hub model (§Prior art: the hub-owns-the-connection model): `params` -names a *produced resource* (an ACL-scoped virtual resource), not a -raw socket spec — so the design must also decide resource naming -(stable names vs target addresses) and discovery (call-level listing -op vs out-of-band config). SOCKS5 ATYP remains the in-band transport -encoding candidate underneath the resource naming. +**Reframe 2026-09-05 — this is partly an XY problem.** The rich +"remote addressing" framing was chasing the wrong thing. Except in the +`-D`/dynamic case (which composes at the assembly layer), a tunnel is +either TCP or UDP, and `params` need only *identify a produced +resource* — not carry a general-purpose address. The producer owns +where the resource comes from (a local port, a docker container's +port, an in-process service, a unix socket — its problem, most likely +a local port). So `params` reduce to: + +1. Which resource (a produced resource identifier — stable name or + target address, still to decide), +2. Substrate discriminator (`tcp` / `udp` / extensible) — so UDP is + structurally supported from day one even if the vast majority of + use is TCP. + +Rich in-band addressing (SOCKS5 ATYP, per-datagram remote addresses) +enters only through the `-D`/dynamic-target composition path +(OQ-TN-03/OQ-TN-08 residue), not through the base open-op params. + +**Status:** mostly resolved 2026-09-05 (pending the resource-naming +and discovery residue). Direction of travel: +- `params` = self-contained JSON object in the open op (alktty + `NegotiateRequest` precedent) — accepted path. +- `params` identify a produced resource + substrate discriminator; + producer owns the backing. No URL-style general addressing. +- Residue: stable resource name vs target address as the identifier + shape; discovery mechanism (call-level listing op vs out-of-band + config); exact JSON field layout (Phase 1 spec, ADR before first + consumer — wire-stable once published). ### OQ-TN-02: Datagram substrates (UDP) — boundary preservation @@ -241,7 +263,9 @@ re-chunked arbitrarily)? substrate (alknet ADR-071/093; the POC only exercised TCP). - SSH's `-D` UDP associate tunnels UDP as a stream with per-datagram framing re-added by the tunnel protocol (e.g. SOCKS5 UDP over TCP). - russh/openssh do this differently — survey needed. + Note (2026-09-05): russh does not support UDP channels at all — no + `direct-udp`-style prior art exists there; the tun2proxy gateway + (§Prior art) is the strongest framing precedent. - iroh and quinn-proxy-poc have native datagram transports; tun2proxy has a full UDP-over-TCP model worth reading. - Boundary preservation is a wire-format decision (per-datagram length @@ -499,10 +523,13 @@ Candidate reading for the research specialist (to be expanded): - SSH channel/forwarding model: RFC 4254 §7 (direct-tcpip / forwarded-tcpip), OpenSSH `-L`/`-R`/`-D` semantics, russh's - `ChannelOpen` framing (russh is already in `/workspace/russh`). + `ChannelOpen` framing (russh is already in `/workspace/russh`; + confirmed 2026-09-05: no UDP channel support at all — no UDP prior + art there, but useful for open-op framing intel). - SOCKS5 (RFC 1928): addressing (ATYP), UDP ASSOCIATE framing, per-endpoint multiplexing — the closest standardized "arbitrary - tunnel + UDP" model. + tunnel + UDP" model. Relevant to the `-D` composition path + (OQ-TN-03 residue), not the base open-op params (OQ-TN-01 reframe). - tun2proxy (`/workspace/tun2proxy`, `src/udpgw.rs`): UDP gateway over TCP — per-datagram length framing, SOCKS5 per-datagram addressing, CONN_ID flow multiplexing, keepalive/ERR flag packets, MTU cap, @@ -525,10 +552,12 @@ Candidate reading for the research specialist (to be expanded): - [ ] Survey notes: SSH/SOCKS5/tun2proxy addressing + UDP framing (OQ-TN-01, OQ-TN-02) — tun2proxy UDP gateway done (§Prior art); SSH/SOCKS5 addressing survey still open -- [ ] Recommendation: addressing format sketch (OQ-TN-01) — SOCKS5 - ATYP validated as in-band encoding prior art; per-channel vs - per-datagram fork unresolved; resource naming + discovery now - in scope (hub model) +- [x] Reframe landed (OQ-TN-01) — params = self-contained JSON open-op + object identifying a produced resource + substrate + discriminator (`tcp`/`udp`/extensible); producer owns the + backing; no URL-style general addressing. Residue: resource + naming shape, discovery mechanism, exact JSON layout (Phase 1 + ADR) - [x] Direction model resolved (OQ-TN-03) — hub-owns-the-connection model: role follows the resource, no protocol-level direction; `-D` composes at the assembly layer