Files

T

glm-5.3-flash a0f939c6df review: phase-gate review 001 — spec conformance of the v1 implementation

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.

2026-09-08 10:58:11 +00:00

2.1 KiB

Raw Blame History

alktunnels

Arbitrary bidirectional tunnels over 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 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:

{ "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

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

2.1 KiB Raw Blame History