0 Fork 0

Files

T

glm-5.3-flash 9587670138 docs: Phase 1 architecture — specs, ADRs 001-012, open-questions tracker

- docs/architecture/: README index, overview, wire, producer,
  consumer, vendor, bast specs + open-questions.md (the OQ-SK-01..09
  ledger promoted; new questions as OQ-SK2-06..)
- ADRs 001-012: ALPN/op/params, protocol base, the handle swap,
  the dial-callback shape, auth split by the door, access control
  (open gate + BIND command gate), BIND in base, provider defaults,
  feature gates, channel capacity, the inline vendor, target policy
- deferred OQs (SK2-06, SK2-07) with tracker tasks in
  tasks/architecture/ per the sdd_process deferred-OQ protocol
- review pass applied: frame-length joint bound (65766 corner),
  accept_no_auth vs skip_auth corrected against fast-socks5 source,
  composed-feature wasm posture, cross-reference fixes

Verified: cross-references (all ADR/OQ refs resolve), doc sizes
under split threshold, Phase 0 fidelity spot-checks

2026-09-20 18:41:56 +00:00

3.7 KiB

Raw Blame History

ADR-008: Egress/Accept Provider Defaults — Local Socket and Composed (Direct Op)

Status

Accepted (2026-09-20, Phase 1; the A/B assembly-layer choice — OQ-SK-01's residue — with the composed vehicle settled by alktunnels 0.2.0 ADR-007)

Context

OQ-SK-01's dialer-trait-vs-callback half is closed (ADR-004); what remained was the default provider set: where does the dial callback come from in the base crate's optional shapes? Option A (dial via alktunnels — the composed shape), Option B (dial directly — local TCP), Option C (injected dialer trait — rejected, ADR-004). alktunnels 0.2.0 removed Option A's blocker (the direct op channels/tunnel/direct is the dynamic-target channel — one open per CONNECT target, what it was graduated for), and POC #2 measured its per-destination open cost (~0.8 ms, loopback) — fine for DNS + browsing.

Decision

The base crate ships both provider kinds, both feature-gated:
- Local-socket providers (behind the local feature): a real TcpStream dial (CONNECT), a real UdpSocket egress (ASSOCIATE, one socket per association, per-datagram send_to/recv_from — no flow table; domain destinations resolve at the egress, the ssh -D semantic), a real TcpListener accept (BIND, ADR-007 variant 1). These are the faithful-RFC shapes and the simplest assembly story.
- Composed providers (behind the composition feature): the dial callback opens an alktunnels direct-op channel naming the target (open_direct, Substrate::Tcp/Substrate::Udp); the UDP table is a lazy destination→tunnel table (open on first datagram, LRU-evict at a cap — POC #2's ComposedEgress shape). Hub relaying is per-target terminate-and-re-produce (alkcall ADR-051).
Neither provider is a dependency of the protocol layer — both are assembly-layer wiring (ADR-004); the features exist so the providers ship in the crate rather than forcing every deployment to hand-roll them. The feature gates and module placement are in overview.md §Feature gates.
No default in the abstract: registration always takes the callbacks explicitly; there is no implicit "default dialer." The feature-gated providers are convenience constructors over the same seams. A missing callback means that command refuses RFC-faithfully (CommandNotSupported-class reply), never a panic — the command gate is the open handler's dispatch, and a provider-less command is an unprovided capability, not an error condition.
Per-target ACL is the composed variant's benefit (each destination rides its own tunnel:direct-governed channel — ADR-006); the local variant's target policy is the dial callback itself.

Consequences

The "no ports" story has two halves, both covered: the consumer-facing half (the handle swap, ADR-003) and the producing-side half (local egress behind local; composed egress behind the composition feature; the protocol layer sees neither).
The 256-channel default cap bounds composed fan-out; the documented proxy-workload recommendation (ADR-010) covers the deployment guidance.
The composed egress's open cost is measured and acceptable for the target workloads (DNS + browsing); a high-fanout deployment that dislikes per-destination opens uses the local variant or raises the cap (config, not wire).

References

OQ-SK-01 (the A/B choice), OQ-SK-03 variant 2 (the composed egress), OQ-SK-05 (per-target ACL), OQ-SK-09 (the cap)
POC #2 poc-udp-associate-findings.md (both variants; the open cost), POC #5 poc-bind-findings.md (the composed accept)
alktunnels ADR-007 (the direct op), alkcall ADR-051 (the hub relay), ADR-004 (the seams), ADR-006 (the ACL posture)

3.7 KiB Raw Blame History