0 Fork 0

Files

T

glm-5.3-flash 001aac1fd5 docs: the targeted fork — ADR-013, the RFC 1928 core is owned

ADR-013 supersedes ADR-011's maintenance posture (not its mechanics):
the extracted T-generic subset is fully owned code, the vendor
framing is retired. Module renamed src/vendor/ -> src/rfc1928/
(naming decided in the ADR: 'vendor' names an ownership relation
now gone; 'socks5' would stutter and collide with the future
producer/consumer layers). Fork point = the tree as of the
extraction-review commit (5b18d4d); provenance stays permanent
(module docs + the extended LICENSE notice).

- ADR-013: fork posture, license mechanics (notice extended, not
  replaced; post-fork modifications under the crate license),
  hand-port replaces re-vendor, lint-allow posture dissolved
- ADR-011 marked Superseded (extraction mechanics remain
  authoritative); ADR-002 references re-pointed
- vendor.md -> rfc1928.md rewritten as the owned-core spec (the cut
  table re-read as the hand-port map)
- spec sweep: README index (ADR-013 row, doc table, principle 8),
  overview (module map, deps, ADR table), producer/consumer/wire/
  bast reference vocabulary, open-questions OQ-SK-04 resolution,
  AGENTS.md conventions 4/17 + verification note + context bullet,
  Cargo.toml description

Verification: cargo doc --no-deps clean; no stale vendor.md/src-vendor
references outside the ADR-011 historical text.

2026-09-22 12:33:36 +00:00

3.0 KiB

Raw Blame History

ADR-002: Protocol Base — the Vendored fast-socks5 Typestate Subset

Status

Accepted (2026-09-20, Phase 1; the extracted-and-forked posture is OQ-SK-04's resolution — the extraction mechanics in ADR-011, the ownership posture in ADR-013)

Context

Phase 0 evaluated the protocol-base candidates: fast-socks5 (the full-fidelity RFC 1928 implementation, explicit typestate server API, generic over T), iroh-socks5 (structurally the closest sibling, but iroh-coupled and an RFC subset), and a hand-rolled codec (rejected as anti-prior-art — alknet's client hand-rolls and it is the known weakness). POC #1 confirmed the load-bearing property: fast-socks5's Socks5ServerProtocol<T, states::*> accepts a channels BiStream directly (T: AsyncRead + AsyncWrite + Unpin), and POC #4 measured the wasm gating at ~120 cfg lines with the wasm-clean subset functionally complete (a full RFC 1928 CONNECT conversation passes --no-default-features).

Decision

The protocol layer is built on fast-socks5's explicit typestate API — Socks5ServerProtocol<T, …> (negotiate/finish_auth/ read_command/reply_success/reply_error), the client side Socks5Stream<S>::use_stream / the associate session, and the pure codecs (new_udp_header/parse_udp_request).
Only the explicit API is used. The legacy Socks5Server/Socks5Socket/Incoming bind-based API is deprecated upstream and is out — never forked into the default path.
Base = v1.0.0, extracted in-tree and forked (ADR-011 for the extraction mechanics and the two carried changes; ADR-013 for the targeted-fork ownership posture). /workspace/fast-socks5 remains the read-only reference for differential testing of RFC edge cases; the fork point is noted in the module docs and the bundled license notice.
Refusals map faithfully per RFC 1928 — ReplyError codes (as_u8/from_u8) are the error vocabulary at the command plane; refusals are never collapsed into generic errors (AGENTS.md convention 2). POC #1 validated the mapping (dial refusal → 0x05).

Consequences

The crate owns its protocol code in-tree (the fork), so BIND and the new_reply publication ride the same tree — no upstream waits.
The typestate's interception points are the layering seams: command-read (the dial/accept dispatch), transfer (the raw two-pump), and — where the default handlers are unusable (UDP ASSOCIATE's unconditional bind) — direct typestate driving. The interception-point map is spec'd in producer.md.
iroh-socks5's design ideas (the {addr, data} frame, control-EOF association lifetime, FRAG≠0 refusal) were adopted at the design level, not the code level (docs/research/iroh-socks5-eval.md).

References

OQ-SK-04 (resolved: the extracted-and-forked base), OQ-SK-03 (the run_udp_proxy_custom caveat)
docs/research/iroh-socks5-eval.md (the base comparison), POC #1 + POC #4 (poc-connect-wasm-findings.md)
Sibling precedent: alktunnels ADR-002 (one-ALPN option A)

3.0 KiB Raw Blame History