glm-5.3-flash
a0f939c6df
Findings + review doc: docs/reviews/001-implementation-review.md (the alkcall house pattern). Closes tunnels/review-core-crates and tunnels/review-impl. Findings: - U-1 [major, NOT fixed] — the local UDP adapter is not the framed adapter ADR-003 mandates: codec-framed bytes reach real targets, empty datagrams are EOF-shaped at the adapter (tunnel teardown), >8 KiB datagrams split, unframed target-initiated datagrams are dropped. Executable-pinned by real-socket probes (temporary test, deleted after the run). Remediation task: tunnels/fix-udp-framed-adapter. - C-1 [major, fixed] — AcceptQueue::pop lost wakeup in the check→register window (open op hangs to the establishment bound); fixed via the tokio notify_waiters contract (Notified created before the check each iteration) + multi-thread regression test. - N-4/N-5/N-7/N-8/N-9/N-10/N-11 [minor, fixed] — serialize TunnelParams in open_reverse_channel; stale doc ref; broken doc link; root re-exports (TunnelParams/Substrate/tunnel_open_spec/OP_TUNNEL_OPEN); README (publish dry-run was failing on the missing readme); harness comment; pump_against UDP framing doc note. - N-2 retracted by executable falsification (codec buffering is bounded by construction); N-6 non-finding with rationale. Verified: 63 tests default / 70 with --features local, 3x repeat-run clean both configs; clippy -D warnings (all-targets + wasm32); fmt; doc warning-free; wasm32 check; cargo publish --dry-run passes.
60 lines
2.1 KiB
Markdown
60 lines
2.1 KiB
Markdown
# alktunnels
|
|
|
|
Arbitrary bidirectional tunnels over [alkcall](https://crates.io/crates/alkcall)
|
|
channels: TCP, UDP, unix sockets, and other stream or datagram
|
|
substrates — in the `ssh -L` / `ssh -D` / `ssh -R` sense, without SSH.
|
|
|
|
A producer/consumer protocol crate riding alkcall channels the same
|
|
way [alktty](https://crates.io/crates/alktty) does (`alk/tty` is the
|
|
sibling precedent): the producer half registers the `alk/tunnel` open
|
|
op and pumps bytes between the channel and the substrate; the consumer
|
|
half is the typed session (`TunnelSession`) that opens tunnel channels
|
|
and owns teardown.
|
|
|
|
## A tunnel is a resource, not an address
|
|
|
|
Open-op params identify a produced resource + substrate:
|
|
|
|
```json
|
|
{ "resource": "postgres-primary", "substrate": "tcp" }
|
|
```
|
|
|
|
The producer owns the backing — the consumer never learns an address.
|
|
Rich addressing (SOCKS5 ATYP, per-datagram remotes) enters only
|
|
through the `-D`/dynamic composition path, inside the tunnel payload,
|
|
never in the wire (ADR-001).
|
|
|
|
- Wire format: `docs/architecture/wire.md` (+ the BAST document at
|
|
`docs/architecture/bast.md`)
|
|
- Open-op params: ADR-001; codec: ADR-003; ALPN: ADR-002
|
|
- Producer shapes: ADR-004; consumer session: ADR-005; ACL: ADR-006
|
|
- The full spec set: `docs/architecture/` (overview, wire, producer,
|
|
consumer, six ADRs, OQ tracker)
|
|
|
|
## Status
|
|
|
|
v0.1.0 — the v1 protocol implementation, Phase-2 complete (spec:
|
|
`docs/architecture/`; reviews: `docs/reviews/`). The wire surface
|
|
(params, ALPN, codec) is one-way-door stable from this point; the
|
|
API surface becomes ABI-stable at the first external consumer.
|
|
|
|
## Features
|
|
|
|
| Feature | Contents | wasm |
|
|
|---------|----------|------|
|
|
| *(default)* | params, wire codec, open-op spec, establisher shapes, `TunnelSession` — protocol only | yes |
|
|
| `local` | TCP/UDP/unix dial + listen helpers (real sockets) | no |
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
cargo test # default crate (wasm-clean)
|
|
cargo test --features local # + real-socket suites
|
|
cargo clippy --all-targets -- -D warnings
|
|
cargo fmt --check
|
|
cargo check --target wasm32-unknown-unknown # the wasm-clean guard
|
|
```
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0 |