mesh/server/README.md

Mesh Server

Serveur de control plane pour la plateforme Mesh.

Installation

Option 1: Docker (Recommandé)

# Copier et configurer l'environnement
cp .env.example .env
# Éditer .env avec vos valeurs (notamment MESH_JWT_SECRET)

# Construire l'image Docker
docker build -t mesh-server .

# Lancer le serveur
docker run -d --name mesh-server -p 8000:8000 --env-file .env mesh-server

# Voir les logs
docker logs mesh-server -f

Option 2: Installation Locale

Note: Nécessite Python 3.12+ (Python 3.13 non supporté actuellement)

# Créer un environnement virtuel
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Installer les dépendances
pip install -r requirements.txt

# Copier et configurer l'environnement
cp .env.example .env
# Éditer .env avec vos valeurs

Configuration

Éditer le fichier .env:

# Serveur
MESH_PUBLIC_URL=http://localhost:8000
MESH_JWT_SECRET=your-secret-key-min-32-chars

# Gotify
GOTIFY_URL=http://gotify:8080
GOTIFY_TOKEN=your-gotify-token

# TURN/STUN
STUN_URL=stun:stun.l.google.com:19302
TURN_HOST=turn.example.com

# Base de données
DATABASE_URL=sqlite:///./mesh.db

Démarrage

Avec Docker

# Le serveur est déjà lancé après docker run
# Pour voir les logs:
docker logs mesh-server -f

# Pour arrêter:
docker stop mesh-server

# Pour redémarrer:
docker start mesh-server

En local

# Lancer le serveur en mode développement
python3 -m uvicorn src.main:app --reload

# Ou avec le script
python3 -m src.main

Le serveur démarre sur http://localhost:8000

API Documentation

Documentation interactive disponible sur:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Endpoints Principaux

Authentification

• POST /api/auth/register - Créer un compte
• POST /api/auth/login - Se connecter
• GET /api/auth/me - Informations utilisateur
• POST /api/auth/capability - Demander un capability token

Rooms

• POST /api/rooms/ - Créer une room
• GET /api/rooms/ - Lister mes rooms
• GET /api/rooms/{room_id} - Détails d'une room
• GET /api/rooms/{room_id}/members - Membres d'une room

WebSocket

• WS /ws?token=JWT_TOKEN - Connexion temps réel

Structure du Projet

server/
├── src/
│   ├── main.py           # Point d'entrée
│   ├── config.py         # Configuration
│   ├── api/              # Routes API REST
│   │   ├── auth.py       # Authentification
│   │   └── rooms.py      # Gestion des rooms
│   ├── auth/             # Authentification & sécurité
│   │   ├── security.py   # JWT, hashing, capability tokens
│   │   ├── schemas.py    # Schémas Pydantic
│   │   └── dependencies.py # Dépendances FastAPI
│   ├── db/               # Base de données
│   │   ├── base.py       # Configuration SQLAlchemy
│   │   └── models.py     # Modèles ORM
│   └── websocket/        # WebSocket temps réel
│       ├── manager.py    # Gestionnaire de connexions
│       ├── events.py     # Types d'événements
│       └── handlers.py   # Handlers d'événements
├── alembic/              # Migrations
├── tests/                # Tests
├── requirements.txt
├── .env.example
└── Dockerfile

Développement

Tests

# Test de l'API (avec serveur lancé)
python3 test_api.py

# Tests unitaires
pytest tests/

Migrations

# Créer une migration
alembic revision --autogenerate -m "Description"

# Appliquer les migrations
alembic upgrade head

# Revenir en arrière
alembic downgrade -1

Linting

# Type checking
mypy src/

# Formatage
black src/

# Linting
flake8 src/

Événements WebSocket

Voir docs/protocol_events_v_2.md pour le protocole complet.

Exemples

system.hello:

{
  "type": "system.hello",
  "from": "peer_123",
  "to": "server",
  "payload": {
    "peer_type": "client",
    "version": "0.1.0"
  }
}

room.join:

{
  "type": "room.join",
  "from": "peer_123",
  "to": "server",
  "payload": {
    "room_id": "room_uuid"
  }
}

chat.message.send:

{
  "type": "chat.message.send",
  "from": "peer_123",
  "to": "server",
  "payload": {
    "room_id": "room_uuid",
    "content": "Hello world"
  }
}

Sécurité

• Tous les endpoints protégés nécessitent un JWT Bearer token
• Les capability tokens ont un TTL court (60-180s)
• Les mots de passe sont hashés avec bcrypt
• Les WebSocket nécessitent un token JWT valide

Voir docs/security.md pour plus de détails.

Variables d'Environnement

Variable	Description	Défaut
MESH_PUBLIC_URL	URL publique du serveur	http://localhost:8000
MESH_HOST	Host d'écoute	0.0.0.0
MESH_PORT	Port d'écoute	8000
MESH_JWT_SECRET	Secret pour JWT	(requis)
MESH_JWT_ALGORITHM	Algorithme JWT	HS256
MESH_JWT_ACCESS_TOKEN_EXPIRE_MINUTES	Expiration token	120
GOTIFY_URL	URL Gotify	(requis)
GOTIFY_TOKEN	Token Gotify	(requis)
STUN_URL	URL STUN	stun:stun.l.google.com:19302
TURN_HOST	Host TURN	(optionnel)
TURN_PORT	Port TURN	3478
DATABASE_URL	URL base de données	sqlite:///./mesh.db
LOG_LEVEL	Niveau de log	INFO

Troubleshooting

Erreur de connexion à la DB

# Vérifier que la DB existe
ls -la mesh.db

# Créer les tables manuellement
python -c "from src.db.base import Base, engine; Base.metadata.create_all(engine)"

Token JWT invalide

Vérifier que MESH_JWT_SECRET est défini et identique entre serveur et client.

WebSocket déconnecté immédiatement

Vérifier que le token JWT est passé en query param: /ws?token=YOUR_TOKEN