alkdev/alksocks
6
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
95876701380099f3ab83432ff17d2cfb43780069
alksocks/docs/architecture/open-questions.md
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

9.8 KiB
Raw Blame History

status: draft last_updated: 2026-09-20 (Phase 1 initial draft — the OQ-SK ledger OQ-SK-01..09 promoted; new questions continue as OQ-SK2-06..)

alksocks — Open Questions

Centralized tracker. The Phase 0 OQ ledger (docs/research/ phase-0.md, OQ-SK-01..09) is promoted here with statuses current as of the Phase 1 spec; new Phase 1 questions continue the OQ-SK2 numbering (SK2 = the architecture-set ledger, distinct from the Phase 0 ledger's OQ-SK- prefix, which stays historical). Note: the SK2 numbering is not contiguous from 01 — OQ-SK2-01..05 were consumed in working drafts before the first committed set; the sequence starts at the numbers in use. Format per docs/sdd_process.md.

Theme 1: Wire format and phases

OQ-SK-01: Producer dial policy — what dials the target?

  • Origin: phase-0.md (OQ-SK-01)
  • Status: resolved — ADR-004 (the shape), ADR-008 (the provider set)
  • Priority: high
  • Resolution: 2026-09-20 (Phase 1). The dialer-trait-vs-callback half closed on the POC evidence (function-not-trait at three seams — DialFn/EgressFactory/BindAcceptFactory, boxed halves, ownership rides the handle). The provider-default half: the base crate ships local-socket providers (local) and composed providers (composed, the alktunnels direct op); no implicit dialer — registration always takes the callbacks explicitly.
  • Cross-references: OQ-SK-03, OQ-SK-08, ADR-004, ADR-008

OQ-SK-03: UDP ASSOCIATE without binding

  • Origin: phase-0.md (OQ-SK-03)
  • Status: resolved — ADR-003
  • Priority: high
  • Resolution: 2026-09-20 (Phase 1; baseline settled 2026-09-13, POC #2 validated 2026-09-14). The handle swap: one channel per association; {addr, data} frames in-band ([len: u16 BE] over the vendored address encoding); association lifetime = channel lifetime; RFC codec at front doors only; sentinel BND.ADDR in-band. The datagram framing (the one-way door) is now decided with empirical ground under it (open cost measured ~0.8 ms; LRU + dedup pinned by test).
  • Cross-references: OQ-SK-01, ADR-003, ADR-008

OQ-SK-08: BIND — the accept-side command

  • Origin: phase-0.md (OQ-SK-08)
  • Status: resolved — ADR-007
  • Priority: high
  • Resolution: 2026-09-20 (Phase 1; POC #5 validated 2026-09-15). BIND ships in the base crate, phase-model style; the accept variants: local listener (default, faithful), composed (alktunnels bind-first listen + forwarded op — vanilla-fidelity since the graduation), wrapper-aware (in-band default). The establishment bound covers only the open-op round trip; the accept wait lives in the teardown-governed pump phase.
  • Cross-references: OQ-SK-01, ADR-004, ADR-006, ADR-007

Theme 2: Crate architecture

OQ-SK-02: Auth mapping — identity seam vs in-band SOCKS auth

  • Origin: phase-0.md (OQ-SK-02)
  • Status: resolved — ADR-005
  • Priority: medium
  • Resolution: 2026-09-20 (Phase 1; the posture settled 2026-09-13). "Both," split by the door: producer = identity seam (in-band NoAuth no-op); front door = RFC 1929 + static credential→identity config mapping. The door's credential→ identity mapping shape (the Phase 0 residue): static config in v1; a pluggable lookup remains an additive extension if a deployment needs dynamic resolution.
  • Cross-references: ADR-005, ADR-006

OQ-SK-04: fast-socks5 wasm posture

  • Origin: phase-0.md (OQ-SK-04)
  • Status: resolved — ADR-011
  • Priority: high
  • Resolution: 2026-09-20 (Phase 0's final resolution, promoted). The inline vendor: the T-generic subset in-tree behind the default-on net feature; the four carried changes (net gate, BIND, the udp-bind seam, new_reply publication); v1.0.0 noted; differential testing against /workspace/fast-socks5.
  • Cross-references: ADR-002, ADR-009, ADR-011

OQ-SK-07: POC register

  • Origin: phase-0.md (OQ-SK-07)
  • Status: resolved — the register is closed (process artifact, not a design question)
  • Priority: low
  • Resolution: 2026-09-14 (Phase 0). All POCs resolved: #1, #2, #4, #5 passed; #3 dropped (transferred to alknet with OQ-SK-06). Findings live in docs/research/ (the findings files are the artifacts); numbering is historical (do not renumber). Full register: phase-0 §OQ-SK-07.
  • Cross-references: OQ-SK-06

OQ-SK-09: Channel capacity for proxy workloads (the 256 default)

  • Origin: phase-0.md (OQ-SK-09)
  • Status: resolved — ADR-010
  • Priority: medium
  • Resolution: 2026-09-20 (Phase 1). No wire change (rejected permanently); assembly-layer config is the mechanism; the crate docs carry the proxy-workload recommendation with the memory arithmetic; in-channel port multiplexing rejected (the rationale + the revisit trigger recorded — the additive escape is a new multiplexed ALPN).
  • Cross-references: OQ-SK2-08, ADR-010

Theme 3: Policy and composition

OQ-SK-05: Target policy and egress scoping

  • Origin: phase-0.md (OQ-SK-05)
  • Status: resolved — ADR-006 (the gate posture), ADR-012 (target policy + the virtual-subnet layer)
  • Priority: high
  • Resolution: 2026-09-20 (Phase 1). No allowlist hook in v1 (the dialer-refuses shape); domain targets pass through unresolved (egress-owned resolution); the virtual-subnet translation layer is assembly-layer policy over the dial callback (no crate feature in v1; a helper may be added additively if a deployment materializes).
  • Cross-references: OQ-SK2-07, ADR-006, ADR-008, ADR-012

OQ-SK-06: noq client support

  • Origin: phase-0.md (OQ-SK-06)
  • Status: resolved — transferred to the alknet rewrite (the 2026-09-14 scope decision)
  • Priority: low
  • Resolution: 2026-09-14 (Phase 0). The quinn/noq AsyncUdpSocket client wrapper is alknet's ancestor-shaped component (ADR-090 + the quinn-proxy POC live there); it neither produces nor consumes channels. This crate's client story is the channels-native sessions (POC-validated) — complete without it.
  • Cross-references: ADR-002 (the base), phase-0 §Scope

OQ-SK2-06: The sandboxed-wasm-consumer adapter story

  • Origin: overview.md (the wasm posture's product input; phase-0 OQ-SK-04's retrospective)
  • Status: deferred(scope)
  • Door type: two-way
  • Priority: low
  • Impacts: how much wasm surface to exercise in the default crate (a product/docs input). Blocks nothing in the protocol design — the wasm-clean invariant (ADR-009) holds regardless.
  • Blocked on: a concrete sandboxed-adapter use case (a TS/Python adapter embedding the consumer session). Tracker task id: architecture/oq-sk2-06-wasm-adapter-story (tasks/architecture/oq-sk2-06-wasm-adapter-story.md).
  • Resolution: Not yet decidable. The use case isn't concrete yet — the adapter story is a product input whose shape would tell us whether the wasm consumer needs surface beyond the channels-native session (e.g. bindings ergonomics). The architecture decision (wasm-clean default, ADR-009) is already made and does not depend on this.
  • Cross-references: ADR-009, ADR-011

OQ-SK2-07: Virtual-subnet translation-layer helper

  • Origin: phase-0.md (OQ-SK-05's 2026-09-14 proposal; ADR-012's resolution)
  • Status: deferred(scope)
  • Door type: two-way
  • Priority: low
  • Impacts: nothing in the crate — the seams already support the translation layer (the dial callback, ADR-004/ADR-012). This tracks whether a translation-table helper should graduate into the crate if a deployment materializes with concrete needs.
  • Blocked on: a concrete deployment wanting identity-scoped virtual subnets (the tun2proxy virtual-network prior art to check at that point). Tracker task id: architecture/oq-sk2-07-virtual-subnet-helper (tasks/architecture/oq-sk2-07-virtual-subnet-helper.md).
  • Resolution: Not yet decidable. The use case isn't concrete — the mechanism is assembly-layer policy today (ADR-012), and a crate-level helper would need real deployment requirements to shape (subnet sizing, per-identity tables, hub exposure).
  • Cross-references: ADR-004, ADR-006, ADR-012, OQ-SK2-08

Theme 4: Documentation tuning

OQ-SK2-08: The recommended proxy-workload cap figure

  • Origin: overview.md §Open Questions; ADR-010's docs-level residue
  • Status: open
  • Priority: low
  • Resolution: ADR-010 pinned the posture (config, not wire; documented recommendation with memory arithmetic). The concrete recommended figure (e.g. "raise per-connection to 4096, per- identity to 1024" or similar) is a docs tuning note to pin during implementation when real workload numbers exist.
  • Cross-references: OQ-SK-09, ADR-010

Deferred / Blocked (index)

OQ Status Blocked on Tracker task
OQ-SK2-06 deferred(scope) a concrete sandboxed-adapter use case architecture/oq-sk2-06-wasm-adapter-story
OQ-SK2-07 deferred(scope) a concrete virtual-subnet deployment architecture/oq-sk2-07-virtual-subnet-helper

References

  • Phase 0 ledger: docs/research/phase-0.md §Open Questions (OQ-SK-01..09 — the full reasoning trails live there)
  • The SDD process: docs/sdd_process.md (the OQ format; the deferred-OQ blocker-task half)
Reference in new issue View Git Blame Copy Permalink