Rust WebSocket Server (Rust-WSS)

A modern, memory-safe rewrite of the original Qt/C++ WebSocket server in async Rust 2021.
It terminates TLS on port 443, preserves the original routing semantics, and adds first-class observability & performance guarantees.

---

✨ Feature Highlights

• Secure transport – tokio-rustls + tokio-tungstenite
• Connection ledger – ConnectionInfo stored in an Arc<RwLock<HashMap<…>>>
• Rich routing helpers – broadcast, unicast, room & app-scoped messaging
• JWT authentication – token in Sec-WebSocket-Protocol
• Observability – tracing spans & Prometheus metrics
• Graceful shutdown – broadcast server-shutdown, close code 1001
• Zero unsafe – compiles with #![forbid(unsafe_code)]
• Lean RAM footprint – ≤ 30 MB for 10 k idle sockets

---

🚀 Quick-Start

1. Prerequisites

• Rust 1.73+ (rustup update stable)
• A TLS certificate (self-signed for local testing)
• make, curl, and (optionally) docker for CI parity

2. Generate a self-signed cert

mkdir cert
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout cert/key.pem -out cert/cert.pem -subj "/CN=localhost"

3. Run the server

export WSS_CERT=cert/cert.pem
export WSS_KEY=cert/key.pem
export RUST_LOG=info
cargo run --release
# → 0.0.0.0:443 (wss)

4. JavaScript client snippet

const jwt = "<signed JWT>";                         // Auth token
const ws  = new WebSocket("wss://localhost/", jwt); // Sent as Sec-WebSocket-Protocol

ws.onopen = () => ws.send(JSON.stringify({ type: "WhoAmI" }));

ws.onmessage = ({ data }) => {
  const msg = JSON.parse(data);
  if (msg.system === "server-shutdown") ws.close();
  console.log("incoming:", msg);
};

// Example broadcast to current room
function sendChat(text) {
  ws.send(JSON.stringify({
    type: "Broadcast2Room",
    payload: { text }
  }));
}

---

🗂️ Repository Layout

.
├── Cargo.toml              # crate manifest & dependencies
├── src/
│   ├── main.rs             # binary entry point
│   ├── tls.rs              # TLS loader/helpers
│   ├── connection.rs       # ConnectionInfo ledger
│   ├── router.rs           # routing helpers
│   ├── metrics.rs          # Prometheus collectors
│   ├── shutdown.rs         # graceful shutdown handler
│   └── errors.rs           # error types via thiserror
├── .cursorrules            # build & style policy for Cursor
├── todo.md                 # development roadmap
└── README.md               # this file

---

🧑‍💻 Development

rustup override set stable
cargo clippy --all-targets --all-features -- -D warnings
cargo test

Hot-reloading

cargo watch -x 'run --release'

---

📜 License

MIT — © 2023-present, Rust-WSS contributors.