WebSocket Gateway

Project roadmap

1. 01

   Design the gateway

   ~2h

   Write DESIGN.md: how clients authenticate (a JWT in the first message or a query parameter, checked before anything else), the message protocol (subscribe, unsubscribe, event, ack and error), the topic permission rules (a user may subscribe to user:<own id> and orders they own), how backend services publish events (an HTTP endpoint with a service key), how events reach clients on other instances (Redis pub/sub), and how missed events are replayed (a short history per topic with event ids). Done when: DESIGN.md covers auth, protocol, permissions, routing and replay.

2. 02

   Accept and authenticate connections

   ~2h

   Build the gateway with Node.js and the ws package: verify the JWT (with the jose library) on connection, closing unauthenticated connections with a clear code, and keep each connection's user and subscriptions. Validate every incoming message (for example with Zod) and limit message size and rate per connection. Send pings to detect dead connections. Done when: authenticated clients connect, and others are refused.

3. 03

   Handle subscriptions and publishing

   ~2h

   Implement subscribe and unsubscribe with permission checks (answering with an error for forbidden topics), and a POST /publish endpoint for backend services that delivers an event to every connection subscribed to its topic on this instance. Give each event an id and keep the last events per topic in Redis (a capped list or stream). Done when: a service publishing to a topic reaches only the subscribed, authorized clients.

4. 04

   Route events across instances

   ~2h

   Publish every event to Redis pub/sub, and have each instance subscribe to the Redis channels for the topics its clients follow (subscribing and unsubscribing as clients come and go), delivering events locally. Done when: with two gateway instances, a client on one receives events published through the other.

5. 05

   Replay missed events and protect against slow clients

   ~2h

   When a client subscribes with the last event id it saw, send the missed events from the topic's history before live ones. Give each connection a bounded send buffer (checking ws's bufferedAmount) and disconnect clients that fall too far behind, so they don't use unlimited memory. Done when: a client that reconnects after a short break receives the missed events once, and a deliberately slow client is disconnected.

6. 06

   Build a demo client and load test

   ~2h

   Build a small React app that logs in (getting a test JWT), connects, subscribes to topics, shows events live, and reconnects automatically with increasing waits. Load test three instances behind nginx on your own machine with thousands of simulated clients and record delivery latency and throughput in README.md. Done when: the demo works across instances, and README.md shows the load test results.

7. 07

   Test it

   ~2h

   Write tests that start two gateway instances and a Redis (Testcontainers or a local one): authentication failures, permission checks, delivery across instances, replay without duplicates, message validation and rate limits, and the slow client protection. Done when: all tests pass.

Resources

• Docsws: Node.js WebSocket library
• Docsjose (JWT for JavaScript)
• DocsRedis pub/sub
• DocsMDN: the WebSocket API
• DocsNGINX: WebSocket proxying