Skip to content

API Documentation

Jump to bottom
Francois edited this page Feb 6, 2026 · 10 revisions

REST API Documentation

Documentation complète des endpoints des services Gateway, Auth et Users du projet ft_transcendence.

Table des matières

📊 Vue d'ensemble des routes

Tableau général des endpoints

Service Méthode Endpoint Description Auth Status
Gateway GET / Message de bienvenue 🌍 Public ✅
Gateway GET /help Liste des routes disponibles 🌍 Public ✅
Gateway GET /health Health check du Gateway 🌍 Public ✅
Gateway GET /health/:name Health check d'un service spécifique 🌍 Public ✅
Gateway GET /healthAll Health check de tous les services 🌍 Public ✅
Auth GET /api/auth/ Status du service Auth 🌍 Public ✅
Auth GET /api/auth/health Health check 🌍 Public ✅
Auth POST /api/auth/register Inscription d'un nouvel utilisateur 🌍 Public ✅
Auth POST /api/auth/login Connexion utilisateur 🌍 Public ✅
Auth POST /api/auth/logout Déconnexion utilisateur 🔒 JWT ✅
Auth GET /api/auth/verify Vérification de token JWT 🔒 JWT ✅
Auth GET /api/auth/me Informations utilisateur courant 🔒 JWT 🚧
Auth POST /api/auth/2fa/setup Initialise la configuration 2FA 🔒 JWT ✅
Auth POST /api/auth/2fa/setup/verify Vérifie et active la 2FA 🔒 JWT ✅
Auth POST /api/auth/2fa/verify Vérifie un code 2FA au login 🔒 Temp ✅
Auth POST /api/auth/2fa/disable Désactive la 2FA 🔒 JWT ✅
Auth POST /api/auth/heartbeat Envoie un heartbeat pour rester en ligne 🔒 JWT ✅
Auth GET /api/auth/is-online/:name Vérifie si un utilisateur est en ligne 🔒 JWT ✅
Auth GET /api/auth/admin/users Liste tous les utilisateurs 🔒 Admin ✅
Auth PUT /api/auth/admin/users/:id Modifie un utilisateur 🔒 Admin ✅
Auth DELETE /api/auth/admin/users/:id Supprime un utilisateur 🔒 Admin ✅
Auth POST /api/auth/admin/users/:id/disable-2fa Désactive la 2FA d'un utilisateur 🔒 Admin ✅
Users GET /api/users/:id Récupère un profil par ID 🔒 JWT 👷
Users GET /api/users/username/:username Récupère un profil par username 🔒 JWT ✅
Users PATCH /api/users/avatar/:username Modifie l'avatar d'un utilisateur 🔒 JWT ✅
Users POST /users/ Crée un profil (route interne) 🔒 Internal ✅
Users GET /api/users/friends/:id Liste les amis d'un utilisateur 🔒 JWT 👷
Users POST /api/users/friends Envoie une demande d'ami 🔒 JWT ✅
Users PATCH /api/users/friends/:id/status Modifie le statut d'une amitié 🔒 JWT 👷
Users PATCH /api/users/friends/:id/nickname Modifie le surnom d'un ami 🔒 JWT 👷
Users DELETE /api/users/friends/:id Supprime une relation d'amitié 🔒 JWT ✅
Game POST /api/game/rl/reset Réinitialise une session 🔒 JWT 👷
Game POST /api/game/rl/step - 🔒 JWT 👷
Game POST /api/game/rl/state État d'une session de jeu 🔒 JWT 👷
AI POST /api/ai/predict Demande le mouvement de la raquette pour l'IA 🔒 JWT 👷

Légende :

  • 🌍 Public : Accessible sans authentification
  • 🔒 JWT : Nécessite un token JWT valide
  • 🔒 Temp : Nécessite un token temporaire (2FA)
  • 🔒 Admin : Nécessite un rôle administrateur
  • 🔒 Internal : Route interne entre services
  • ✅ Implémenté | 👷 En développement | 🚧 DEV ONLY

Statistiques

  • Total des routes : 36
  • Routes publiques : 7
  • Routes authentifiées : 25
  • Routes admin : 4
  • Services : 4 (Gateway, Auth, Users, AI)

🌐 Gateway Service

Le Gateway est le point d'entrée unique de l'application. Il route les requêtes vers les services appropriés et valide les JWT localement.

