paseo-relay (Rust)

Rust rewrite of @getpaseo/relay (ported from upstream commit fd022bc).

The original is two things in one npm package; this workspace keeps them as two crates:

Crate	What it is	Who links it
crates/server (paseo-relay)	Native tokio relay server: an opaque, bidirectional WebSocket forwarder between a daemon and its clients.	deployed as a binary
crates/e2ee (paseo-relay-e2ee)	The E2EE channel — NaCl box (Curve25519 + XSalsa20-Poly1305), wire-compatible with the existing JS clients.	a Rust daemon

The relay never decrypts. server does not depend on e2ee.

Key decisions

• Native, not Cloudflare. The rewrite drops Durable Objects in favour of a single tokio process. This removes the entire serializeAttachment / hibernation-rehydration dance — a socket's identity is just its key in an in-memory map (crates/server/src/session.rs).
• v2 only. The legacy v1 protocol and the old JSON ping/pong keepalive are not ported.
• One scaling seam. All session state lives behind SessionRegistry. Today it is an in-memory map (single process). To scale out, put a sticky load balancer in front (hash on serverId, already in the URL) — the forwarding core does not change. A true backplane would reimplement only that one type.
• Frozen wire format is the contract. A Rust daemon interoperates with the existing JS browser client purely because crates/e2ee/src/wire.rs reproduces the byte layout and handshake. The browser client is not part of this rewrite.

Layout

crates/
  e2ee/      crypto.rs · channel.rs · wire.rs · base64.rs   + tests/parity.rs
  server/    main.rs · router.rs · session.rs · forward.rs · control.rs  + tests/e2e.rs

Build & test

cargo build
cargo test            # unit tests run; parity/e2e tests are #[ignore] (see below)
cargo run -p paseo-relay-server   # listens on RELAY_ADDR (default 0.0.0.0:8787)

GET /health → {"status":"ok"}; GET /ws?role=..&serverId=..&v=2 upgrades.

Implementation roadmap (next steps)

1. E2EE crypto parity — ✅ done. crypto_box::SalsaBox verified byte-identical to tweetnacl@1.0.3 (keygen, decrypt, and byte-exact ciphertext) in crates/e2ee/src/crypto.rs parity tests. Vectors regenerable via gen.cjs.
2. Encrypted channel (protocol) — ✅ done. ChannelCore (on_frame, buffered send, re-hello same-key/different-key handling) and the pure client_handshake / daemon_handshake functions in channel.rs, with full unit coverage (handshake, bidirectional messages, buffering/flush, plaintext-fatal, key-mismatch-fatal). The async transport driver is spec'd at the bottom of channel.rs and lands with the daemon (item 4).
3. Relay teardown cascades — ✅ done. Force-close via a Command::Close{code} on each writer task: replaced socket → 1008, last client gone → data socket 1001 + control disconnected, data socket drop → clients 1012. Covered by 5 real-WebSocket integration tests in crates/server/tests/e2e.rs (round-trip, buffering, all three cascades). The control-unresponsive nudge/reset timer is deliberately deferred — it is timer-based robustness, not core teardown; revisit once the daemon's keepalive behaviour is settled.
4. Rust daemon integration — ✅ done. crates/e2ee/src/driver.rs binds the pure core to any Stream + Sink<Frame> transport (connect_client / accept_daemon / channel + the run pump), with Frame::Close carrying fatal close codes. Proven two ways: an in-memory transport test in driver.rs, and a full-stack test (crates/server/tests/e2ee_relay.rs) where a Rust client and daemon exchange encrypted traffic through the live relay over real WebSockets.

Remaining (productionization, not core port)

• A paseo-relay daemon binary (control-socket discovery loop + a connection per client) reusing the driver.
• TLS / deployment / observability for the relay server.
• Optional: the control-unresponsive nudge/reset keepalive (deferred from item 3).