glm-5.3-flash
50909ab1ca
- src/{params,wire,producer,consumer,error}.rs skeletons with module
docs per overview.md §Module Map; lib.rs crate docs + re-exports
- constants in params.rs (OP_TUNNEL_OPEN, TUNNEL_ALPN,
TUNNEL_OPEN_SCOPE) + establishment_reason helper (delegates to
alkcall 0.7.0's ChannelOpenError::establishment_reason)
- MAX_DATAGRAM_LEN (65535) in wire.rs (ADR-003's frame-time bound)
- async-trait dropped: skeleton confirms no trait (ADR-004)
Verified: cargo check, clippy --all-targets -D warnings (native +
wasm32), fmt --check, test, wasm32 check — all clean
112 lines
4.5 KiB
Markdown
112 lines
4.5 KiB
Markdown
---
|
|
id: tunnels/crate-init
|
|
name: Initialize the alktunnels module skeleton (params, wire, producer, consumer, error)
|
|
status: completed
|
|
depends_on: [architecture/oq-promotion-sync]
|
|
scope: narrow
|
|
risk: low
|
|
impact: project
|
|
level: implementation
|
|
tags: [scaffold, crate-init]
|
|
---
|
|
|
|
## Description
|
|
|
|
Convert the alktunnels scaffold crate into the real module skeleton per
|
|
`docs/architecture/overview.md` §Module Map. The crate already exists
|
|
(Cargo.toml with alkcall 0.7.0, the wasm-clean tokio subset, licenses,
|
|
`lib.rs` stub); this task adds the module structure the subsequent tasks
|
|
fill in.
|
|
|
|
### Module skeleton
|
|
|
|
```rust
|
|
// src/lib.rs
|
|
//! alktunnels — arbitrary bidirectional tunnels over alkcall channels.
|
|
//! (crate docs per overview.md §What — the two-paragraph shape)
|
|
|
|
pub mod error;
|
|
pub mod params;
|
|
pub mod wire;
|
|
|
|
pub mod producer;
|
|
pub mod consumer;
|
|
|
|
// Public API surface: re-exports filled in by subsequent tasks (convention 16).
|
|
```
|
|
|
|
- `src/error.rs` — `TunnelError` (thiserror; convention 2) + the typed
|
|
open-error surface re-exported from alkcall (`ChannelOpenError`,
|
|
`establishment_reason`-shaped helper). Skeleton only; filled by
|
|
`tunnels/params` and `tunnels/consumer-session`.
|
|
- `src/params.rs` — `TunnelParams {resource, substrate}` +
|
|
`Substrate` enum (`tcp | udp | unix`) + `tunnel_open_spec()` builder +
|
|
`TUNNEL_OPEN_SCOPE`/`OP_TUNNEL_OPEN`/`TUNNEL_ALPN` constants. Skeleton
|
|
with type definitions; the schema builder + tests land in
|
|
`tunnels/params`.
|
|
- `src/wire.rs` — the codec module doc (ADR-003 summary + bast.md
|
|
pointer); skeleton for `frame_datagram`/`DatagramReader`/
|
|
`DatagramCodecError`, filled by `tunnels/wire-codec`.
|
|
- `src/producer.rs` — module doc (producer.md summary); skeleton for
|
|
`tunnel_open_spec` wiring, `register_tunnel_openable`, the establisher
|
|
shape, the pump handler — filled by `tunnels/producer-open-op` +
|
|
`tunnels/producer-listen`.
|
|
- `src/consumer.rs` — module doc (consumer.md summary); skeleton for
|
|
`TunnelSession` — filled by `tunnels/consumer-session`.
|
|
|
|
### Keep in place / verify
|
|
|
|
- Cargo.toml: alkcall 0.7.0 pin, the wasm-clean tokio subset, the empty
|
|
`[features]` table (the `local` feature is added by `tunnels/local-socket-halves`).
|
|
- `bytes`, `serde`, `serde_json`, `thiserror`, `tracing`, `futures` stay;
|
|
drop `async-trait` IF the skeleton confirms no trait is needed (ADR-004 —
|
|
it likely is not; note the decision in Summary if dropped).
|
|
- The default crate stays wasm-clean: `cargo check --target
|
|
wasm32-unknown-unknown` must pass at every task in this graph
|
|
(convention 4; the structural guard).
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] `src/lib.rs` declares `error`, `params`, `wire`, `producer`,
|
|
`consumer` with doc comments; public API re-exports listed (empty
|
|
bodies fine)
|
|
- [x] Every skeleton module compiles (`cargo check` clean)
|
|
- [x] `cargo clippy --all-targets -- -D warnings` clean
|
|
- [x] `cargo fmt --check` clean
|
|
- [x] `cargo check --target wasm32-unknown-unknown` passes
|
|
- [x] No comments in code beyond doc comments (convention 1)
|
|
|
|
## References
|
|
|
|
- docs/architecture/overview.md (module map, feature gates)
|
|
- docs/architecture/decisions/004-no-backend-trait.md (module placement)
|
|
- AGENTS.md conventions 1/2/4/15/16
|
|
|
|
## Notes
|
|
|
|
- All five skeleton modules created per the task's shapes, with module
|
|
docs pointing at the spec docs + ADRs and `tunnels/*` tasks that fill
|
|
them in.
|
|
- Constants placed early (`OP_TUNNEL_OPEN`, `TUNNEL_ALPN`,
|
|
`TUNNEL_OPEN_SCOPE` in params.rs — they are part of the wire surface,
|
|
not producer-only, so they live in the shared module per the module
|
|
map's "params.rs … + open-op input schema").
|
|
- `establishment_reason` is a thin delegation to
|
|
`ChannelOpenError::establishment_reason` (alkcall 0.7.0 has the
|
|
method upstream); the crate-level helper keeps the POC's free-fn
|
|
shape for consumers and re-exports the typed error.
|
|
- `MAX_DATAGRAM_LEN` (65535) placed in wire.rs — the one codec constant
|
|
ADR-003 pins regardless of the codec functions landing later.
|
|
- **`async-trait` dropped** per the task's IF: the skeleton confirms no
|
|
trait is needed (ADR-004 — halves functions, not traits);
|
|
`cargo check` passes without it.
|
|
|
|
## Summary
|
|
|
|
Module skeleton landed (error/params/wire/producer/consumer + lib.rs
|
|
docs + re-exports); Cargo.toml unchanged except `async-trait` dropped
|
|
(ADR-004 confirmation). Verified: `cargo check`, `cargo clippy
|
|
--all-targets -- -D warnings`, `cargo fmt --check`, `cargo test`,
|
|
`cargo check --target wasm32-unknown-unknown`,
|
|
`cargo clippy --target wasm32-unknown-unknown -- -D warnings` — all
|
|
clean. |