alksocks/docs/architecture/consumer.md

---

status: draft last_updated: 2026-09-25 (the cred-bearing door's call-connection contract reconciled — TokenClient's door-only posture, one command per accepted connection; the BIND spent posture reconciled — the take-guarded reply#2 reader, review 002 C-1/D-1; the landed session signatures reconciled 2026-09-24; Phase 1 initial draft 2026-09-20)

alksocks — The Consumer Half

The consumer opens SOCKS5 channels against a produced service and speaks RFC 1928 inside them. Two consumption shapes, structurally separate (the Phase 0 scope resolution):

1. The channels-native session — a typed client that opens channels/socks5/sub and drives the RFC conversation in-stream (wrapper-aware; the POC #1 use_stream / POC #2 associate session shapes).
2. The front door (optional, feature local) — a real local endpoint (TCP for CONNECT/BIND; UDP for ASSOCIATE) that vanilla clients point at; the door bridges each accepted connection/socket onto a channel, with the RFC codec living only at that boundary.

Both wrap the same protocol layer; neither is required by the other.

The Channels-Native Sessions

Socks5ChannelSession (CONNECT)

Opens channels/socks5/sub via ChannelClient::open_channel (alkcall ADR-037/043), then drives the client side of the RFC conversation in-stream over the channel's BiStream:

• the forked client typestate's use_stream path — generic over the backing stream (POC #1: Socks5Stream impls AsyncRead + AsyncWrite itself, so the session over a BiStream is the intended use, not a hack);
• target construction via ToTargetAddr (IP-string forms parse to IP targets; domain form passes through unresolved — ADR-012);
• after the reply, the session is a raw byte pipe — the consumer reads/writes payload bytes directly (0 B framing, CONNECT).

The associate session

The UDP ASSOCIATE client (POC #2's shape):

• opens the channel, negotiates, sends ASSOCIATE, reads the reply — receives the sentinel BND.ADDR and never uses it for addressing (the handle is the channel; ADR-003);
• send_datagram(dst, bytes) frames once ([len: u16 BE][addr + data], the RFC 1928 address encoding) and writes the frame;
• recv_datagram() returns Some((source_addr, bytes)) per datagram — its incremental reader state (mid-frame position + batched-datagram pending queue) persists across calls (a datagram split across channel chunks survives a caller-driven receive loop; POC #2's finding);
• shutdown() half-closes the stream — the mux's implicit-EOF sentinel reaches the producer's stage as EOF and the association ends (association lifetime = channel lifetime);
• teardown ownership: the session owns the channel; on Drop it closes/joins — the alktunnels ADR-005 posture (the consumer session type owns teardown), combined with ADR-004's ownership-rides-the-handle contract.

The BIND client

The BIND reply#2 reader (POC #5's read_reply2 sketch): the forked client request() reads reply#1; reply#2 is hand-read with the forked public read_address codec (reply#1's codec applied again; no second codec). The session then rides the pass-through data plane. The reply#2 phase is take-guarded: the one normative reader is await_inbound — the first read consumes the session's stream (the returned plane owns it; the session stays the teardown owner), so a second call returns the family's spent shape (Ok(None), the same posture the sibling sessions pin) and cannot re-read the live data plane; a failed read restores the inner (the producer ends the session on every post-reply#1 failure exit, so a re-call EOFs — never a live data-plane re-read either way). The reply1() handle is a view (the advertised BND.ADDR + the raw pre-reply#2 stream), not a reader. The BIND client is a wrapper-aware-consumer convenience — vanilla clients reach BIND through the front door instead.

Error surface

SocksServerError / SocksError (the forked surface) mapped faithfully; channel-open failures are the typed channel:open_failed reasons (alkcall ADR-049). A refused session never yields a phantom channel; a refused target is an RFC reply code surfaced through the session type.

The Front Doors (feature local, optional)

The consumer's optional local exposure — the ssh -D shape (POC #1: curl end-to-end; POC #2 test 8: the UDP door; POC #5 test 8: the BIND door):

• The CONNECT/BIND door: bind a real TCP listener; for each accepted connection, pipe it raw onto a channel BiStream (copy_bidirectional, zero protocol translation — POC #1's literal 0 B pass-through conclusion). The door's credential half (below) is the only RFC work it does.
• The UDP door: bind a real UDP socket; decode RFC-header'd datagrams (parse_udp_request), send {addr, data} frames in-band, return replies RFC-header'd (new_udp_header) — the RFC codec at the door boundary only (ADR-003). FRAG ≠ 0 → refuse (the v1 posture).
• The BIND door's reply#2 fidelity: the local variant's real listener/peer addresses pass through the pipe unchanged (the conversation is the vanilla client's own); the door adds nothing.

Door variants and auth (ADR-005)

• The NoAuth door (POC #1's raw-pipe shape): zero protocol translation; for loopback-only or wrapper-aware use.
• The cred-bearing door (RFC 1929): a vanilla client carrying user:pass gets a real RFC 1929 conversation at the door; the door maps the accepted credential to local configuration — which channel identity/endpoint to open the producer channel with — via a static config table (ADR-005: user:pass → channel identity/endpoint selection). The SOCKS password never crosses the channel as a SOCKS password; the channel identity never reaches the vanilla client. The door checks credentials itself (no forked AuthMethod impl needed — the door owns the accept loop). The mapped identity rides the open-op call's auth_token payload (CF-005 precedence (1)) via TokenClient::wrap — the client's channel-0 CallConnection is taken once per door (the door-only contract: a cred-bearing door's client is a door client; other shapes — the UDP door's association, channels-native sessions — ride their own connections to the same producer registration, one registration, many connections). The vanilla conversation is one command per accepted connection (the door's RFC half consumes the greeting + one command; the data plane rides to EOF).

Door variant selection (NoAuth vs cred-bearing; the UDP door's bind address) is assembly-layer configuration.

Wiring (Assembly Layer)

let session = Socks5ChannelSession::connect(
    &channel_client, target).await?;
let (mut read, mut write) = session.split();   // post-reply payload pipe

let assoc = AssociateSession::associate(&channel_client).await?;
assoc.send_datagram(dst, &bytes).await?;       // frames once, ADR-003
let (src, bytes) = assoc.recv_datagram().await?.expect("a datagram");

let door = FrontDoor::builder()
    .credentials(cred_table)       // RFC 1929 mapping, ADR-005
    .bind("127.0.0.1:1080")
    .build();
door.serve(channel_client).await?;

The landed session signatures: the constructors take &ChannelClient (shared — many sessions ride one client, the concurrency posture); send_datagram takes impl ToTargetAddr (the CONNECT session's target-construction posture, ADR-012); recv_datagram() returns Result<Option<(TargetAddr, Bytes)>, SocksSessionError> — None is the channel EOF (the association's clean end), never an empty datagram (F-2: an empty payload is a legal datagram).

Design Decisions

ADR	Decision	Summary
001	ALPN + op	the consumer opens the one op
003	The associate session	sentinel BND.ADDR; frames once; reader state persists
004	Ownership rides the handle	handle payloads own channel sessions; the session-teardown posture is inherited from alktunnels ADR-005 (the consumer session type owns teardown)
005	Door auth	RFC 1929 at the door; static credential→identity mapping
007	BIND client	the reply#2 reader; vanilla clients via the door
011	The extraction	the client use_stream path in-tree
013	The targeted fork	the core is owned (src/rfc1928/)

Open Questions

Open questions are tracked in open-questions.md. None currently blocking this document.

References

• POC #1 (poc-connect-wasm-findings.md — the raw-pipe door, the use_stream fit), POC #2 (poc-udp-associate-findings.md — the associate session, the reader-state finding, the UDP door), POC #5 (poc-bind-findings.md — the reply#2 reader, the BIND door)
• Upstream: alkcall ADR-037/043 (channel open), alktunnels ADR-005 (consumer session owns teardown — the posture inherited), the CF-005/CF-006 seam
• producer.md (the other half), wire.md (the normative wire)