Public Routes

Méthode Endpoint Description Auth Rate Limit Status
GET / Message de bienvenue 🌍 Public Global ✅
GET /help Liste des routes disponibles 🌍 Public Global ✅

GET /

Response 200:

{
  "message": "Welcome to the Gateway API, check /help"
}

GET /help

Liste toutes les routes disponibles du Gateway avec leur méthode HTTP.

Response 200:

{
  "routes": {
    "public": {
      "/": "GET - Welcome message",
      "/help": "GET - This help message",
      "/healthAll": "GET - Health check all services",
      "/health/:name": "GET - Health check service by name",
      "/auth/*": "Proxied to Auth service",
      "/users/*": "Proxied to Users service",
      "/game/*": "Proxied to Game service",
      "/block/*": "Proxied to Blockchain service"
    }
  }
}

Health Check Routes

Méthode Endpoint Description Auth Rate Limit Status
GET /health Health check du Gateway 🌍 Public Global ✅
GET /health/:name Health check d'un service spécifique 🌍 Public Global ✅
GET /healthAll Health check de tous les services 🌍 Public Global ✅

GET /health

Vérifie la santé du Gateway lui-même.

Response 200:

{
  "status": "healthy",
  "service": "gateway",
  "timestamp": "2026-01-27T12:00:00Z"
}

GET /health/:name

Vérifie la santé d'un service spécifique.

URL Parameters:

  • name (string) : Nom du service (auth, users, game, block)

Response 200:

{
  "status": "healthy",
  "service": "auth",
  "timestamp": "2026-01-27T12:00:00Z"
}

Erreurs possibles:

  • 404 Not Found - Service inconnu
  • 503 Service Unavailable - Service injoignable

GET /healthAll

Vérifie la santé de tous les services enregistrés.

Response 200:

{
  "gateway": {
    "status": "healthy",
    "timestamp": "2026-01-27T12:00:00Z"
  },
  "auth": {
    "status": "healthy",
    "timestamp": "2026-01-27T12:00:00Z"
  },
  "users": {
    "status": "healthy",
    "timestamp": "2026-01-27T12:00:00Z"
  },
  "game": {
    "status": "healthy",
    "timestamp": "2026-01-27T12:00:00Z"
  },
  "block": {
    "status": "healthy",
    "timestamp": "2026-01-27T12:00:00Z"
  }
}

🔐 Auth Service

Service d'authentification gérant les utilisateurs, JWT, 2FA et statuts en ligne.

Authentication Routes

Méthode Endpoint Description Auth Rate Limit Status
GET /api/auth/ Status du service Auth 🌍 Public Global ✅
GET /api/auth/health Health check 🌍 Public Global ✅
POST /api/auth/register Inscription d'un nouvel utilisateur 🌍 Public 5/5min (prod), 100/5min (dev) ✅
POST /api/auth/login Connexion utilisateur 🌍 Public 5/5min (prod), 100/5min (dev) ✅
POST /api/auth/logout Déconnexion utilisateur 🔒 JWT Global ✅
GET /api/auth/verify Vérification de token JWT 🔒 JWT Global ✅
GET /api/auth/me Informations utilisateur courant 🔒 JWT Global 🚧 DEV ONLY

GET /api/auth/

Response 200:

{
  "message": "Auth service is running"
}

GET /api/auth/health

Response 200:

{
  "status": "healthy"
}

POST /api/auth/register

Crée un nouveau compte utilisateur.

Rate Limit: 5 requêtes/5min (prod), 100/5min (dev)

Request Body:

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "SecurePass123!"
}

Validation:

  • username: 4-20 caractères alphanumériques (_- autorisés), pattern: /^[a-zA-Z0-9_]+$/
  • email: Format email valide, max 100 caractères
  • password: Min 8 caractères, max 100 caractères, au moins 1 majuscule, 1 minuscule, 1 chiffre

Response 201:

{
  "success": true,
  "message": "User registered successfully",
  "userId": 42
}

Erreurs possibles:

  • 400 Bad Request - Données invalides ou manquantes
  • 409 Conflict - Username ou email déjà utilisé
  • 429 Too Many Requests - Rate limit dépassé

POST /api/auth/login

Authentifie un utilisateur et retourne un JWT.

