This is a Redis starter template for JS and Node, adapted for a matchmaking and game session state demo using:

• Express
• Redis
• Docker

Requirements

• bun
• docker

Getting started

Copy the example environment file:

cp .env.example .env

The app uses Redis on redis://localhost:6379 by default when you run it outside Docker.

Start the stack with Docker:

bun docker

The API listens on http://localhost:8080.

API routes

The matchmaking service exposes these routes:

1. POST /api/matchmaking/modes/:mode/join - Join the queue for a mode and skill level
2. GET /api/matchmaking/modes/:mode/queue?skill=<skill> - Inspect the queue for a skill bucket
3. GET /api/matchmaking/rooms/:roomId - Read a room by ID
4. PATCH /api/matchmaking/rooms/:roomId - Update room status and winner

Running tests

Run the full test suite with:

bun test

The tests start Redis through Docker, reset the database between cases, and exercise the matchmaking queue and room lifecycle.

Running locally outside Docker

bun install
bun dev

Implementation notes

• Queue membership is stored in Redis sorted sets, grouped by mode and skill bucket.
• Player state is stored in Redis hashes while the player waits in queue.
• The join-and-match flow uses WATCH and MULTI for optimistic locking so concurrent requests cannot double-match players.
• Matched rooms are stored as JSON strings with a TTL so stale rooms expire automatically.
• Room updates use WATCH and MULTI to guard against concurrent patches.
• Room lifecycle events are published to Redis Pub/Sub on matchmaking:events.

Learn more

• Redis documentation
• Redis sorted sets
• Redis hashes
• Redis Pub/Sub
• Redis transactions