docs: Phase 1 architecture spec — ADRs 001..006, spec docs, OQ promotion
The Phase 0 OQ ledger (OQ-TN-01..10) promoted into
docs/architecture/open-questions.md (now OQ-TN-01..14, with four
new Phase 1 residues). Six ADRs and four spec docs, all Draft, all
decision-shaped per the SDD process (ADRs carry the WHY; specs carry
the WHAT and reference by number):
ADRs:
- 001 open-params-layout: params = {resource, substrate} — the
producer's stable name, not an address; wire-stable from the first
consumer; unknown substrates fail loudly at schema time
- 002 alpn-strategy: single alk/tunnel ALPN (option A); substrate in
params selects the framing; prior art (SSH/SOCKS5/udpgw) gives no
reason for the split
- 003 codec-and-udp-framing: raw pass-through (stream) / mandatory
[len: u16 BE] (UDP) — F-2 mandate recorded (the codec is mandatory
for correctness, not cosmetics); len=0 = legal empty datagram;
OQ-TN-13 resolved fail-loud (truncation)
- 004 no-backend-trait: halves functions at the assembly layer;
listen is an establisher shape; hub re-produce deferred(OQ-TN-12);
trait re-evaluated at the alknet ADR-078 convergence threshold
- 005 consumer-session-owns-teardown: TunnelSession with
open/adopt/stream_halves/take_halves/pump_against/close/join/Drop —
the W3 adopter gap closes structurally; Drop is the best-effort
fallback
- 006 access-control-posture: the open gate is the boundary;
TUNNEL_OPEN_SCOPE = tunnel:open (stable once published); op-level
ACL; ownership seam; no allowlists in v1; identity = 0.7.0's
precedence chain
Spec docs:
- overview.md: purpose, resource model, deps (alkcall 0.7.0,
wasm-clean default, local feature), module map
- wire.md: the open op (params/reply/typed errors), the data plane
by substrate, sentinels + half-close, byte diagrams
- producer.md: spec, establisher (dial + listen shapes), pump
handler (pump_bidi inline, R-02), registration API, ACL posture
- consumer.md: TunnelSession (forward open + reverse adopt
construction), data plane, teardown API (close/join/Drop incl.
pump-less join semantics)
- bast.md: the BAST doc for the UDP codec (convention 12's trigger
fired — the framing IS binary beyond pass-through)
- open-questions.md: OQ-TN-01..14; 01..10 promoted (faithful to the
phase-0 ledger's final states), 11 partially resolved (collision
domain = per-producer registry per ADR-001; lifecycle open),
12 deferred(scope), 13 resolved fail-loud (ADR-003), 14 open
Verified by an architecture-reviewer pass (2 criticals, 6 majors,
10 minors — all fixed: ADR-001/003-vs-OQ decision-state contradictions
resolved; the Layer-2 mislabel corrected to the ADR-047 §4 per-session
fork; alktty/alknet ADR misattributions fixed; codec placement pinned
to the establisher (pump stays substrate-agnostic); reverse-path
construction named (TunnelSession::adopt + pump_against); security
posture promoted to ADR-006; BAST doc written; F-2 rationale deduped;
README tables completed; channel_id > 0; MTU wording fixed; ADR-047 §5
attributions corrected; impacts lines added to unresolved OQs; review/
ledger pointer paths added to README references).
Verification: doc set internal cross-refs all resolve; cargo test,
fmt --check, doc --no-deps clean
This commit is contained in:
@@ -0,0 +1,190 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-09-07
|
||||
---
|
||||
|
||||
# alktunnels — Producer Half
|
||||
|
||||
The producer half: the `channels/tunnel/sub` open op — its spec, its
|
||||
establisher (dial + listen shapes), its pump handler, and its
|
||||
registration. The producer is whoever can reach the tunnel target;
|
||||
connection direction is irrelevant (OQ-TN-03's hub model). The reverse
|
||||
POC validated the producer running on the connect side of its own
|
||||
connection (`from_connection_with_serving`).
|
||||
|
||||
Design decisions: [ADR-001](decisions/001-open-params-layout.md)
|
||||
(params), [ADR-002](decisions/002-alpn-strategy.md) (ALPN),
|
||||
[ADR-003](decisions/003-codec-and-udp-framing.md) (codec),
|
||||
[ADR-004](decisions/004-no-backend-trait.md) (no backend trait). This
|
||||
document is the normative WHAT.
|
||||
|
||||
## The Open-Op Spec
|
||||
|
||||
```text
|
||||
operation id: channels/tunnel/sub
|
||||
op type: Sub (reply = one { channel_id } envelope; data plane on the BiStream)
|
||||
ALPN marker: alk/tunnel (ChannelOpenSpec)
|
||||
visibility: External
|
||||
input schema: { resource: string (required), substrate: enum [tcp, udp, unix] (required) }
|
||||
output schema: { channel_id: integer > 0 }
|
||||
access control: required_scopes: ["tunnel:open"]
|
||||
description: SHOULD carry a human-readable hint (round-trips through discovery, OQ-TN-08)
|
||||
```
|
||||
|
||||
Registration is via `ChannelCore::register_openable_with_establisher`
|
||||
(alkcall ADR-049 §5): the registry schema-validates input, runs the
|
||||
ACL, allocates the channel (connection-owner rule, ADR-047 §5), runs
|
||||
the establisher as the awaited bounded establishment phase, then
|
||||
spawns the pump handler. The generic channel ops
|
||||
(`channel/close`, `channel/control`, `channel/resources/subscribe`)
|
||||
register separately via `ChannelOperations::register_on` — the
|
||||
producer (or its assembly layer) MUST register them on the serving
|
||||
registry so peers can manage channels out-of-band (the recipe alkcall
|
||||
review 007 §Part B verified — `alkcall/docs/reviews/
|
||||
007-establishment-follow-ups-review.md`; R-01 = the `Establishment`
|
||||
plan payload, R-02 = the `OpenHandler` lifetime contract).
|
||||
|
||||
**Registration timing:** the openable may register AFTER
|
||||
`from_connection_with_serving` returns (the connect-side serving
|
||||
posture — the reverse POC's W2): the dispatcher reads through the
|
||||
shared `Arc<OperationRegistry>` per dispatch. Late registration is a
|
||||
supported assembly shape, not a race.
|
||||
|
||||
## The Establisher
|
||||
|
||||
The establisher is the open op's awaited, bounded establishment phase
|
||||
(alkcall ADR-049 §1/§2): validate params semantically, consult
|
||||
ownership if wired, dial/accept the substrate, and return
|
||||
`Establishment::new(plan)` — the dialed handle rides the typed-opaque
|
||||
plan (`ChannelPlan = Arc<dyn Any + Send + Sync>`; the `+ Sync` bound
|
||||
constrains plan payloads — socket-backed handles carry it naturally,
|
||||
reverse POC F-1, documented upstream). On failure:
|
||||
`EstablishmentError` (the typed reason codes) → the wrapper tears the
|
||||
channel down and replies `channel:open_failed`.
|
||||
|
||||
**Two shapes** (both return the same plan-flow; ADR-004):
|
||||
|
||||
### 1. Dial establisher (the `-L`/forward shape)
|
||||
|
||||
Registry lookup of `(resource, substrate)` → backing → dial →
|
||||
halves. The dial function is substrate code injected at assembly
|
||||
(ADR-004: the establisher closure closes over it); the protocol crate
|
||||
never sees a socket type. Failure mapping:
|
||||
|
||||
| Producer condition | Typed reason |
|
||||
|---|---|
|
||||
| resource not in the registry (or wrong substrate) | `unknown_resource` |
|
||||
| dial refused / timed out / unreachable | `dial_failed` |
|
||||
| bind/connect resource exhaustion (fds, ports, slots) | `resource_shortage` |
|
||||
| establisher-internal failure | `handler_error` |
|
||||
| the bound exceeded | `timeout` (wrapper-level) |
|
||||
|
||||
### 2. Listen establisher (the producer-side listener variant)
|
||||
|
||||
For a producer whose resource is a LISTENER (SSH `-R` far-side
|
||||
listener; a hub exposing its own port to a third party): the same
|
||||
open op, the same params; the establisher pops the next accepted
|
||||
connection from an assembly-owned listener queue and returns it as
|
||||
the plan payload. The listener lifecycle (bind, accept loop, cancel)
|
||||
is assembly code — the protocol never binds (OQ-TN-04). Error
|
||||
mapping: an empty queue during establishment is `resource_shortage`;
|
||||
a closed listener is `dial_failed`-class. No new wire surface — the
|
||||
listen variant is plan-flow with a different halves source.
|
||||
|
||||
**Identity:** the establisher receives the **per-call opener
|
||||
identity** (the dispatch-resolved identity overlaid onto the
|
||||
install-time context — alkcall 0.7.0 CF-006). On hub-forwarded opens
|
||||
it sees the end client, not the hub. `auth` carries the opener's
|
||||
identity plus the transport-truthful fields (`alpn`, `remote_addr`,
|
||||
`tls_client_fingerprint`) — never rewritten. Consult it for
|
||||
ownership-scoped resources if the assembly layer wants
|
||||
`OwnershipProvider` checks here (OQ-TN-08's optional half).
|
||||
|
||||
**Concurrency:** each open's establisher result flows to ITS pump
|
||||
handler — concurrent opens of the same resource are independent
|
||||
(the R-01 plan flow — alkcall review 007 R-01, the
|
||||
`Establishment::new(plan)` payload; the forward POC's resource-keyed
|
||||
handoff race is structurally gone, confirmed under concurrency by the
|
||||
reverse POC).
|
||||
|
||||
## The Pump Handler
|
||||
|
||||
The `OpenHandler` (alkcall ADR-049/050 shape:
|
||||
`Fn(Value, Option<ChannelPlan>, Connection, AuthContext) ->
|
||||
JoinHandle<()>`):
|
||||
|
||||
1. Downcast the plan to the concrete handle type
|
||||
(`Arc::downcast::<TargetHandle>` — establisher and handler agree
|
||||
on the type; alkcall never inspects it).
|
||||
2. `conn.accept_bi()` — the channel's yield-once `BiStream`.
|
||||
3. `pump_bidi(bidi, handle.read, handle.write)` — **awaited inline**
|
||||
inside the handler's task. The returned `JoinHandle` MUST track
|
||||
the data-plane lifetime (R-02): the wrapper awaits it and its
|
||||
completion triggers channel teardown. **Early return =
|
||||
teardown-at-birth** — both pumps see instant EOF with zero bytes;
|
||||
the "spawn-and-forget" shape is the one bug class the R-02
|
||||
telemetry (yield-once flag + birth-teardown debug hint) diagnoses
|
||||
at runtime. Hand-rolling the two-pump shape is out (ADR-050).
|
||||
4. UDP: the plan payload is the FRAMED adapter (ADR-003) — the pump
|
||||
is unchanged; the codec lives at the substrate/pump boundary.
|
||||
|
||||
**The handler is substrate-agnostic by construction:** it cannot know
|
||||
whether the halves came from TCP, UDP, a unix socket, or an
|
||||
in-process pipe, and must not (AGENTS.md convention 7).
|
||||
|
||||
## Registration API (the spec surface)
|
||||
|
||||
```rust
|
||||
pub fn register_tunnel_openable(
|
||||
core: &ChannelCore, // the manager + policy pair
|
||||
registry: &ResourceRegistry, // assembly-owned: (resource, substrate) -> backing
|
||||
on_registry: &Arc<OperationRegistry>, // the session's dispatch registry
|
||||
// (the per-session fork per alkcall ADR-047 §4
|
||||
// amendment, 2026-09-03 — NOT the connection
|
||||
// overlay; Layer-2-registered open ops resolve
|
||||
// NOT_FOUND, review 004 F-01)
|
||||
auth: AuthContext, // the install-time context (per-call overlay is upstream's)
|
||||
dial: DialFn, // substrate halves function (ADR-004; `local` feature or assembly)
|
||||
) -> Result<(), String>
|
||||
```
|
||||
|
||||
- `ResourceRegistry` (assembly construct, OQ-TN-11): maps
|
||||
`(resource, substrate)` → backing. The POCs' `HashMap` shape is the
|
||||
candidate; the collision domain is the producer's registry
|
||||
(ADR-001 — two producers on one connection may expose the same
|
||||
resource name independently).
|
||||
- The scope constant `TUNNEL_OPEN_SCOPE = "tunnel:open"`; the open-op
|
||||
spec builder is public so assembly layers can compose variants
|
||||
(e.g. extra ACL fields) without forking the wire shape.
|
||||
- The pump handler factory is public for the same reason.
|
||||
|
||||
## Access control posture
|
||||
|
||||
Tunnels reach local networks — the open gate is the security boundary
|
||||
(OQ-TN-08):
|
||||
|
||||
- The registry runs `AccessControl` before the establisher (the ACL
|
||||
rides `register_openable`; free via alkcall).
|
||||
- `TUNNEL_OPEN_SCOPE` is the base gate; the assembly layer MAY add
|
||||
resource-scoped checks via the establisher (ownership on the
|
||||
resource name) — the protocol provides the seam, not the policy.
|
||||
- No target allowlists, no tunnel-specific policy machinery in v1 —
|
||||
the far side owns the resource (OQ-TN-08 resolution); discovery is
|
||||
the ACL-filtered ops listing.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- **OQ-TN-11**: resource naming collision domain + lifecycle
|
||||
(partially resolved — the per-producer registry is the leading
|
||||
candidate)
|
||||
- **OQ-TN-14**: unix/stdio substrate placement (open — backend module
|
||||
task, not a wire question)
|
||||
|
||||
## References
|
||||
|
||||
- [wire.md](wire.md) (the open op's wire surface),
|
||||
[overview.md](overview.md) (module map)
|
||||
- Forward POC `docs/research/poc-summary.md`; reverse POC
|
||||
`docs/research/reverse-poc-summary.md` (both producer shapes ran)
|
||||
- alkcall ADR-047/049 (open ops + establishment), ADR-050 (`pump_bidi`),
|
||||
ledger CF-005/CF-006 (identity precedence + per-call opener)
|
||||
Reference in New Issue
Block a user