tasks: Phase 2 decomposition — 12-task dependency graph for v1
tasks/architecture/: - oq-promotion-sync (planning): back-pointers from the phase-0 ledger + AGENTS.md to the promoted OQ tracker (the convergence checklist's final half) - oq-tn-14-tracker: the Safe-Exit external-trigger tracker task for OQ-TN-14 (unix/stdio placement; [external-trigger, deferred-oq], risk trivial, level research per the two-halves rule) tasks/tunnels/ (the implementation graph, 8 generations): - crate-init: module skeleton per overview.md's module map - params: TunnelParams + open-op spec (ADR-001 wire-stable surface) - wire-codec: frame_datagram/DatagramReader + the 8 POC-pinned test families (ADR-003) - producer-open-op: establisher (dial, plan flow R-01) + pump handler (pump_bidi inline R-02) + registration; POC-ported integration tests - consumer-session: TunnelSession (open/adopt, data planes, teardown matrix — ADR-005); generalizes the reverse POC's ReverseTunnel - producer-listen: the listen establisher + AcceptQueue contract (ADR-004 shape 2) - local-socket-halves: the local feature (TCP/UDP/unix halves functions; truncation fail-loud per OQ-TN-13; unix ships per OQ-TN-14's lean-yes, stdio deferred) - review-core-crates: review-injection point before the downstream tasks build on the high-risk producer/consumer shapes - end-to-end-suite: 6 suites / >=20 tests consolidating both POC suites against the public API (the spec's executable form) - review-impl: the phase-gate review (wire/API/conventions/docs sync; findings doc per the alkhttp/alkcall house pattern) Graph verified with taskgraph: 12 tasks valid, no cycles, 8 generations; critical path = oq-promotion-sync -> crate-init -> params -> wire-codec -> producer-open-op -> consumer-session -> review-core-crates -> review-impl; risk concentrated in the two session tasks (both POC-validated); parallel groups available at generations 1 and 6
This commit is contained in:
@@ -0,0 +1,125 @@
|
||||
---
|
||||
id: tunnels/producer-open-op
|
||||
name: Producer half — establisher (dial shape) + pump handler + register_tunnel_openable
|
||||
status: pending
|
||||
depends_on: [tunnels/params, tunnels/wire-codec]
|
||||
scope: broad
|
||||
risk: high
|
||||
impact: phase
|
||||
level: implementation
|
||||
tags: [producer, establisher, open-op, pump]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Implement `src/producer.rs` per producer.md: the dial-shape establisher,
|
||||
the substrate-agnostic pump handler, and the registration surface. This
|
||||
is the crate's core — the open op that both POCs validated (the forward
|
||||
POC's producer on the accept side; the reverse POC's worker on the
|
||||
connect side). Port from the REVERSE POC first
|
||||
(`/workspace/alktunnels-reverse-poc/src/producer.rs`) — it is the 0.6/0.7
|
||||
idiomatic shape (plan flow, no handoff) and its 16 tests are the
|
||||
reference suite.
|
||||
|
||||
### The establisher (dial shape — the listen shape is a separate task)
|
||||
|
||||
```rust
|
||||
pub type DialFn = Arc<
|
||||
dyn Fn(Substrate, &str) -> BoxFuture<'static, Result<TargetHandle, TunnelEstablishError>>
|
||||
+ Send + Sync,
|
||||
>;
|
||||
// TargetHandle: boxed halves (read: Box<dyn AsyncRead + Send + Sync + Unpin>, write: ...),
|
||||
// or the framed UDP adapter (the establisher wraps BEFORE returning the plan —
|
||||
// ADR-003's placement; the pump stays substrate-agnostic)
|
||||
```
|
||||
|
||||
- `tunnel_establisher(registry: ResourceRegistry, dial: DialFn,
|
||||
identity_witness: Option<...>) -> OpenEstablisher` — the assembly layer
|
||||
injects the substrate dial function (ADR-004); the establisher:
|
||||
1. Parses params (`TunnelParams` — schema-validated upstream, semantic
|
||||
parse here).
|
||||
2. Registry lookup `(resource, substrate)` → backing address —
|
||||
`unknown_resource` on miss (typed reason mapping per ADR-001's
|
||||
table).
|
||||
3. `dial(substrate, backing)` → the handle (the closure owns real
|
||||
socket code — behind `local` or assembly-constructed).
|
||||
4. UDP: wrap in the framed adapter (ADR-003) — `UdpHalf` + codec,
|
||||
truncation fail-loud (OQ-TN-13).
|
||||
5. Return `Ok(Establishment::new(Arc::new(handle)))` (R-01 plan flow).
|
||||
- `ResourceRegistry`: the assembly-owned
|
||||
`HashMap<(String, Substrate), String>` (POC shape; OQ-TN-11's
|
||||
collision domain) with `register`/`lookup` async methods.
|
||||
|
||||
### The pump handler
|
||||
|
||||
```rust
|
||||
pub fn make_tunnel_pump_handler() -> OpenHandler
|
||||
```
|
||||
|
||||
1. Downcast the plan to `TargetHandle` (`Arc::downcast` — error path:
|
||||
log + return; the birth-teardown telemetry catches it).
|
||||
2. `conn.accept_bi()` (yield-once).
|
||||
3. `pump_bidi(bidi, t_read, t_write)` — **awaited inline** (R-02: the
|
||||
returned `JoinHandle` tracks the data-plane lifetime; early return =
|
||||
teardown-at-birth). The handler is substrate-agnostic by
|
||||
construction — it must not know what the halves came from
|
||||
(ADR-004).
|
||||
|
||||
### Registration
|
||||
|
||||
```rust
|
||||
pub fn register_tunnel_openable(
|
||||
core: &ChannelCore,
|
||||
registry: &ResourceRegistry,
|
||||
on_registry: &Arc<OperationRegistry>, // the session's dispatch registry (ADR-047 §4 fork)
|
||||
auth: AuthContext,
|
||||
dial: DialFn,
|
||||
) -> Result<(), String>
|
||||
```
|
||||
|
||||
- Wires `tunnel_open_spec()` + the establisher + the pump via
|
||||
`register_openable_with_establisher` (timeout `None` = the 10s
|
||||
default).
|
||||
- Post-hoc registration is supported (W2): the dispatcher reads through
|
||||
the shared `Arc` per dispatch.
|
||||
|
||||
### Integration tests (the POC suite, ported)
|
||||
|
||||
Port the reverse POC's test topology (`harness.rs`: worker =
|
||||
`from_connection_with_serving` + `ChannelOperations::register_on` +
|
||||
post-hoc openable; hub = adapter + capturing install hook) into
|
||||
`tests/` with the `dial` closure standing in for real sockets
|
||||
(in-process duplex halves — no `local` feature needed). Cover:
|
||||
establishment success + typed errors (unknown_resource / dial_failed /
|
||||
FORBIDDEN / timeout-adjacent), the plan flow under same-resource
|
||||
concurrency, per-call opener identity (CF-006 witness),
|
||||
late-registration visibility, pump round-trip through `pump_bidi`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Establisher: typed reason mapping exact (ADR-001's table)
|
||||
- [ ] Pump handler: `pump_bidi` inline; no spawn-and-forget; no
|
||||
substrate types leak into the handler
|
||||
- [ ] `register_tunnel_openable` wires spec + establisher + pump +
|
||||
dial injection
|
||||
- [ ] Integration tests: forward AND reverse topology (the harness
|
||||
shapes from both POCs), ≥8 tests covering the above
|
||||
- [ ] Clippy/fmt clean; wasm32 check passes (dial closures are
|
||||
runtime-injected — the crate compiles without `local`)
|
||||
- [ ] `cargo test` green
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/producer.md (the normative shapes)
|
||||
- docs/architecture/decisions/001/003/004 (params, codec placement, no
|
||||
trait)
|
||||
- POC reference: `/workspace/alktunnels-reverse-poc/src/producer.rs` +
|
||||
`harness.rs` + `tests/tunnel_poc.rs` (the 0.7.0-idiomatic shapes)
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills during implementation.
|
||||
|
||||
## Summary
|
||||
|
||||
> Agent fills this on completion.
|
||||
Reference in New Issue
Block a user