- frame(addr, payload): [len: u16 BE][addr + data] over
TargetAddr::to_be_bytes() + payload; the joint bound enforced at
frame time (checked_add; 65507 + 255-char domain = 65766 > 65535 →
Oversize) with addr_encoding_len exposed (7 v4 / 19 v6 / 259 max
domain) and MAX_INNER_LEN pinned
- DatagramReader: incremental reassembly across chunk boundaries
(split frames, batched frames, partial headers), infallible,
returning per-frame Results; the addr sub-layout decoded by hand
(ATYP-keyed, UTF-8-validated) with typed decode errors —
BadAtyp / ShortAddress / DomainNotUtf8 / EmptyFrame — so the
producer stage fails the association loud on protocol garbage
(udp_undecodable_frame_ends_association, POC #2)
- module docs state the framing-once invariant (the egress speaks
inner bytes; this layer owns the single length prefix — the
double-framing bug class POC #2 caught), the F-2 invariant at
payload level (a zero-length payload is a legal empty datagram,
never EOF; wire len == 0 is unreachable garbage), and the EOF
layering (the channels-level sentinel, outside the codec)
- doc-sync: wire.md + bast.md residue corrected — "len == 0 is a
legal empty datagram" replaced with the payload-level F-2
statement (len == 0 unreachable since addr >= 7 bytes)
- lib.rs re-exports frame, DatagramReader, addr_encoding_len,
MAX_INNER_LEN, WireError (convention 15)
Verification: cargo test (58 lib + 37 differential), clippy
--all-targets -- -D warnings, fmt --check, doc --no-deps, and both
wasm checks (check + clippy on wasm32-unknown-unknown) — all clean.
- Cargo.toml: alkcall = "0.8.0" (convention 11 — pinned, first
consumption of the 0.8.0 surface), serde/serde_json, bytes, and
the std-only futures subset (BoxFuture seam shape). tokio's
wasm-clean subset and the empty local/composed features unchanged.
- lib.rs: the six skeleton modules per overview.md §Module Map
(params, wire, producer, consumer, egress, error) — stub files
with module docs naming their filling tasks; no re-exports yet
(each implementation task adds its own).
Verified: cargo test (76 tests), clippy --all-targets -D warnings,
fmt --check, cargo doc --no-deps, both wasm checks
(check + clippy on wasm32-unknown-unknown), and the dep-graph
spot-checks (no mio/socket2/tokio::net in the default normal graph;
normal tokio features = bytes/io-util/macros/rt/sync/time only).
alkcall 0.8.0 from crates.io confirmed wasm-clean via probe build
before wiring.
Task: tasks/implementation/core-crate-deps.md (completed)
Batch 1 of the Phase 1 decomposition: the default, wasm-clean crate
(producer + consumer + wire + seams + params/errors), per the
architecture spec set (ADRs 001-013) and the three POCs' validated
shapes. The assembly layer (local/composed providers, front doors) is
batch 2, decomposed after review-protocol-core opens.
- foundation: crate-deps (alkcall 0.8.0 first consumption), wire-codec
(the ASSOCIATE frame + the joint bound), seam-types (the three
ADR-004 seams), params-errors (the one-way-door surface)
- harness: duplex transport + identities + in-process seams (the
alkcall 0.8.0 establishment surface proven before the producer)
- verticals: producer/consumer splits per command (CONNECT,
ASSOCIATE, BIND) — each POC's scope, producer tasks test via the
raw RFC client, consumer tasks e2e through the harness
- closing: integration suite (three-command regression, teardown
matrix, identity matrix, docs sync) + review-protocol-core (the
batch gate)
taskgraph: 8 generations, no cycles, risk path 2.55 (no high-risk
tasks). Also records the wire.md/bast.md len=0 residue (payload-level
F-2 is the operative invariant) as a doc-sync deliverable of the
wire-codec task.
Verification: cargo test (76 passed), fmt clean; taskgraph
validate/cycles/parallel/critical clean.
Security + code-smell + coverage review of the targeted fork as owned
code (the extraction review was narrow; this is the full pass).
Findings: 1 major (F-1: reply_success/reply_error write replies with
.write() — a partial-write hazard invisible to clippy's
unused_io_amount under the err_when-chaining idiom, executable-probe
verified; rfc1928.md's write_all rationale is false for these sites),
7 minors (2 security-posture notes, 2 extraction leftovers, 3
coverage gaps), 4 observations. No critical findings.
Verification: 38+32 tests, clippy (all-targets + wasm32) -D warnings,
fmt, doc, wasm check, publish dry-run, MSRV 1.88 native+wasm — all
green. Coverage 92.63% regions / 95.40% lines (cargo-llvm-cov); gaps
attributed per finding. Differential suite's 15 upstream citations
spot-checked against the v1.0.0 reference checkout — all accurate.
The mechanical half of the posture change: src/vendor/ ->
src/rfc1928/ (module alksocks::rfc1928), tests/vendor-differential.rs
-> tests/rfc1928-differential.rs (git mv — history preserved).
- Fork point pinned: the tree as of 5b18d4d (the extraction review's
gate commit); provenance permanent in the module docs and the
extended LICENSE notice (upstream MIT preserved, fork-point +
post-fork modification statement added — extend, never replace)
- The lint-allow posture dissolved: all module-level #[allow]s
removed and the suppressed smells fixed (u8::max_value() ->
u8::MAX, needless lifetimes elided, match_like_matches_macro
applied, io::Error::new(Other) -> io::Error::other, the
AuthMethod::new self-taking signature renamed
into_starting_state, the F-4 ToSocketAddrs string re-worded — it
no longer names the cut resolve_dns(), the unused ready! macro
and dead AuthenticationMethod::from_u8 removed, the upstream
commented-out async-std note folded into the impl doc)
- Module docs rewritten: ownership statement (project conventions
apply unconditionally), extraction provenance (ADR-011) +
ownership (ADR-013) + maintenance posture (behavioral reference,
hand-port path)
- Differential suite survives the rename untouched (32 tests pin
bytes, not upstream text)
Verification: cargo test (38+32 green), cargo clippy --all-targets
-D warnings, cargo fmt --check, cargo check/clippy
--target wasm32-unknown-unknown, cargo test --all-features, cargo
doc --no-deps — all pass.
The extraction review against vendor.md's cut table, ADR-011
§Amendment, and AGENTS.md conventions. All five file diffs vs the
fast-socks5 v1.0.0 reference checkout read hunk-by-hunk and
categorized (cut / carried changes / adjustments / provenance /
tests); wasm, clippy, fmt, doc all green; RFC 1928 spot-checks
(reply form, method order, UDP zero fallback, domain cap, FRAG
split) independently verified against the RFC text.
F-1 (critical, resolved here): ReplyError::from_u8 kept upstream's
unreachable!("ReplyError code unsupported.") arm while being
wire-reachable — Socks5Stream::read_request_reply feeds the raw
reply byte from the wire into it, and RFC 1928 §6 marks 0x09-0xFF
unassigned, so a misbehaving peer would panic the consumer task.
Unassigned codes now map to GeneralFailure (the RFC's catch-all),
pinned by a new test, and the panic-translation adjustment is
recorded in vendor.md's adjustment list (with the Config-Default
and write_all notes) in the same change.
Findings F-2..F-4 (dead commented code dropped with its region;
Cargo.toml feature-layout comments; the preserved resolve_dns error
string) reviewed and accepted. Review task file carries the full
record; the gate to the downstream task groups is open.
Verified: cargo test (38 + 32), cargo test --all-features, clippy
--all-targets and --target wasm32-unknown-unknown (-D warnings),
cargo check --target wasm32-unknown-unknown, cargo fmt --check,
cargo doc --no-deps.
Extract the T-generic client session from fast-socks5 v1.0.0's
client.rs into src/vendor/client.rs (ADR-011 §Amendment extraction,
vendor.md cut table row 2): Socks5Stream<S> with use_stream (the
greeting, method-choice read, password sub-handshake, request
encoder, reply reader, socket accessors), the AsyncRead/AsyncWrite
impls, and the pruned Config (skip_auth only).
- typed MissingTargetAddr variant replaces upstream's
anyhow::Error::msg(...).into() at client.rs:285 (the one SocksError
addition; the client.rs:528 Other(anyhow!) site went with the cut
Socks5Datagram)
- use_password_auth's unreachable!() is an error return (upstream's
None-arm message; convention 2), and the sub-negotiation reply's
version byte is now checked (was only a dropped debug!)
- write -> write_all in request_header (clippy unused_io_amount;
byte-identical on a healthy stream)
- cut (not copied): Socks5Datagram, the Socks5Stream<TcpStream>
convenience impl (connect*/connect_raw), Config::connect_timeout
- 14 first-party duplex tests vs raw-byte mock servers (uncorrelated
from the vendored server typestate): both handshakes, 0xff
refusal, version mismatch, domain/IP request forms, the full
failure-code table, UDP-ASSOCIATE zero fallback, skip_auth,
io-impl copy, socket accessors
- mod.rs: doc touch-ups (client module now landed; fixed the
pre-existing broken intra-doc link)
Verification: cargo test (37 pass), --all-features, clippy
--all-targets -D warnings (native + wasm32), cargo check --target
wasm32-unknown-unknown, cargo fmt --check, cargo doc --no-deps.
Extract fast-socks5 v1.0.0's non-net lib.rs region into
src/vendor/mod.rs (scaffolding-pinned root; the task's lib.rs target
name corrected — a second root file would conflict, see task Notes):
consts, Socks5Command (as_u8/from_u8 made pub), AuthenticationMethod,
SocksError pruned to the extracted region's consumers (no anyhow/
Redaction/InvalidHeader/ReplySocks4Error/ArgumentInputError), the
Result alias, ReplyError codec, UdpHeaderError + new_udp_header/
parse_udp_request. util/target_addr.rs gains TargetAddr/AddrError
(minus resolve_dns + its two variants)/ToTargetAddr/Addr/read_address;
util/stream.rs gains the read_exact!/ready! macros (de-exported to
pub(crate) use) + ConnectError + to_reply_error. SocksServerError
lands verbatim in server.rs early — SocksError's #[from] needs it
before the typestate task. 16 first-party codec tests (round-trips,
mapping tables, garbage-RSV/unknown-ATYP); no sockets, no env_logger.
Newer-clippy style lints allowed at module level in vendored files
(verbatim diff posture, rationale recorded).
Verification: cargo test (16 pass) + --all-features; clippy
--all-targets -D warnings (native + wasm32); cargo check
--target wasm32-unknown-unknown; cargo fmt --check; cargo doc.
Negative sweeps: no anyhow/log/tokio::net/socket2/tokio-stream/
async-trait under src/vendor/; no #[macro_export]; resolve_dns and
the pruned error variants absent.
The inline vendor (vendor.md, ADR-011 §Amendment) is the root of the
crate's dependency graph; this decomposes it before any downstream
group (params/wire/producer/consumer/doors).
- vendor-crate-scaffolding: Cargo.toml (wasm-clean tokio subset, no
alkcall yet), lib.rs, vendor/ skeleton, bundled MIT notice
- vendor-wire-vocabulary: consts, codecs, errors, macros — with the
extraction-boundary pins (error-variant pruning, pub command
codecs, macro de-exporting)
- vendor-server-typestate: Socks5ServerProtocol + the new_reply
publication (carried change #2); BIND's driving is producer-group
work, the vendor carries only the surface
- vendor-client-session: Socks5Stream::use_stream path + the
AsyncRead/AsyncWrite impls; Config pruned (connect_timeout cut);
tests against a raw-byte mock server so it runs parallel with the
typestate task
- vendor-differential-tests: RFC edge-case suite over duplex streams,
pinning upstream behavior per vendor.md's differential posture
- review-vendor-extraction: the gate before downstream groups —
file-by-file diff vs /workspace/fast-socks5 must contain only
cut/carried-change/adjustment hunks
Graph validated: all dependency ids resolve, no cycles; topological
order scaffolding → wire → (typestate ∥ client) → tests → review.
Complete the ADR-011 §Amendment (extraction, not wholesale-copy-plus-
gate) across every doc that stated the pre-amendment posture:
- ADR-011: add the two extraction-recipe exclusions the amendment
missed (the socks4 module — upstream's separate default-off cargo
feature, out of RFC 1928 scope; the legacy Config/Authentication
auth layer — ungated but consumed only by the cut region) and the
dependency-surface adjustments (log -> tracing, anyhow dropped,
async-trait dropped with its legacy-layer uses)
- ADR-009: amend — the vendor's net gate dissolves; features collapse
to local + composed; local carries tokio/net + socket2 itself
- vendor.md: replace the contradictory old "four carried changes"
section with the two-change reading + extraction-time adjustments;
extend the cut table (socks4 row, legacy auth layer)
- overview.md: dependency diagram + feature table drop the net
feature; module map reflects two carried changes
- README.md: principles 7/8 + doc/ADR tables updated
- ADR-002/012, open-questions.md (OQ-SK-04), phase-0.md current-state
sections, AGENTS.md conventions 4/17 + stale wasm-caveat sentence,
POC findings posture notes: aligned with the extraction
Verification: repo-wide grep for stale "four carried"/default-on net/
implies-net statements returns only amendment-context matches;
extraction recipe re-verified against POC #4's gate map and the
fast-socks5 v1.0.0 source (async-trait usage confined to the cut
legacy layer; AuthMethod<T> traits are native async-fn-in-trait).
The Phase 0 doc had accumulated stratified updates (each revision layered
on top of the prior text), leaving duplicated statements, superseded
reasoning presented as live, and a few internal conflicts. This rewrite
is a consolidation only — no decisions changed:
- Each OQ opens with a status line; resolved content stated as settled
fact; superseded reasoning retained only where it carries Phase 1 ADR
weight (e.g. OQ-SK-04's decision tree as the reasoning trail).
- The inline-vendor decision now stated once (OQ-SK-04 + the Convergence
Layering bullet) instead of ~10 restatements; stale 'file the upstream
ask' residue removed (Convergence protocol-base bullet).
- The component-3 transfer to alknet stated once in §Vision; the noq
section is background-only; OQ-SK-06 compressed to its resolution.
- OQ-SK-01/03's duplicated direct-op update merged into its OQ;
OQ-SK-08's superseded sequencing consistently framed as the retired
POC workaround against alktunnels 0.1.0.
- Checklist: OQ-SK-03/06/07 and the POC box checked to match their own
text; 'RFC-refused in both POCs' corrected (fast-socks5 refuses BIND;
POC #5 implemented it).
- Preserved: all external anchors cross-referenced by the findings files
(§OQ-SK-07 register + numbering, §Prior art's run_udp_proxy_custom
caveat, OQ-SK-04's decision record, the Convergence Layering bullet),
every ADR/API/file:line reference, POC numbers, and measurement
figures. Restored on audit: the 65507 u16-suffices rationale,
skip_auth_this_is_not_rfc_compliant, lib.rs:91, the wasm-resolver
interaction note.
Verified: anchor audit against all cross-referencing docs (no dangling
references), content-loss audit vs the prior version (no unsuperseded
fact dropped), fast-socks5 v1.0.0 spot-checks (TCPBind refusal sites,
wait_on_tcp:1195, private new_reply, typestate methods — all true).
The ownership premise ('we own fast-socks5') was wrong — it is
third-party upstream and has not been forked. The corrected posture
resolves OQ-SK-04: inline vendor. The wrapper's needs exceed the wasm
gate regardless (BIND absent upstream — POC #5 proved the wrapper
drives it; the run_udp_proxy_custom bind seam; private new_reply), so
carrying the T-generic subset (~120 cfg lines, POC #4-verified) pays
for itself independent of the adapter story.
AGENTS.md:
- convention 17 rewritten: 'Upstream: alkcall is ours to shape;
fast-socks5 is inlined' — the ownership split stated plainly, the
inline vendor + its four carried changes named, the courtesy PR
kept optional/never-waited-on, the vendor point (v1.0.0) noted
- convention 4: wasm posture note updated to the resolved vendor
- prior-art entry: fast-socks5 marked third-party/NOT ours
phase-0.md:
- OQ-SK-04 RESOLVED (2026-09-20): resolution note headers the OQ (the
two settling facts: wrong ownership premise; needs exceed the gate);
decision tree retained as reasoning trail with both legs annotated
(Case 2's premise falsified by the BIND need); the root question
reframed as retrospective; checklist item checked
- §Prior art fast-socks5: header + run_udp_proxy_custom caveat
reworded from 'fileable ask' to in-tree change
- settled-foundations wasm caveat resolved; survey + checklist
prior-art entries marked; 'What Phase 0 could NOT answer' wasm item
struck as resolved; convergence Layering bullet now enumerates the
four in-tree carried changes; upstream-asks bullet: fast-socks5
items are no longer asks
poc-connect-wasm-findings.md / poc-bind-findings.md /
iroh-socks5-eval.md: 'we own it' ask sections corrected to
in-tree-vendor changes (dangling fragment from an earlier edit also
fixed); ledger item 3 annotated
Verified: fast-socks5 upstream still 1.0.0, no net feature, BIND
refused (lib.rs:384-386/server.rs:813-816) — the needs-are-real facts
stand. Docs-only change; no build surface affected.
The ask ledger's two alktunnels items landed 2026-09-18/20 — superseded
in shape, not implemented as posed. The graduation (alktunnels
tunnels-graduation.md -> ADRs 007/008) adopted the ssh
forwarded-tcpip-shaped alternative over the per-ask carriers.
phase-0.md:
- settled-foundations: establishment gains the reply-projection note
(ADR-049 amendment 3); the relay/hub note records the in-tree
ChannelRelay/HubLegTemplate (ADR-051); identity-seam note marked
current at 0.8.0
- OQ-SK-01: Option A updated — the direct op (channels/tunnel/direct,
ADR-007) is the dynamic-target channel; POC #5's scope-gate +
ADR-007 rationale point the same way (separation lives at the ACL)
- OQ-SK-03: composed egress's vehicle is open_direct +
Substrate::Udp; the ~0.8 ms measurement carries over; the stale
POC-candidate hunch paragraph updated
- OQ-SK-08: the landed note — ask #1 dissolved (bind-first establisher;
the real bound rides the open reply; POC #5's open-rides-the-accept
workaround + the 10s-bound finding retire), ask #2 landed at the
wire's native moment (forwarded op's {listen, substrate, peer}
params), correlation token per ADR-008 Amendment 1
- convergence: egress seam composes against 0.2.0; the upstream-asks
bullet records the landing per crate; the BIND hand-off bullet notes
variant 2 is now fully vanilla-fidelity
- checklist OQ-SK-08 item + POC #5 register entry point at the landed
note
poc-bind-findings.md: ledger statuses appended (superseded in shape;
evidence stands as the alktunnels-0.1.0 record)
AGENTS.md: alkcall pin 0.7.1 -> 0.8.0 (reply projection noted);
architecture context: alktunnels v0.2.0 entry added, alkcall 0.8.0
surface listed
Verified against the repos: alkcall 0.8.0 changelog (U-1/U-2/ADR-051),
alktunnels 0.2.0 changelog + ADR-007/008 + exports
(bindfirst_establisher producer.rs:641, register_tunnel_bindfirst_
openable :924), fast-socks5 still 1.0.0 with no net feature (the
courtesy tail). Docs-only change; no build surface affected.
POC #5 run 2026-09-15 (alksocks-bind-poc, standalone, 9 tests) —
OQ-SK-08 POC-validated; the POC register (OQ-SK-07) is closed.
- The BIND phase model extends end to end on one channel: request →
reply#1 (BND.ADDR) → quiet wait → one inbound accept → reply#2
(peer) → pump_bidi pass-through (0 B overhead, like CONNECT)
- Both accept variants implemented: local (real TcpListener, faithful
RFC) + composed (alktunnels listen-tunnel — per-listener ACL for
free, hub-relayable)
- The address-first-vs-accept-first deadlock resolved in shape:
reply#1 first, the tunnel open rides the accept future
- The socks5:bind scope gate distinguishes ingress from egress
(RFC-faithful ConnectionNotAllowed refusal; CONNECT unaffected)
- Vanilla front door re-validated for the BIND conversation (raw pipe,
zero translation); CONNECT + ASSOCIATE regression-guarded on the
same registration — the RFC 1928 command surface is complete
- fast-socks5: zero BIND ask (typestate-driven; reply_success carries
reply#1); courtesy ask: publish the private new_reply encoder
- alktunnels ask ledger pinned at two items for the one-version bump:
(1) listen-addr inspection without consuming an accept, (2) accepted
handles carrying peer metadata — both POC-evidenced, both additive
Verification: cargo test (9/9), clippy --all-targets -D warnings,
fmt --check clean in alksocks-bind-poc.
- OQ-SK-07: add a POC register table (one-place accounting of all five
numbered POCs: #1/#2/#4 passed, #3 dropped, #5 pending); mark the
priority order as historical; note numbering must not be renumbered
- §Vision: fix the components 1+2 layout sentence now that component 3
transferred; keep the transfer reasoning
- alknet-client ancestor section: replace the stale 'this crate's
client half rehomes that work' sentence with a historical note (the
rehoming is alknet's, per the 2026-09-14 scope decision)
- noq prior-art section + OQ-SK-06: add transfer banners so ~25 lines
of transferred research are not read as live scope
- OQ-SK-02: spell out what the 'yes / planes-don't-compare /
probably-not' shorthand maps to
- OQ-SK-04: note the component-3 transfer does not change the wasm
decision inputs
- OQ-SK-07 #3: rewrite the ambiguous 'at the time of the decision'
parenthetical as before/after
- Survey list: mark noq and iroh entries as alknet-facing background
- Convergence checklist: uncheck the POC item (BIND POC still pending)
and explain the checkbox semantics
Verified against the repo: findings files, POC crates
(alksocks-connect-poc 8 tests, alksocks-udp-poc 11 tests,
alksocks-fs5-wasm-poc exists), upstream line refs (fast-socks5
lib.rs:384-386 / server.rs:813-816 / 1195, noq runtime/mod.rs:44 /
endpoint.rs:162, alktunnels producer.rs:207,392), op name
channels/socks5/sub in both POC crates.
Verification: docs-only change; no build/test surface affected.
Post-POC #2 findings review: a real BIND use case and mechanism
surfaced, plus a channel-capacity analysis for proxy workloads.
- OQ-SK-08: fast-socks5 parses but refuses TCPBind — the wrapper owns
the whole shape (zero upstream ask). Phase-model extension: reply#1
(BND.ADDR) -> quiet wait -> one inbound accept -> reply#2 (peer) ->
raw pass-through; iroh-socks5's channels-native BIND is convergent
precedent. Accept variants mirror OQ-SK-03's egress variants:
feature-gated local listener (faithful RFC) vs composed alktunnels
listen-tunnel (needs a listen-addr-inspection ask) vs wrapper-aware
only. Security note: BIND is inbound egress — SOCKS5_OPEN_SCOPE must
distinguish it from CONNECT/ASSOCIATE.
- OQ-SK-09: 256-channel default vs proxy fan-out; wire change
rejected, assembly-layer config + documented proxy-workload
recommendation is the mechanism; in-channel port multiplexing
([port:u16] per chunk) considered and rejected (re-opens OQ-SK-03's
demux-vs-phase trade, breaks 0-B pass-through, AGENTS.md #10).
- OQ-SK-05 addendum: virtual address space / identity-scoped subnets
adoptable with no wire change — DST.ADDR/BND.ADDR translation via
the dial callback; hub exposure via terminate-and-re-produce.
- POC #5 (BIND, both accept variants, vanilla front-door test) added
to OQ-SK-07; checklist + convergence updated; upstream-asks list
pinned (fast-socks5: net gate + UDP bind seam; alktunnels:
listen-addr inspection).
Verification: docs-only change (phase-0.md).
- Scope resolution: the quinn/noq AsyncUdpSocket client wrapper
(component 3) transfers to the alknet rewrite (its ancestor work —
ADR-090, quinn-proxy POC — lives there; it consumes no channels and
has no consumers planned here). OQ-SK-06 and would-be POC #3 go
with it. alksocks = the producer/consumer pair only.
- Convergence section added (Phase 0's output for the Architect): the
validated approach pieces (fast-socks5 typestate driven directly for
both commands, the handle-swap wire shape, DialFn + EgressFactory
egress seam, "both" auth split by the door, alktty/alktunnels
layering, vendored-subset fork posture) and the list of Phase 1 ADR
decisions with their collected inputs (datagram framing, demux vs
phase, params/ALPN, scope convention, door mapping, wasm posture).
- Checklist: OQ-SK-06 resolved-by-transfer; POC list complete (#1/#2/#4
passed, #3 dropped); convergence checked off.
- alksocks-udp-poc (/workspace/alksocks-udp-poc/): 11 tests pass,
clippy -D warnings + fmt clean; the handle-swap baseline validated
end to end (one channel per association, [len][addr+data] frames
in-band, RSV/FRAG only at front doors, channel EOF = association
lifetime, per-datagram addressing without a flow table)
- Both egress variants implemented behind the EgressFactory callback;
composed per-destination alktunnels udp-tunnel open cost measured at
~0.8 ms mean (N=20, in-process loopback) — comfortable for DNS +
browsing
- Front-door RFC-codec composition confirmed (RFC UDP header codec at
the vanilla boundary only); CONNECT regression-guarded on the same
registration
- Load-bearing API findings for Phase 1: the select!-driven stage's
egress readiness contract (Pending-when-idle; readable() not
writable(); closed queues end, never spin) and the length framing
applied exactly once by the wire layer (egress returns inner bytes)
Verification: cargo test (11 pass), cargo clippy --all-targets -- -D
warnings, cargo fmt --check, cargo doc --no-deps (all clean in the
POC crate); phase-0.md OQ-SK-03/07 statuses updated.
channel_id is u32 on the wire (~4B ids, monotonic counter, ADR-040);
256 is the default per-connection max_channels (memory bound, 256x1MiB
reassembly buffers) and the default per-identity DoS cap (ADR-041) —
both configurable without a wire change. AGENTS.md convention 10 and
the OQ-SK-03 composed-egress note now carry the qualifier.
- endgame story makes both mechanisms real: consumer binds the produced
SOCKS5 resource locally (optional front door, ssh -D shape without
the forced bind) and points tun2proxy at it
- producer side: identity seam only (CF-005/CF-006); a password there
is moot against the ACL system — in-band conversation runs NoAuth
- consumer front door: owns RFC 1929 where vanilla clients need it
(tun2proxy/curl user:pass), maps accepted credentials to the channel
identity it opens the producer with; the SOCKS password never crosses
the channel as a SOCKS password
- replace-or-second-gate sub-question dissolves: the mechanisms occupy
different planes (door-local creds vs channel-level identity)
- remaining for Phase 1: credential->identity mapping shape; producer-
side local backend door surface; AuthMethod trait vs door-owned check
- the ASSOCIATE reply's BND.ADDR/BND.PORT is a relay handle, not a
destination (per-datagram destinations ride the datagram header);
swapping "tell the client about a UDP port" for "tell the client
about the UDP tunnel" preserves every RFC property: one channel per
association, {addr, data} frames in-band, channel EOF = association
lifetime, optional front-door binds on either side
- sentinel-address hunch superseded: no virtualized relay address is
ever needed on the in-band path; BND.ADDR there is pure
RFC-compatibility surface
- producer egress has two variants, both dial-callback policy (OQ-SK-01
shape): local UdpSocket (no flow table, native-only) or composed
per-target alktunnels udp-tunnels (lazy destination->tunnel table;
flow table reborn as channel handles; per-target ACL for free —
dissolves most of OQ-SK-05 for the composed path)
- no upstream ask: alktunnels' connected-udp substrate is correct as-is
for per-target composition; an unconnected-egress resource would be
SOCKS5 again (circular)
- POC #2 baseline settled: sketch both egress variants behind the dial
callback, measure per-destination open cost of the composed variant
- new docs/research/iroh-socks5-eval.md: full source review of
iroh-socks5 0.5.0 (github.com/mattgeddes/iroh-socks5, MIT OR
Apache-2.0) — quality verified, structural sibling of the alksocks
shape, but iroh-coupled (no generic-T seam) with an RFC subset, so
fast-socks5 stays the protocol base (POC #1/#4 conclusions stand)
- phase-0: prior-art section for iroh-socks5; OQ-SK-03 updated with its
UDP design as the POC #2 baseline (framed {addr, data} in-band
datagrams, RFC header codec at front doors only, no producer-side
flow table, control-EOF association lifetime, FRAG != 0 refused)
- POC #1 passed (alksocks-connect-poc, 8 tests + curl front-door
example): BiStream-as-T genericity, register_openable_with_
establisher fit, pump_bidi data plane, typed session refusal,
RFC reply-code dial-refusal mapping, vanilla-client front door.
Structural resolution: the dial belongs at the command-read
interception point (target is unknowable at open time); the
establisher is the session gate. OQ-SK-01/02 shapes resolved
empirically.
- POC #4 passed (fs5-wasm-poc, kept at /workspace/alksocks-fs5-wasm-poc):
the fork is genuinely minimal — ~120 lines of #[cfg] insertions
gate kernel-net behind a default-on 'net' feature; the wasm-clean
subset compiles for wasm32-unknown-unknown (--no-default-features)
and still completes a full RFC 1928 CONNECT conversation. OQ-SK-04
reduces to the adapter-story question.
- Corrected the run_udp_proxy_custom prior-art claim: it binds a
kernel socket unconditionally (relay closure + reply IP only);
the channels path drives the typestate directly. Fileable ask.
- Findings: docs/research/poc-connect-wasm-findings.md
The root question is 'does wasm make sense for alksocks?', not 'how
do we get wasm': Case 1 (wasm wanted) -> fork-first, PR as courtesy,
carry regardless; Case 2 (wasm unwanted) -> plain dependency on the
router.rs native path, no fork (the alkhttp precedent, strictly
better when its premise holds). Decision inputs written: (a) is
there a planned sandboxed (wasm) consumer of the SOCKS5 service,
(b) is the fork genuinely minimal (POC #4 checks). Fork-first is a
conditional preference, not a general one — do not carry a fork for
an invariant's sake. AGENTS.md conventions 4/17 aligned.
- phase-0 vision: components split — (1) producer half (expose the
SOCKS5 service over channels), (2) consumer half (consume it,
optionally bind it locally — the ssh -D front door + tun2proxy
path), (3) standalone SOCKS client wrapper for quinn/noq that must
work with any RFC 1928 server (iroh relay/peer IP-leak motivation,
alknet ADR-090 generalized); the earlier docs conflated the
consumer-side bind with the producer-side local backend
- principle 6: the vpn-like endgame — tunnel a produced SOCKS5
resource to a local port, point tun2proxy (--proxy socks5://
natively) at it; verified tun2proxy src/args.rs
- OQ-SK-04 resolved as fork-first: 'fork' = vendor-and-vet inline in
the crate (minimal diff, feature-gate native-net), PR upstream as
courtesy, never wait on approval; wasm-drop (alkhttp precedent) is
the escape hatch, not the plan
- AGENTS.md conventions 4/9/17 aligned (fork-first, binds on either
side, wasm posture)
- OQ-SK-03: RFC 1928 control/data never interleave (fast-socks5
wait_on_tcp treats post-reply control bytes as garbage), so the
alktty 5-stream demux solves a problem SOCKS5 doesn't have; phase
model (pass-through CONNECT, len-prefixed datagrams post-reply)
subsumes it; the demux's real advantage is an additive in-band
stream-type vocabulary — noted as the honest one-way-door fork
- OQ-SK-04: no structural fork needed for the channels surface
(router.rs interception shape covers CONNECT; run_udp_proxy_custom
+ reply_success + the pure UDP codec cover ASSOCIATE); the
fork/wrap/reimplement decision is driven entirely by the wasm
feature-gating outcome; full fork documented as least attractive
glm-5.3-flash