docs: reframe OQ-TN-01 as resource identification, not addressing
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).
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user