glm-5.3-flash
69498b79cc
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
101 lines
3.5 KiB
Markdown
101 lines
3.5 KiB
Markdown
---
|
|
id: tunnels/params
|
|
name: TunnelParams + open-op spec (schema, scope gate, constants)
|
|
status: pending
|
|
depends_on: [tunnels/crate-init]
|
|
scope: narrow
|
|
risk: low
|
|
impact: component
|
|
level: implementation
|
|
tags: [wire, params, open-op]
|
|
---
|
|
|
|
## Description
|
|
|
|
Implement `src/params.rs` per ADR-001 + wire.md §The Open Op: the
|
|
`TunnelParams` wire type, the `Substrate` discriminator, and the open-op
|
|
`OperationSpec` builder. This is the wire-stable surface (one-way door) —
|
|
exact conformance to the ADR is the point.
|
|
|
|
### Types
|
|
|
|
```rust
|
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct TunnelParams {
|
|
pub resource: String,
|
|
pub substrate: Substrate,
|
|
}
|
|
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "lowercase")]
|
|
pub enum Substrate { Tcp, Udp, Unix }
|
|
```
|
|
|
|
- `deny_unknown_fields` is the loud-rejection posture (ADR-001: unknown
|
|
fields fail schema validation, never silently ignored).
|
|
- `Substrate::Unix` is included in the type (the wire enum per ADR-001)
|
|
but NOT in the open-op schema's enum list v1 (`["tcp", "udp"]`) until
|
|
OQ-TN-14 resolves — an older producer rejecting a newer substrate is
|
|
the SSH "unknown channel type" posture; the schema list is the
|
|
authoritative gate. Document this asymmetry in the type docs (type
|
|
extensible, schema conservative).
|
|
|
|
### The open-op spec (in producer.rs or params.rs — put it where
|
|
`tunnels/producer-open-op` can consume; the spec builder lives in
|
|
params.rs per the module map, producer.rs re-exports)
|
|
|
|
```rust
|
|
pub const OP_TUNNEL_OPEN: &str = "channels/tunnel/sub";
|
|
pub const TUNNEL_ALPN: &str = "alk/tunnel";
|
|
pub const TUNNEL_OPEN_SCOPE: &str = "tunnel:open";
|
|
|
|
pub fn tunnel_open_spec() -> OperationSpec
|
|
```
|
|
|
|
- `OperationType::Sub`; `Visibility::External`; channel-open marker
|
|
`ChannelOpenSpec::new(TUNNEL_ALPN)`.
|
|
- `input_schema`: `{resource: string (required), substrate: string enum
|
|
["tcp","udp"] (required)}` — JSON Schema Draft shape as the POCs used.
|
|
- `output_schema`: `{channel_id: integer > 0}`.
|
|
- `AccessControl.required_scopes: [TUNNEL_OPEN_SCOPE]` (ADR-006).
|
|
- `description`: a one-line human hint (round-trips through discovery;
|
|
the spec's SHOULD).
|
|
|
|
### Error surface
|
|
|
|
`src/error.rs`: `TunnelError` (thiserror) covering the codec + session
|
|
errors (filled incrementally by later tasks); plus the re-export of
|
|
`alkcall::channels::client::ChannelOpenError` and an
|
|
`establishment_reason(&CallError) -> Option<&str>` helper
|
|
(ADR-049 §4 surface; the POC consumer's shape).
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `TunnelParams` round-trips serde; unknown fields rejected
|
|
- [ ] `tunnel_open_spec()` matches wire.md §The Open Op exactly (op id,
|
|
type, ALPN marker, schemas, ACL, description)
|
|
- [ ] Schema validation test: valid params pass; missing fields,
|
|
unknown fields, unknown substrate values all fail
|
|
- [ ] `establishment_reason` maps `channel:open_failed` details.reason
|
|
(POC-pinned shapes: `unknown_resource`, `dial_failed`,
|
|
`resource_shortage`)
|
|
- [ ] Unit tests cover the serde + schema shapes
|
|
- [ ] wasm32 check passes
|
|
|
|
## References
|
|
|
|
- docs/architecture/decisions/001-open-params-layout.md
|
|
- docs/architecture/wire.md §The Open Op
|
|
- docs/architecture/decisions/006-access-control-posture.md
|
|
- POC reference: `/workspace/alktunnels-udp-poc/src/params.rs` +
|
|
`producer.rs::tunnel_open_spec` (the shape, with `deny_unknown_fields`
|
|
added)
|
|
|
|
## Notes
|
|
|
|
> Agent fills during implementation.
|
|
|
|
## Summary
|
|
|
|
> Agent fills this on completion. |