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:
2026-09-06 06:43:53 +00:00
parent 4df3c618d4
commit 069350bd51
+54 -25
View File
@@ -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