Rate Limit: 5 requêtes/5min (prod), 100/5min (dev)

Request Body:

{
  "username": "john_doe",
  "password": "SecurePass123!"
}

Ou avec email:

{
  "email": "john@example.com",
  "password": "SecurePass123!"
}

Response 200 (Sans 2FA):

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": 42,
  "username": "john_doe",
  "require2FA": false
}

Response 200 (Avec 2FA activé):

{
  "success": true,
  "require2FA": true,
  "tempToken": "temporary_token_for_2fa_verification",
  "message": "2FA code required"
}

Erreurs possibles:

  • 400 Bad Request - Données manquantes ou invalides
  • 401 Unauthorized - Identifiants incorrects
  • 429 Too Many Requests - Rate limit dépassé

POST /api/auth/logout

Déconnecte l'utilisateur et invalide le token.

Headers:

Authorization: Bearer <token>

Response 200:

{
  "success": true,
  "message": "Logged out successfully"
}

GET /api/auth/verify

Vérifie la validité d'un token JWT.

Headers:

Authorization: Bearer <token>

Response 200:

{
  "valid": true,
  "userId": 42,
  "username": "john_doe",
  "role": "user"
}

Erreurs possibles:

  • 401 Unauthorized - Token invalide ou expiré

GET /api/auth/me

Retourne les informations de l'utilisateur connecté.

⚠️ DEV ONLY - À supprimer en production

Headers:

Authorization: Bearer <token>

Response 200:

{
  "userId": 42,
  "username": "john_doe",
  "email": "john@example.com",
  "role": "user",
  "twoFactorEnabled": true,
  "createdAt": "2026-01-15T10:30:00Z"
}

2FA Routes

Méthode Endpoint Description Auth Rate Limit Status
POST /api/auth/2fa/setup Initialise la configuration 2FA 🔒 JWT 5/5min (prod), 100/5min (dev) ✅
POST /api/auth/2fa/setup/verify Vérifie et active la 2FA 🔒 JWT 5/5min (prod), 100/5min (dev) ✅
POST /api/auth/2fa/verify Vérifie un code 2FA au login 🔒 Temp Token 5/5min (prod), 100/5min (dev) ✅
POST /api/auth/2fa/disable Désactive la 2FA 🔒 JWT Global ✅

POST /api/auth/2fa/setup

Génère un secret TOTP et un QR code pour configurer l'authentification à deux facteurs.

Rate Limit: 5 requêtes/5min (prod), 100/5min (dev)

Headers:

Authorization: Bearer <token>

Response 200:

{
  "success": true,
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "manualEntryKey": "JBSW Y3DP EHPK 3PXP"
}

Note: Le secret n'est pas encore sauvegardé en base. Il faut appeler /2fa/setup/verify avec un code valide pour activer la 2FA.

Configuration TOTP:

  • Window: ±1 (±30 secondes)
  • Step: 30 secondes
  • Digits: 6
  • Algorithm: SHA1 (standard TOTP)

POST /api/auth/2fa/setup/verify

Vérifie le code TOTP et active la 2FA pour l'utilisateur.

Rate Limit: 5 requêtes/5min (prod), 100/5min (dev)

Headers:

Authorization: Bearer <token>

Request Body:

{
  "token": "123456",
  "secret": "JBSWY3DPEHPK3PXP"
}

Response 200:

{
  "success": true,
  "message": "2FA activated successfully",
  "backupCodes": [
    "AB12-CD34-EF56",
    "GH78-IJ90-KL12",
    "MN34-OP56-QR78",
    "ST90-UV12-WX34",
    "YZ56-AB78-CD90"
  ]
}

Erreurs possibles:

  • 400 Bad Request - Code invalide ou expiré
  • 409 Conflict - 2FA déjà activée

POST /api/auth/2fa/verify

Vérifie le code 2FA après un login avec 2FA activée.

Rate Limit: 5 requêtes/5min (prod), 100/5min (dev)

Headers:

Authorization: Bearer <tempToken>

Request Body:

{
  "token": "123456"
}

Response 200:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": 42,
  "username": "john_doe"
}

Erreurs possibles:

  • 400 Bad Request - Code invalide
  • 401 Unauthorized - Temp token invalide ou expiré
  • 429 Too Many Requests - Trop de tentatives

POST /api/auth/2fa/disable

Désactive l'authentification à deux facteurs.

