mesh/server/README.md

<!--
Created by: Claude
Date: 2026-01-02
Purpose: Documentation du serveur Mesh
Refs: server/CLAUDE.md
-->

# Mesh Server

Serveur de control plane pour la plateforme Mesh.

## Installation

### Option 1: Docker (Recommandé)

```bash
# 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)

```bash
# 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`:

```bash
# 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
```bash
# 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
```bash
# 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

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

# Tests unitaires
pytest tests/
```

### Migrations

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

# Appliquer les migrations
alembic upgrade head

# Revenir en arrière
alembic downgrade -1
```

### Linting

```bash
# Type checking
mypy src/

# Formatage
black src/

# Linting
flake8 src/
```

## Événements WebSocket

Voir [docs/protocol_events_v_2.md](../docs/protocol_events_v_2.md) pour le protocole complet.

### Exemples

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

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

**chat.message.send**:
```json
{
  "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](../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

```bash
# 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`