devbeni/funcode2.0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README to enhance project overview and clarify Socket.IO implementation details

Browse Source
This commit is contained in:
devbeni
2025-09-19 19:03:57 +02:00
parent 2c5461b0e0
commit d5a5fd2d64
1 changed files with 64 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

157
README.md
View File

@@ -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