---
status: draft
last_updated: 2026-09-24 (the phase lifetimes' timeout posture decided:
teardown-governed, no protocol-layer idle bound, ADR-014; Phase 1
initial draft 2026-09-20; the POC-validated wire shapes promoted
into the normative spec)
---
# alksocks: Wire Format
The `alk/socks5` wire surface. Two layers: the **open op** (JSON
params on the channels call plane; trivial here, ADR-001) and the
**data plane** (the RFC 1928 conversation + the data streams inside
the channel `BiStream`). The channels layer strips its own 8-byte
header transparently (alknet ADR-093 / alkcall ADR-035); alksocks
owns everything inside the `BiStream`, which is, per the phase
model (ADR-003/ADR-007), the RFC conversation itself plus raw
pass-through, with exactly one framed stage (ASSOCIATE datagrams).
Design decisions live in the ADRs ([001](decisions/001-alpn-and-open-op.md),
[003](decisions/003-udp-handle-swap.md), [007](decisions/007-bind-in-base.md),
[011](decisions/011-inline-vendor.md), [013](decisions/013-targeted-fork.md),
[014](decisions/014-idle-timeout-posture.md)); this document is the normative
WHAT. RFC 1928's own wire rules (method negotiation, command encoding,
reply encoding, the RFC UDP datagram header) are specified by the RFC
itself; this document covers the channels-specific surface and the
phase model's stage boundaries.
## The Open Op (`channels/socks5/sub`)
`Sub`-typed operation (alkcall ADR-047): the reply carries
`{ "channel_id": <u32> }` once; everything else (the entire RFC 1928
conversation and the data plane) flows on the channel's `BiStream`,
never in the call response stream. ALPN marker `alk/socks5` (ADR-001).
### Input (params)
```json
{}
```
- Trivial: the SOCKS5 target is unknown at open time (it arrives
in-stream post-negotiation); the establisher is a session gate, not
a dial (POC #1's structural finding, ADR-004).
- Schema: `{type: object}` with `additionalProperties: false`. Empty
params stay valid forever; a future per-session option would be an
additive schema extension (ADR-001).
### Reply / errors
- Success: `{ "channel_id": <u32> }`: the establishment phase (the
session gate) succeeded, the open handler is running.
- Failure: a typed `channel:open_failed` call error with
`details: { reason, message }` where `reason ∈ dial_failed` /
`unknown_resource` / `resource_shortage` / `handler_error` /
`timeout` (alkcall ADR-049 §3). The registry's ACL gate runs
before the wrapper (`FORBIDDEN` for a scope-less identity;
POC #1). **A failed open never returns a `channel_id`**: no
phantom channel. Session-level refusal is always channels-level;
*target-level* refusal happens later, in-stream, as an RFC reply
code (ADR-004).
- The scope gate: `required_scopes = ["socks5:open"]`
(`SOCKS5_OPEN_SCOPE`, ADR-006). Caller identity resolves in the
alkcall CF-005 precedence order (payload `auth_token` >
`ServingConfig.identity` > transport identity); the establisher
and open handler receive the per-call opener identity (CF-006).
No extra reply fields in v1 (the session gate has nothing to
project; `with_reply_field` stays available additively).
## The Phase Model
RFC 1928 is one command per connection, and control and data never
interleave in either direction. The channel's `BiStream` therefore
has a **phase structure with no mode byte**: the reply itself
synchronizes the switch (POC #2 confirmed post-reply garbage is
refused structurally; the demux-vs-phase trade is resolved by
ADR-003/ADR-007):
| CONNECT | negotiate → command → reply | raw pass-through | none (0 B) |
| BIND | negotiate → command → reply#1 | quiet wait (no bytes allowed) → accept → reply#2, then pass-through | none after reply#2 |
| UDP ASSOCIATE | negotiate → command → reply (sentinel BND.ADDR) | datagram stage | `[len: u16 BE][addr + data]` per datagram |
- **Post-reply control bytes are protocol garbage.** CONNECT: the
stream is a pure byte pipe; any non-data interpretation is a
consumer violation. ASSOCIATE: 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`, POC
#2). BIND: any byte in the quiet wait ends the session with no
data plane (POC #5, the RFC 1928 §3 reading).
- **No in-band control vocabulary.** The alktunnels resolution
("no in-band control path, ever; the escape hatch is a new ALPN")
holds: no KEEPALIVE, no error frames, no flow-expiry frames. No
idle/inactivity vocabulary either: every phase's lifetime is
teardown-governed (EOF / garbage / error sentinels), never
protocol-layer timed (ADR-014; ADR-007 decided the BIND quiet
wait's ends the same way). A deployment enforces idle policy at
its edges, not in-band. Errors are EOF-shaped (channels-level) or
reply-code-shaped (in-stream, pre-data-plane).
- **One channel per SOCKS5 session** (no sub-demux, no flow key;
AGENTS.md convention 10; the ASSOCIATE handle swap makes the
channel the relay handle, ADR-003).
## The Data Plane
### CONNECT: raw pass-through
Post-reply, the handler runs `alkcall::channels::pump_bidi(channel_
bistream, target_read, target_write)` (ADR-050), the canonical
two-pump shape (alknet ADR-078); each pump shuts down the opposite
sink on completion (half-close semantics fall out); EOF sentinels
are the channels layer's. Zero protocol framing in-band: the RFC
conversation *is* the stream (POC #1: echo round-trips clean; the
front door adds no framing).
The dial seam (`DialFn`, ADR-004) is invoked at the command-read
interception point with the parsed target. Per-target refusal:
`reply_error` with the mapped RFC code (POC #1: dial refusal →
`ConnectionRefused` 0x05); no phantom data plane.
### UDP ASSOCIATE: the handle swap + framed datagram stage
The ASSOCIATE reply's `BND.ADDR`/`BND.PORT` is the sentinel
`127.0.0.1:0` on the in-band path (pure RFC-compatibility surface);
the channel is the relay handle (ADR-003). The datagram stage rides
the same channel:
- **Frame:** `[len: u16 BE][addr + data]` where `addr + data` is the
RFC address encoding (`TargetAddr::to_be_bytes()`: ATYP + addr +
port; the RFC UDP header minus RSV/FRAG). One frame per datagram,
both directions. **A zero-length payload is a legal empty datagram
(never EOF; the F-2 invariant, shaped on alktunnels ADR-003's
codec, re-implemented in first-party `src/wire.rs`); `len == 0`
(zero inner bytes) is unreachable from a compliant peer, since
`addr` is always ≥ 7 bytes, so the operative invariant lives at
payload level.** The length covers
`addr + data`, not data alone; the joint bound is the
constraint:** a frame is rejected (`Oversize`, at frame time)
whenever `len(addr) + len(data) > 65535`. The UDP payload bound
alone (65507) does *not* fit u16 unconditionally: a 65507-byte
datagram to a 255-character domain is 65507 + 259 (max domain-form
address: ATYP + length byte + 255 + port) = 65766 bytes of frame
payload, a legal RFC 1928 datagram that would overflow u16. The
joint rejection keeps the length field honest: max data is 65276
for domain-form destinations, 65516 for IPv6, 65528 for IPv4.
Implementations must not use unchecked u16 arithmetic on the
payload bound.
- **RSV/FRAG do not ride the tunnel wire**: fragmentation cannot be
expressed in-band; FRAG ≠ 0 is refused at front doors (the
iroh-socks5 v1 posture).
- **The RFC header codec (`new_udp_header`/`parse_udp_request`)
exists only at vanilla front-door boundaries** (ADR-003; POC #2
test 8: RFC datagram in, `{addr, data}` frames in-band, RFC
reply-header'd datagrams out, zero payload translation).
- **Association lifetime = channel lifetime.** Channel EOF (the
channels-level sentinel) ends the association; no extra control
vocabulary (POC #2 test 4: a fresh associate succeeds immediately
after a half-close teardown). No inactivity timer exists at the
protocol layer: every phase (the pre-command handshake, the BIND
quiet wait, the association) is teardown-governed, never
idle-expired (ADR-014); a deployment wanting an idle bound enforces
it outside the protocol layer (door accept paths, caller-side
wrappers).
- **The stage is `select!`-driven** (channel reads ∥ egress replies),
with the egress readiness contract: `next_reply` is `Pending` when
nothing is ready (an instantly-ready `Ok(None)` starves a biased
select into livelock; POC #2's load-bearing API finding).
**Framing is applied exactly once, by the wire layer:**
`Egress::next_reply` returns *inner* bytes (`addr + data`); the
frame writer adds the single length prefix (the double-framing bug
class POC #2 caught is an API-design invariant).
- **Producer egress** is the `EgressFactory` seam (ADR-004/ADR-008):
local-socket (one `UdpSocket` per association, per-datagram
`send_to`/`recv_from`, no flow table; replies attributed by the
sender's address per the RFC's per-datagram source semantics) or
composed (a lazy destination→direct-op-tunnel table, LRU-evicted;
open cost ~0.8 ms measured, per-target ACL for free).
**Per-datagram `send` is awaited inline** (the stage interleaves
sends with reply drains); a slow egress applies backpressure to
the association, not to other channels; the batch-2
composed-egress author inherits this bound knowingly.
### BIND: the phase model extended (ADR-007)
- Phase 1 ends at **reply#1 carrying `BND.ADDR`** (the accept
variant's real listener address; the sentinel on the wrapper-aware
in-band path).
- **The quiet wait**: no bytes are legal; the `select!` is
single-shot with exactly two exits: the one inbound accept (from
the `BindAcceptFactory` seam, whose future owns the listener), or
the control stream's EOF/garbage/error (the client-gone teardown
riding the accept future's drop).
- **reply#2 carries the peer address** (the real peer on both
non-sentinel variants: local is `accept()`'s peer, byte-exact;
composed is the forwarded op's `peer` param since the bind-first
graduation, alktunnels `docs/research/tunnels-graduation.md`;
sentinel `0.0.0.0:0` wrapper-aware).
- **Phase 2 is raw pass-through** (`pump_bidi`, the CONNECT shape)
between the channel and the accepted halves.
- Failure mapping is RFC-faithful: factory failure (pre-reply#1) →
reply#1 with the mapped code; accept-stage failure (post-reply#1)
→ reply#2 with the mapped code, no data plane (POC #5 test 6).
### Sentinels and lifecycle (all commands)
- **EOF** is the channels-level zero-length chunk, per-direction
(half-close); written by `pump_bidi`'s shutdown-on-completion or
teardown. CONNECT/BIND data planes end on EOF; the ASSOCIATE
association ends on EOF.
- **No mid-stream control frames** in any phase (the phase model's
whole point); pump-phase failures are EOF-shaped (alkcall
ADR-049 §6).
- **BAST:** the ASSOCIATE datagram frame is the one binary framing
beyond pass-through; its BAST document is [bast.md](bast.md).
## Normative byte diagrams
CONNECT (post-reply, one direction's view inside the channel
`BiStream`, after the channels layer's 8-byte header per chunk):
```
<payload bytes> ... <EOF sentinel: channels-level length=0 chunk>
```
UDP ASSOCIATE (the datagram stage, one direction's view):
```
[len:u16 BE][ATYP + addr + port + data] [len:u16 BE][...] ...
zero-length data: an empty datagram (legal payload, NOT EOF;
the F-2 invariant at payload level)
len == 0 (no addr bytes): unreachable from a compliant peer
EOF: the channels-level sentinel, outside the codec
```
BIND (the phase sequence, one channel's view):
```
<negotiation> <BIND cmd> |
```
## Open Questions
Open questions are tracked in [open-questions.md](open-questions.md).
None currently open against this document: the datagram framing
(the one-way door) is decided (ADR-003); the phase lifetimes'
timeout posture is decided (ADR-014: teardown-governed, no
protocol-layer idle bound); OQ-SK2-07 (the virtual-subnet
translation layer) rides the dial callback and does not touch this
surface.
## References
- ADR-001 (op/params), ADR-003 (the handle swap + frame),
ADR-004 (the seams + phase-model refusal paths), ADR-007 (BIND),
ADR-011 (the forked codecs), ADR-014 (the teardown-governed
phase lifetimes; no protocol-layer idle timeout)
- POC findings: `poc-connect-wasm-findings.md` (CONNECT pass-through,
refusal mapping), `poc-udp-associate-findings.md` (the stage,
readiness contract, framing-once invariant, association lifetime),
`poc-bind-findings.md` (the BIND phases, quiet-wait semantics,
failure mapping)
- Upstream: alkcall ADR-035 (channels pure multiplexing), ADR-037
(channel open), ADR-049 (establishment/typed errors), ADR-050
(`pump_bidi`); alktunnels ADR-003 (the length codec + F-2)
- RFC 1928 (the protocol's own wire rules), iroh-socks5 eval
(`docs/research/iroh-socks5-eval.md`, the frame prior art)