Headers:

Authorization: Bearer <token>

Request Body:

{
  "password": "SecurePass123!"
}

Response 200:

{
  "success": true,
  "message": "2FA disabled successfully"
}

Erreurs possibles:

  • 400 Bad Request - Mot de passe requis
  • 401 Unauthorized - Mot de passe incorrect

User Status Routes

Méthode Endpoint Description Auth Rate Limit Status
POST /api/auth/heartbeat Envoie un heartbeat pour rester "en ligne" 🔒 JWT 10/10s ✅
GET /api/auth/is-online/:name Vérifie si un utilisateur est en ligne 🔒 JWT 200/min (prod), 1000/min (dev) ✅

POST /api/auth/heartbeat

Envoie un signal heartbeat pour marquer l'utilisateur comme en ligne.

Rate Limit: 10 requêtes/10s

Headers:

Authorization: Bearer <token>

Response 200:

{
  "success": true,
  "online": true,
  "expiresIn": 30
}

Note: Le statut en ligne expire après 30 secondes sans heartbeat. Les clients doivent envoyer un heartbeat toutes les 20-25 secondes pour rester en ligne.

GET /api/auth/is-online/:name

Vérifie si un utilisateur est actuellement en ligne.

Rate Limit: 200 requêtes/min (prod), 1000/min (dev)

URL Parameters:

  • name (string) : Username de l'utilisateur

Headers:

Authorization: Bearer <token>

Response 200:

{
  "username": "john_doe",
  "online": true,
  "lastSeen": "2026-01-27T12:34:56Z"
}

Admin Routes

Toutes les routes admin nécessitent un rôle ADMIN et sont préfixées par /api/auth/admin.

⚠️ Les headers X-User-Id, X-User-Name et X-User-Role sont injectés automatiquement par le Gateway après validation du JWT.

Méthode Endpoint Description Auth Rate Limit Status
GET /api/auth/admin/users Liste tous les utilisateurs 🔒 Admin 50/min ✅
PUT /api/auth/admin/users/:id Modifie un utilisateur 🔒 Admin 20/min ✅
DELETE /api/auth/admin/users/:id Supprime un utilisateur 🔒 Admin 10/min ✅
POST /api/auth/admin/users/:id/disable-2fa Désactive la 2FA d'un utilisateur 🔒 Admin 10/min ✅

GET /api/auth/admin/users

Liste tous les utilisateurs de la plateforme.

Rate Limit: 50 requêtes/min

Headers:

Authorization: Bearer <admin_token>
X-User-Id: <admin_user_id>      (injecté par Gateway)
X-User-Name: <admin_username>   (injecté par Gateway)
X-User-Role: admin               (injecté par Gateway)

Query Parameters (optionnels):

  • page (number) : Numéro de page (défaut: 1)
  • limit (number) : Nombre de résultats par page (défaut: 50, max: 100)
  • search (string) : Recherche par username ou email
  • role (string) : Filtre par rôle (user, admin)

Response 200:

