Merge pull request #39 from CS3219-AY2526Sem1/feature/matching-service-init

Feature/matching service init

Author: billyhoce

services/matching-service/.dockerignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+venv/
+.git
+.gitignore

services/matching-service/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+venv/
+.env

services/matching-service/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY ./app ./app
+
+EXPOSE 8000
+
+# Dev mode (reload)
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

services/matching-service/Makefile

@@ -0,0 +1,2 @@
+run:
+	uvicorn app.main:app --reload --port 8000

services/matching-service/README.md

@@ -0,0 +1,59 @@
+# Matching Service
+
+## Overview
+
+The **Matching Service** is responsible for pairing users in PeerPrep based on selected topic, difficulty, and programming language. It manages user queues, handles match creation, and communicates with other services such as:
+
+- **User Service**
+- **Question Service**
+- **Collaboration Service**
+
+This service is built using **FastAPI** and is designed to be **containerised using Docker**.
+
+---
+
+## Features
+
+- Join a match queue for a specific topic, difficulty, and programming language
+- Automatic peer matching from the queue
+- Cancel a queue request
+- Integration points for collaboration sessions
+- Health check endpoint for service monitoring
+
+---
+
+## API Testing with Postman
+
+A **Postman collection** is provided to test the Matching Service:
+
+1. Open Postman -> Import -> File -> `postman/PeerPrep.postman_collection.json`
+2. The collection includes:
+   - Join queue (`/match/request`)
+   - Cancel queue (`/match/cancel`)
+3. Update environment variables if needed (e.g., `url`)
+
+---
+
+## WebSocket Testing
+
+To test real-time events such as match found or timeout:
+
+1. Open Postman -> New -> WebSocket Request
+2. URL: `ws://localhost:8000/match/ws/{{user_id}}`
+3. Replace `{{user_id}}` with your test user
+4. Click **Connect**
+5. To simulate events:
+   - POST `/match/request` from **user 1** and **user 2** to trigger `match.found`
+   - POST `/match/request` to trigger `match.timeout` if no peer is found within 60 seconds
+
+---
+
+## Running the service
+
+### Using Make
+
+From the `matching-service` folder, run:
+
+```bash
+make run
+```

services/matching-service/app/__init__.py

@@ -0,0 +1,62 @@
+from app.models.match import MatchRequest, MatchResponse
+import uuid
+from app.core import queue
+import time
+import asyncio
+from app.core.websocket_manager import manager
+
+TIMEOUT_SECONDS = 60
+
+class MatchingService:
+
+    @staticmethod
+    async def join_queue(request: MatchRequest) -> MatchResponse:
+        difficulty = request.difficulty
+        topic = request.topic
+        language = request.language
+        user_id = request.user_id
+
+        peer_id = queue.dequeue_user(difficulty, topic, language)
+
+        # suitable match
+        if peer_id:
+            await manager.send_event(user_id, "match.found", {"peer_id": peer_id})
+            await manager.send_event(peer_id, "match.found", {"peer_id": user_id})
+
+            # TODO: Initialise collaboration session and assign question
+
+            return MatchResponse(success=True, peer_id=peer_id, message="Peer found")
+        else:
+            # no suitable match
+            queue.enqueue_user(difficulty, topic, language, user_id)
+            position = queue.get_queue_position(difficulty, topic, language, user_id)
+
+            return MatchResponse(
+                success=True,
+                message="Added to queue",
+                # queue_position=position
+            )
+        
+    @staticmethod
+    def cancel_queue(request: MatchRequest) -> MatchResponse:
+        removed = queue.remove_user(request.difficulty, request.topic, request.language, request.user_id)
+        if removed:
+            return MatchResponse(success=True, message="Removed from queue")
+        else:
+            return MatchResponse(success=False, message="User not in queue")
+
+    @staticmethod
+    async def check_timeouts(request: MatchRequest):
+        await asyncio.sleep(TIMEOUT_SECONDS)
+        position = queue.get_queue_position(request.difficulty, request.topic, request.language, request.user_id)
+
+        if position is not None:
+            queue.remove_user(request.difficulty, request.topic, request.language, request.user_id)
+            print(f"Timeout: Removed user {request.user_id} from queue after {TIMEOUT_SECONDS}")
+            
+            # send WebSocket event timeout
+            await manager.send_event(
+                request.user_id,
+                "match.timeout",
+                {"message": f"Timeout after {TIMEOUT_SECONDS} seconds, removed from queue"}
+            )

services/matching-service/app/core/__init__.py

@@ -0,0 +1,40 @@
+import redis
+import json
+import time
+
+r = redis.Redis(host="localhost", port=6379, db=0, decode_responses=True)
+
+def _queue_key(difficulty: str, topic: str, language: str) -> str:
+    return f"match_queue:{difficulty}:{topic}:{language}"
+
+def enqueue_user(difficulty: str, topic: str, language: str, user_id: str):
+    key = _queue_key(difficulty, topic, language)
+    # add to the end of the queue
+    r.rpush(key, user_id)
+    r.hset("match_timestamps", user_id, int(time.time()))
+
+def dequeue_user(difficulty: str, topic: str, language: str):
+    key = _queue_key(difficulty, topic, language)
+    # pop from the front (FIFO)
+    user_id = r.lpop(key)
+    if user_id:
+        r.hdel("match_timestamps", user_id)
+    return user_id
+
+def get_queue_position(difficulty: str, topic: str, language: str, user_id: str):
+    key = _queue_key(difficulty, topic, language)
+    queue = r.lrange(key, 0, -1)
+    try:
+        return queue.index(user_id) + 1
+    except ValueError:
+        return None
+    
+def remove_user(difficulty: str, topic: str, language: str, user_id: str):
+    key = _queue_key(difficulty, topic, language)
+    removed = r.lrem(key, 0, user_id)
+    r.hdel("match_timestamps", user_id)
+    return removed > 0
+
+def get_user_join_time(user_id: str):
+    ts = r.hget("match_timestamps", user_id)
+    return int(ts) if ts else None

services/matching-service/app/core/matching.py

@@ -0,0 +1,23 @@
+from typing import Dict
+from fastapi import WebSocket
+
+class ConnectionManager:
+    def __init__(self):
+        self.active_connections: Dict[str, WebSocket] = {}
+
+    async def connect(self, user_id: str, websocket: WebSocket):
+        await websocket.accept()
+        self.active_connections[user_id] = websocket
+
+    def disconnect(self, user_id: str):
+        self.active_connections.pop(user_id, None)
+
+    async def send_event(self, user_id: str, event: str, data: dict):
+        websocket = self.active_connections.get(user_id)
+        if websocket:
+            await websocket.send_json({
+                "event": event,
+                "data": data
+            })
+
+manager = ConnectionManager()