From d5a5fd2d64102665ca87bcee8c4dcb5b83a2eca3 Mon Sep 17 00:00:00 2001 From: devbeni Date: Fri, 19 Sep 2025 19:03:57 +0200 Subject: [PATCH] docs: update README to enhance project overview and clarify Socket.IO implementation details --- README.md | 157 ++++++++++++++++++++++-------------------------------- 1 file changed, 64 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 54d59b6..3e1eef6 100644 --- a/README.md +++ b/README.md @@ -1,99 +1,70 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +### Why this project exists -## Getting Started +[Funcode.hu](https://funcode.hu/en) is a terrible website that handles queuing systems poorly. Their queue implementation is unreliable, crashes frequently, and provides a frustrating user experience during high-traffic events. This project demonstrates how to properly implement a robust, real-time queue system that can handle concurrent users efficiently. -First, run the development server: +### How it works -```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev +**Core Architecture:** +- When an event reaches a concurrency threshold (configurable, default 100 users), the server enables a queue for that event +- Users connect via WebSocket (Socket.IO) for real-time communication +- When queueing is active, users are placed in a FIFO (First In, First Out) queue +- The server grants access (issues a signed JWT token) to up to CONCURRENT_ACTIVE users (default 50) at a time +- JWT tokens are valid for a short period (default 15 minutes). When expired, the server revokes access and grants tokens to the next users in queue +- Users must authenticate with their JWT token to make purchase API calls + +**Socket.IO Implementation Details:** + +1. **Connection Flow:** + ``` + Client connects → Socket.IO handshake → emit 'join_event' → Server adds to queue/grants access + ``` + +2. **Event Types:** + - `join_event`: Client joins an event queue + - `queue_update`: Server sends position, wait time, active user count + - `granted`: Server grants access with JWT token + - `revoked`: Server revokes access (token expired) + - `disconnect`: Client leaves, removed from all queues + +3. **Queue Management:** + - In-memory queue per event ID for fast access + - MySQL persistence for queue positions and active sessions + - Automatic queue activation when threshold reached + - Real-time updates to all connected clients + +4. **Token Management:** + - JWT tokens signed with server secret + - Tokens include socket ID and event ID + - Database tracking of active sessions with expiration times + - Automatic cleanup of expired tokens + +**Technical Flow Diagram:** +``` +┌─────────────┐ WebSocket ┌──────────────┐ MySQL ┌─────────────┐ +│ Browser │ ◄──────────────► │ Socket.IO │ ◄──────────► │ Database │ +│ │ │ Server │ │ │ +│ • Queue UI │ │ • Queue Mgmt │ │ • Events │ +│ • Token │ │ • JWT Issue │ │ • Tickets │ +│ • Purchase │ │ • Real-time │ │ • Orders │ +└─────────────┘ └──────────────┘ └─────────────┘ + │ │ + │ HTTP API │ + └────────────────────────────────┘ + Purchase Requests ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +**Why it's better than Funcode.hu:** +- ✅ Real-time updates vs. page refreshes +- ✅ Persistent queue positions in database vs. memory-only +- ✅ JWT-based authentication vs. unreliable session management +- ✅ Graceful handling of disconnections vs. losing queue position +- ✅ Configurable thresholds vs. hard-coded limits +- ✅ Modern, responsive UI vs. outdated interface +- ✅ Transparent queue position and wait times vs. vague "please wait" -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. - -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. - -## Learn More - -To learn more about Next.js, take a look at the following resources: - -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. - -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! - -## Deploy on Vercel - -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. - -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. - -## Queue / Ticketing demo (WebSocket + JWT) - -This repository contains a minimal demo of a queue system for high-concurrency ticket sales. Key ideas: - -- When an event reaches a concurrency threshold (e.g. 100 users), the server enables a queue for that event. -- Users connect via WebSocket (Socket.IO). When queueing is active they are placed in a FIFO queue. -- The server grants access (issues a signed JWT) to up to CONCURRENT_ACTIVE users (default 50) at a time. -- The JWT is valid for a short period (default 15 minutes). When it expires the server revokes access and grants the next users in queue. -- The client uses the JWT to authenticate purchase API calls. - -Files added in this demo: - -- `app/api/socketio/route.js` — Next.js App Router API route that initializes the Socket.IO server, queue logic and JWT issuance with MySQL persistence. -- `app/api/events/route.js` — API for fetching event and ticket information from MySQL. -- `app/api/purchase/route.js` — API for processing ticket purchases with JWT verification. -- `database/schema.sql` — MySQL database schema with tables for events, tickets, queue, orders, and active sessions. -- `.env.example` — example environment variables for the queue system and MySQL connection. -- `app/page.tsx` — modern, responsive client UI that connects via Socket.IO and provides a full ticket purchasing experience. - -Important notes and limitations: - -- The server implementation in `server/index.js` is an in-memory demo. For production use a shared, persistent store (Redis) for queue/locks and a robust MySQL schema if you need persistence. -- Add authentication, rate-limiting, and persistent sessions before using in production. - -Running locally - -1. **Setup MySQL Database:** - ```sql - -- Execute the schema in database/schema.sql - mysql -u root -p < database/schema.sql - ``` - -2. **Environment Configuration:** - Copy `.env.example` to `.env` and configure your settings: - ```bash - cp .env.example .env - ``` - Update the MySQL connection details and JWT secret. - -3. **Install Dependencies:** - ```powershell - pnpm install - ``` - -4. **Start the Application:** - ```powershell - pnpm dev - ``` - -5. **Access the Application:** - Open `http://localhost:3000` - the page will automatically: - - Initialize the Socket.IO server via `/api/socketio` - - Connect to the queue system on port 4000 - - Load event and ticket data from MySQL - - Provide a modern, responsive ticket purchasing interface - -Next steps / improvements - -- Move queue state to Redis (ZSET) to support multiple server instances. -- Persist issued tokens and sessions in DB to support revocation and auditing. -- Add server-side validation of the JWT on purchase endpoints. -- Add tests around queue promotion logic and token expiration. +**Production Considerations:** +- Use Redis for distributed queue state across multiple server instances +- Implement proper user authentication and rate limiting +- Add comprehensive logging and monitoring +- Set up load balancing for Socket.IO with sticky sessions +- Add automated cleanup of stale connections and expired tokens \ No newline at end of file