{
  "users": [
    {
      "id": 1,
      "username": "john_doe",
      "email": "john@example.com",
      "role": "user",
      "twoFactorEnabled": true,
      "createdAt": "2026-01-15T10:30:00Z",
      "lastLogin": "2026-01-27T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "pages": 3
  }
}

Erreurs possibles:

  • 401 Unauthorized - Token invalide
  • 403 Forbidden - Utilisateur non admin

PUT /api/auth/admin/users/:id

Modifie les informations d'un utilisateur.

Rate Limit: 20 requêtes/min

URL Parameters:

  • id (number) : ID de l'utilisateur

Headers:

Authorization: Bearer <admin_token>
X-User-Id: <admin_user_id>      (injecté par Gateway)
X-User-Name: <admin_username>   (injecté par Gateway)

Request Body:

{
  "username": "new_username",
  "email": "new@example.com",
  "role": "admin"
}

Response 200:

{
  "success": true,
  "user": {
    "id": 42,
    "username": "new_username",
    "email": "new@example.com",
    "role": "admin",
    "updatedAt": "2026-01-27T12:35:00Z"
  }
}

Erreurs possibles:

  • 400 Bad Request - Données invalides
  • 403 Forbidden - Non autorisé
  • 404 Not Found - Utilisateur inexistant
  • 409 Conflict - Username ou email déjà utilisé

DELETE /api/auth/admin/users/:id

Supprime un utilisateur de manière permanente.

Rate Limit: 10 requêtes/min

URL Parameters:

  • id (number) : ID de l'utilisateur

Headers:

Authorization: Bearer <admin_token>
X-User-Id: <admin_user_id>      (injecté par Gateway)
X-User-Name: <admin_username>   (injecté par Gateway)

Response 200:

{
  "success": true,
  "message": "User deleted successfully",
  "userId": 42
}

Erreurs possibles:

  • 403 Forbidden - Non autorisé (ne peut pas supprimer un admin)
  • 404 Not Found - Utilisateur inexistant

POST /api/auth/admin/users/:id/disable-2fa

Désactive la 2FA pour un utilisateur (utile si l'utilisateur a perdu accès à son authenticator).

Rate Limit: 10 requêtes/min

URL Parameters:

  • id (number) : ID de l'utilisateur

Headers:

Authorization: Bearer <admin_token>
X-User-Id: <admin_user_id>      (injecté par Gateway)
X-User-Name: <admin_username>   (injecté par Gateway)

Response 200:

{
  "success": true,
  "message": "2FA disabled for user",
  "userId": 42,
  "username": "john_doe"
}

Erreurs possibles:

  • 403 Forbidden - Non autorisé
  • 404 Not Found - Utilisateur inexistant
  • 409 Conflict - 2FA déjà désactivée

👥 Users Service

Service de gestion des profils utilisateurs et des relations d'amitié.

⚠️ Note: Returned id is the authId in DB. users/ prefix should perhaps be changed to users/profiles

Profile Routes

Méthode Endpoint Description Auth Rate Limit Status
GET /api/users/:id Récupère un profil par ID 🔒 JWT Global 👷
GET /api/users/username/:username Récupère un profil par username 🔒 JWT Global ✅
PATCH /api/users/avatar/:id Modifie l'avatar d'un utilisateur 🔒 JWT Global 👷
POST /users/ Crée un profil (route interne) 🔒 Internal - ✅

GET /api/users/:id

Récupère les informations de profil d'un utilisateur par son ID.

URL Parameters:

  • id (number) : Auth ID de l'utilisateur

Headers:

Authorization: Bearer <token>

Response 200:

{
  "authId": 1,
  "username": "john_doe",
  "avatarUrl": "default.png"
}

Erreurs possibles:

  • 400 Bad Request - ID invalide
  • 404 Not Found - Utilisateur inexistant

GET /api/users/username/:username

Récupère les informations de profil d'un utilisateur par son username.

URL Parameters:

  • username (string) : Username de l'utilisateur

Headers:

Authorization: Bearer <token>

Response 200:

{
  "authId": 1,
  "username": "john_doe",
  "avatarUrl": "default.png"
}

Erreurs possibles:

  • 400 Bad Request - Username invalide
  • 404 Not Found - Utilisateur inexistant

PATCH /api/users/avatar/:id

Modifie l'URL de l'avatar d'un utilisateur.

URL Parameters:

  • id (number) : Auth ID de l'utilisateur

Headers:

Authorization: Bearer <token>

Request Body:

{
  "avatarUrl": "new_avatar.png"
}

Response 200:

{
  "authId": 1,
  "username": "john_doe",
  "avatarUrl": "new_avatar.png"
}

Erreurs possibles:

  • 400 Bad Request - Données invalides
  • 401 Unauthorized - Non autorisé
  • 404 Not Found - Utilisateur inexistant

POST /users/

Crée un nouveau profil utilisateur. Route interne appelée par le service Auth après inscription.

🔒 Route interne - Authentification par API Key ou header interne

Request Body:

{
  "id": 42,
  "username": "john_doe",
  "email": "john@example.com"
}

Response 201:

{
  "authId": 42,
  "username": "john_doe",
  "avatarUrl": "default.png"
}

Erreurs possibles:

  • 400 Bad Request - Données manquantes ou invalides
  • 409 Conflict - Profil déjà existant

Friends Routes

Méthode Endpoint Description Auth Rate Limit Status
GET /api/users/friends/:id Liste les amis d'un utilisateur 🔒 JWT Global 👷
POST /api/users/friends Envoie une demande d'ami 🔒 JWT Global ✅
PATCH /api/users/friends/:id/status Modifie le statut d'une amitié 🔒 JWT Global 👷
PATCH /api/users/friends/:id/nickname Modifie le surnom d'un ami 🔒 JWT Global 👷
DELETE /api/users/friends/:id Supprime une relation d'amitié 🔒 JWT Global 👷

GET /api/users/friends/:id

Liste toutes les relations d'amitié d'un utilisateur.

URL Parameters:

  • id (number) : Auth ID de l'utilisateur

Headers:

Authorization: Bearer <token>

Response 200:

[
  {
    "id": 1,
    "status": "accepted",
    "nickname": "Best Friend",
    "friend": {
      "authId": 2,
      "username": "jane_doe",
      "avatarUrl": "default.png"
    }
  }
]

Erreurs possibles:

  • 400 Bad Request - ID invalide
  • 401 Unauthorized - Non authentifié
  • 404 Not Found - Utilisateur inexistant

POST /api/users/friends

Envoie une demande d'ami à un utilisateur.

Headers:

Authorization: Bearer <token>

Request Body:

{
  "id": 2
}

Response 201:

{
  "id": 1,
  "status": "pending",
  "nickname": null,
  "friend": {
    "authId": 2,
    "username": "jane_doe",
    "avatarUrl": "default.png"
  }
}

Erreurs possibles:

  • 400 Bad Request - ID invalide ou manquant
  • 401 Unauthorized - Non authentifié
  • 409 Conflict - Relation d'amitié déjà existante
  • 422 Unprocessable Entity - Ne peut pas s'ajouter soi-même

PATCH /api/users/friends/:id/status

Modifie le statut d'une relation d'amitié (accepter/refuser une demande).

URL Parameters:

  • id (number) : ID de la relation d'amitié

Headers:

Authorization: Bearer <token>

Request Body:

{
  "status": "accepted"
}

Valeurs possibles pour status:

  • accepted : Accepter la demande
  • rejected : Refuser la demande
  • pending : Remettre en attente
  • blocked : Bloquer l'utilisateur

Response 200:

{
  "id": 1,
  "status": "accepted",
  "nickname": null,
  "friend": {
    "authId": 2,
    "username": "jane_doe",
    "avatarUrl": "default.png"
  }
}

Erreurs possibles:

  • 400 Bad Request - Statut invalide
  • 401 Unauthorized - Non authentifié
  • 404 Not Found - Relation inexistante

PATCH /api/users/friends/:id/nickname

Modifie le surnom personnalisé d'un ami.

URL Parameters:

  • id (number) : ID de la relation d'amitié

Headers:

Authorization: Bearer <token>

Request Body:

{
  "nickname": "Best Friend"
}

Response 200:

{
  "id": 1,
  "status": "accepted",
  "nickname": "Best Friend",
  "friend": {
    "authId": 2,
    "username": "jane_doe",
    "avatarUrl": "default.png"
  }
}

Erreurs possibles:

  • 400 Bad Request - Nickname invalide
  • 401 Unauthorized - Non authentifié
  • 404 Not Found - Relation inexistante

DELETE /api/users/friends/:id

Supprime une relation d'amitié.

URL Parameters:

  • id (number) : ID de la relation d'amitié

Headers:

Authorization: Bearer <token>

Response 200:

{
  "id": 1,
  "status": "deleted",
  "nickname": null,
  "friend": {
    "authId": 2,
    "username": "jane_doe",
    "avatarUrl": "default.png"
  }
}

Erreurs possibles:

  • 400 Bad Request - ID invalide
  • 401 Unauthorized - Non authentifié
  • 404 Not Found - Relation inexistante

GAME Service

RL Routes

POST /rl/step

POST /rl/state

POST /rl/reset

AI Service

POST /predict

Predicts the next move for the AI paddle.

Request Body:

{
  "ball_x": 400,
  "ball_y": 300,
  "ball_velocity_x": 5,
  "ball_velocity_y": -2,
  "paddle_y": 250,
  "opponent_y": 250
}

Response:

{
  "action": 1  // 0=STOP, 1=UP, 2=DOWN
}

📦 DTOs & Models

ProfileDTO

Structure d'un profil utilisateur.

interface ProfileDTO {
  authId: number;        // ID utilisateur (clé primaire du service Auth)
  username: string;      // Username unique
  avatarUrl: string;     // URL de l'avatar
}

Exemple:

{
  "authId": 1,
  "username": "john_doe",
  "avatarUrl": "default.png"
}

FriendshipUnifiedDTO

Structure d'une relation d'amitié.

interface FriendshipUnifiedDTO {
  id: number;             // ID de la relation
  status: FriendshipStatus; // Statut de la relation
  nickname: string | null;  // Surnom personnalisé (optionnel)
  friend: ProfileDTO;       // Profil de l'ami
}

type FriendshipStatus = 'pending' | 'accepted' | 'rejected' | 'blocked';

Exemple:

{
  "id": 1,
  "status": "accepted",
  "nickname": "Best Friend",
  "friend": {
    "authId": 2,
    "username": "jane_doe",
    "avatarUrl": "default.png"
  }
}

User Model (Auth Service)

Structure utilisateur en base de données SQLite (service Auth).

interface User {
  id: number;                    // ID unique
  username: string;               // Username unique (4-20 caractères)
  email: string;                  // Email unique
  passwordHash: string;           // Hash bcrypt (rounds: 10)
  role: 'user' | 'admin';        // Rôle utilisateur
  twoFactorEnabled: boolean;      // 2FA activée ?
  twoFactorSecret: string | null; // Secret TOTP (si 2FA activée)
  createdAt: string;              // Date de création (ISO 8601)
  lastLogin: string | null;       // Dernier login (ISO 8601)
}

JWT Payload

Structure du payload JWT.

interface JWTPayload {
  sub: number;        // Subject (userId)
  username: string;   // Username
  role: string;       // Rôle ('user' | 'admin')
  iat: number;        // Issued at (timestamp)
  exp: number;        // Expiration (timestamp)
}

Configuration JWT:

  • Algorithme: HS256
  • Expiration: 1h (configurable via AUTH_CONFIG.JWT_EXPIRATION)
  • Secret: Variable d'environnement JWT_SECRET
  • Validation: Locale au Gateway (pas d'appel au service Auth)

Rate Limits Summary

Endpoint Production Development
Gateway Global 1000/min 10000/min
Auth - Register 5/5min 100/5min
Auth - Login 5/5min 100/5min
Auth - 2FA Setup 5/5min 100/5min
Auth - 2FA Verify 5/5min 100/5min
Auth - Heartbeat 10/10s 10/10s
Auth - Is Online 200/min 1000/min
Admin - List Users 50/min 50/min
Admin - Update User 20/min 20/min
Admin - Delete User 10/min 10/min
Admin - Disable 2FA 10/min 10/min

Les rate limits s'adaptent automatiquement selon NODE_ENV (production/development/test).

🔗 Liens utiles

📝 Notes importantes

Architecture

Gateway JWT Validation: Le Gateway valide les JWT localement sans appel au service Auth. Cela réduit la latence et les points de défaillance.

Headers internes: Le Gateway injecte automatiquement les headers X-User-Id, X-User-Name et X-User-Role après validation du JWT pour toutes les requêtes vers les services backend.

Sécurité

Hashing: Tous les mots de passe sont hashés avec bcrypt (10 rounds).

TOTP: Les tokens 2FA expirent après 30 secondes. Configuration standard : SHA1, 6 digits, 30s step.

Session Management: Le statut "en ligne" utilise Redis avec un TTL de 30 secondes. Les clients doivent envoyer un heartbeat toutes les 20-25 secondes.

Statuts HTTP

Les services utilisent les codes HTTP standardisés :

  • 200 OK : Succès
  • 201 Created : Ressource créée
  • 400 Bad Request : Données invalides
  • 401 Unauthorized : Authentification requise ou invalide
  • 403 Forbidden : Permissions insuffisantes
  • 404 Not Found : Ressource inexistante
  • 409 Conflict : Conflit (ex: username déjà pris)
  • 422 Unprocessable Entity : Erreur sémantique
  • 429 Too Many Requests : Rate limit dépassé
  • 500 Internal Server Error : Erreur serveur

Voir Restful-API pour plus de détails sur les conventions HTTP.

Home

🏗️ Architecture

🌐 Web Technologies

Backend

Frontend

🔧 Core Technologies

🔐 Security

⛓️ Blockchain

🛠️ Dev Tools & Quality

📝 Page model

Clone this wiki locally