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

221 lines
9.8 KiB
Markdown
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](../research/phase-0.md) (OQ-SK-01)
- **Status**: resolved — [ADR-004](decisions/004-dial-callback-shape.md)
(the shape), [ADR-008](decisions/008-provider-defaults.md) (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](../research/phase-0.md) (OQ-SK-03)
- **Status**: resolved — [ADR-003](decisions/003-udp-handle-swap.md)
- **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](../research/phase-0.md) (OQ-SK-08)
- **Status**: resolved — [ADR-007](decisions/007-bind-in-base.md)
- **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](../research/phase-0.md) (OQ-SK-02)
- **Status**: resolved — [ADR-005](decisions/005-auth-split-by-door.md)
- **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](../research/phase-0.md) (OQ-SK-04)
- **Status**: resolved — [ADR-011](decisions/011-inline-vendor.md)
- **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](../research/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](../research/phase-0.md) (OQ-SK-09)
- **Status**: resolved — [ADR-010](decisions/010-channel-capacity.md)
- **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](../research/phase-0.md) (OQ-SK-05)
- **Status**: resolved — [ADR-006](decisions/006-access-control.md)
(the gate posture), [ADR-012](decisions/012-target-policy.md)
(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](../research/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](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](../research/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](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