core: the cross-cutting integration suite + docs sync
The batch-1 closing task: nine cross-cutting integration tests
(tests/core-integration.rs) pinning the whole protocol core end to
end over the channels harness, plus the architecture-sync docs pass.
Tests:
- One registration, all three commands: CONNECT + ASSOCIATE + BIND
interleaved live on the one channels/socks5/sub op; a teardown
ends only its own session (mux/demux isolation) — the POC #2/#5
regression guard, complete.
- Concurrency: nine concurrent mixed-command sessions (raw topology)
and six through the typed consumer sessions (consumer-side
topology) — the mux/demux pinned in both channel-id allocation
directions; fresh round-trips after the burst; no channel leaks.
- Teardown matrix (wire.md §Sentinels and lifecycle): CONNECT
half-close, ASSOCIATE EOF, BIND client-gone (a parked accept so
the quiet-wait exit is deterministic) — each followed by fresh
sessions of every command (no connection poisoning).
- Identity/scope matrix (ADR-006 end to end): open-only (CONNECT +
ASSOCIATE serve, BIND refused 0x02 at the command gate), bind-only
fail-closed at the open gate for all commands (the spec drift the
task's phrasing carried, reconciled — ADR-006's open gate requires
socks5:open unconditionally), both-scopes (everything, granted
explicitly); the CF-006 witness asserted per row.
- The readiness contract re-pinned under concurrent load: a
hot-Ok(None) egress across concurrent associations does not starve
the datagram stage's channel branch.
Docs sync: README Current State ("the protocol core is implemented"
+ the landed inventory; the decomposition residue gone); consumer.md
§Wiring reconciled to the landed session signatures; ADR-006
§Consequences states the grant asymmetry explicitly; lib.rs crate
docs describe the landed surface.
Verification: cargo test 302 green; --all-features green; clippy
--all-targets -D warnings clean; fmt --check clean; both wasm checks
clean; cargo doc --no-deps clean. Batch boundary holds: no
local/composed code, the default crate is protocol-only.
This commit is contained in:
1 parent
c57451545d
commit
1ad8d9d489
6 files changed
+1196
-37
No files matched your search
+24
-13
@@ -1,10 +1,10 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-09-22 (the targeted fork — ADR-013; the module is
|
||||
`src/rfc1928/`; the vendor posture retired. The vendor extraction
|
||||
amendment ADR-011 §Amendment 2026-09-21; Phase 1 initial draft
|
||||
2026-09-20 — the OQ-SK ledger promoted into ADRs 001-012 and
|
||||
open-questions.md)
|
||||
last_updated: 2026-09-24 (the protocol core landed + the cross-cutting
|
||||
integration suite; the rfc1928 doc's targeted fork 2026-09-22; the
|
||||
vendor extraction amendment ADR-011 §Amendment 2026-09-21; Phase 1
|
||||
initial draft 2026-09-20 — the OQ-SK ledger promoted into ADRs
|
||||
001-012 and open-questions.md)
|
||||
---
|
||||
|
||||
# alksocks — Architecture
|
||||
@@ -20,16 +20,27 @@ architecture spec docs and the ADRs.
|
||||
|
||||
## Current State
|
||||
|
||||
Phase 1 (Architecture) — initial draft. Phase 0
|
||||
(`docs/research/phase-0.md`) is converged (2026-09-14) and
|
||||
POC-complete (all numbered POCs passed or were dropped with the
|
||||
scope decision); the OQ-SK ledger's Phase 1 inputs are collected and
|
||||
promoted into ADRs 001–012. All docs are `draft` — they transition
|
||||
Phase 1 (Architecture) — the **protocol core is implemented**. Phase
|
||||
0 (`docs/research/phase-0.md`) is converged (2026-09-14) and
|
||||
POC-complete (all numbered POCs passed or were dropped with the scope
|
||||
decision); the OQ-SK ledger's Phase 1 inputs are collected and
|
||||
promoted into ADRs 001–013. All docs are `draft` — they transition
|
||||
to `reviewed` when their open questions resolve and the architecture
|
||||
review passes. The RFC 1928 core is implemented (the targeted fork,
|
||||
review passes.
|
||||
|
||||
The landed core (the protocol-only batch; no `local`/`composed` code
|
||||
exists yet): the RFC 1928 core in `src/rfc1928/` (the targeted fork,
|
||||
ADR-013 — the vendor group's six tasks landed and passed the
|
||||
extraction review); the remaining layers follow the decomposition
|
||||
phase.
|
||||
extraction review), the ASSOCIATE datagram frame codec (`src/wire.rs`,
|
||||
ADR-003), the open-op params + typed error surface (`src/params.rs` /
|
||||
`src/error.rs`, ADR-001), the three seam types (`src/egress.rs`,
|
||||
ADR-004), the producer half (`src/producer.rs` — the session-gate
|
||||
establisher, the command-dispatch pump, the three commands, the scope
|
||||
gates), and the consumer half (`src/consumer.rs` — the
|
||||
connect/associate/bind session types with teardown ownership). The
|
||||
batch-1 cross-cutting integration suite (`tests/core-integration.rs`)
|
||||
pins the core's whole behavior end to end; the `local` and
|
||||
`composed` provider groups follow (batch 2).
|
||||
|
||||
## Documents
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-09-20 (Phase 1 initial draft)
|
||||
last_updated: 2026-09-24 (the landed session signatures reconciled —
|
||||
`&ChannelClient` constructors, `impl ToTargetAddr` datagrams, the
|
||||
`Option`-shaped `recv_datagram`; Phase 1 initial draft 2026-09-20)
|
||||
---
|
||||
|
||||
# alksocks — The Consumer Half
|
||||
@@ -120,12 +122,12 @@ address) is assembly-layer configuration.
|
||||
|
||||
```rust
|
||||
let session = Socks5ChannelSession::connect(
|
||||
&mut channel_client, target)?;
|
||||
&channel_client, target).await?;
|
||||
let (mut read, mut write) = session.split(); // post-reply payload pipe
|
||||
|
||||
let assoc = AssociateSession::associate(&mut channel_client)?;
|
||||
assoc.send_datagram(dst, &bytes).await?;
|
||||
let (src, bytes) = assoc.recv_datagram().await?;
|
||||
let assoc = AssociateSession::associate(&channel_client).await?;
|
||||
assoc.send_datagram(dst, &bytes).await?; // frames once, ADR-003
|
||||
let (src, bytes) = assoc.recv_datagram().await?.expect("a datagram");
|
||||
|
||||
let door = FrontDoor::builder()
|
||||
.credentials(cred_table) // RFC 1929 mapping, ADR-005
|
||||
@@ -134,6 +136,14 @@ let door = FrontDoor::builder()
|
||||
door.serve(channel_client).await?;
|
||||
```
|
||||
|
||||
The landed session signatures: the constructors take `&ChannelClient`
|
||||
(shared — many sessions ride one client, the concurrency posture);
|
||||
`send_datagram` takes `impl ToTargetAddr` (the CONNECT session's
|
||||
target-construction posture, ADR-012); `recv_datagram()` returns
|
||||
`Result<Option<(TargetAddr, Bytes)>, SocksSessionError>` — `None` is
|
||||
the channel EOF (the association's clean end), never an empty
|
||||
datagram (F-2: an empty payload is a legal datagram).
|
||||
|
||||
## Design Decisions
|
||||
|
||||
| ADR | Decision | Summary |
|
||||
|
||||
@@ -3,7 +3,8 @@
|
||||
## Status
|
||||
|
||||
Accepted (2026-09-20, Phase 1; scope gates POC-validated in shape —
|
||||
POC #1 (`socks5:open`), POC #5 (`socks5:bind` at command dispatch))
|
||||
POC #1 (`socks5:open`), POC #5 (`socks5:bind` at command dispatch);
|
||||
consequence asymmetry pinned by the integration suite, 2026-09-24)
|
||||
|
||||
## Context
|
||||
|
||||
@@ -60,7 +61,14 @@ distinction at command dispatch from the per-call opener identity.
|
||||
- Two grants, clean separation: `socks5:open` (egress) and
|
||||
`socks5:bind` (ingress listeners) — never implied by each other
|
||||
(the alktunnels ADR-006 Amendment 1 posture: a capability on its
|
||||
own scope).
|
||||
own scope). The implication asymmetry is pinned by the integration
|
||||
suite (`tests/core-integration.rs`, the identity/scope matrix):
|
||||
`socks5:open` alone serves CONNECT + ASSOCIATE and is refused BIND
|
||||
(0x02) at the command gate; `socks5:bind` alone grants *nothing*
|
||||
on the op — the open gate's `required_scopes = ["socks5:open"]`
|
||||
fails closed for every command (the establisher never runs, no
|
||||
phantom channel); both scopes, granted explicitly, serve
|
||||
everything. A BIND-capable deployment grants both.
|
||||
- BIND's security boundary is enforced even though BIND rides the
|
||||
same op (ADR-001): the command gate is the mechanism, and it is
|
||||
POC-validated (POC #5).
|
||||
|
||||
Reference in new issue
Block a user