# Qu'est-ce qu'un serveur

Un serveur est un programme qui attend des demandes et y répond. Par extension, on appelle aussi « serveur » la machine sur laquelle il tourne.

## Le problème

Le jeu est entièrement local : la carte, les joueurs et les sauvegardes vivent sur une seule machine, dans `src/data/saves`. Tant que c'est le cas, impossible de comparer ses parties avec quelqu'un d'autre, de reprendre une partie sur un autre ordinateur, ou de jouer à deux à distance.

Toutes ces idées demandent la même chose : un programme, quelque part, que plusieurs jeux peuvent joindre. Avant de l'écrire, il faut le vocabulaire.

Ce site de documentation est d'ailleurs déjà un serveur : `npm run dev` en lance un, et le navigateur s'y connecte à l'adresse `http://localhost:3000`.

## La notion

### Client et serveur

<Mermaid
  chart={`sequenceDiagram
    participant C as Client<br/>navigateur, jeu, curl
    participant S as Serveur<br/>attend sur un port
    Note over S: démarre et écoute
    C->>S: requête, je voudrais la page d'accueil
    S-->>C: réponse, la voici
    C->>S: requête, je voudrais les scores
    S-->>C: réponse, les voici
    Note over S: continue d'attendre`}
/>

| Rôle | Ce qu'il fait |
| --- | --- |
| Client | Prend l'initiative : il envoie une requête |
| Serveur | Attend, reçoit la requête, renvoie une réponse |

Le serveur ne contacte jamais le client de lui-même. Il tourne en permanence, là où un programme ordinaire démarre, fait son travail et s'arrête.

### Adresse IP et port

Pour joindre un serveur, il faut deux informations.

| Information | Rôle | Image |
| --- | --- | --- |
| Adresse IP | Désigne la machine sur le réseau | L'adresse de l'immeuble |
| Port | Désigne le programme sur cette machine, de 1 à 65535 | Le numéro de l'appartement |

Une machine peut faire tourner plusieurs serveurs, chacun sur son port. **Un port ne peut être écouté que par un seul programme à la fois.**

| Port | Usage habituel |
| --- | --- |
| 22 | SSH |
| 80 | Web, HTTP |
| 443 | Web chiffré, HTTPS |
| 3000, 5000, 8000, 8080 | Serveurs de développement |
| 5432 | Base de données PostgreSQL |
| 6379 | Base de données Redis |

Les ports en dessous de 1024 sont réservés : il faut les droits d'administrateur pour les écouter. C'est pourquoi on développe sur 3000 ou 8000.

### localhost

`localhost`, ou `127.0.0.1`, désigne **la machine sur laquelle on se trouve**. Une requête vers `localhost` ne sort pas sur le réseau.

| Adresse d'écoute | Qui peut se connecter |
| --- | --- |
| `127.0.0.1` | Seulement les programmes de la même machine |
| `0.0.0.0` | Toutes les machines qui peuvent joindre celle-ci |

Cette différence est la cause d'un grand classique : un serveur qui marche sur son poste et que personne d'autre n'arrive à joindre. Il écoute sur `127.0.0.1`.

### Les noms

Personne ne retient des adresses IP. Le **DNS** est l'annuaire qui traduit un nom, comme `github.com`, en adresse IP. Le client pose la question à l'annuaire, puis se connecte à l'adresse obtenue.

## Lancer un serveur en une ligne

Python en fournit un, qui sert les fichiers du dossier courant.

```bash
cd documentation
python3 -m http.server 8000
```

```text
Serving HTTP on :: port 8000 (http://[::]:8000/) ...
```

Le terminal ne rend pas la main : le serveur attend. Dans un **deuxième terminal** :

```bash
curl http://localhost:8000/recap.md
```

`curl` est un client en ligne de commande : il envoie une requête et affiche la réponse. Le navigateur fait la même chose à l'adresse `http://localhost:8000`.

Dans le premier terminal, le serveur note chaque requête reçue :

```text
::1 - - [13/Nov/2026 10:12:01] "GET /recap.md HTTP/1.1" 200 -
```

Ce sont ses **journaux**, ou *logs*. C'est la première chose à lire quand un serveur ne fait pas ce qu'on attend. On l'arrête avec Ctrl + C.

## Savoir ce qui écoute

| Commande | Effet |
| --- | --- |
| `lsof -i :8000` | Quel programme écoute sur le port 8000, sur macOS et Linux |
| `ss -ltnp` | Tous les ports écoutés, sur Linux |
| `curl -i http://localhost:8000` | Envoie une requête et montre aussi l'en-tête de la réponse |
| `ping 192.168.1.20` | La machine répond-elle ? |

## Les erreurs fréquentes

| Message | Sens |
| --- | --- |
| `Address already in use` | Un autre programme écoute déjà sur ce port. Le trouver avec `lsof`, ou choisir un autre port |
| `Connection refused` | La machine répond, mais rien n'écoute sur ce port |
| `Connection timed out` | Pas de réponse du tout : mauvaise adresse, machine éteinte, pare-feu |
| `Permission denied` au démarrage | Port en dessous de 1024 sans droits d'administrateur |

## Où tourne un serveur

<Mermaid
  chart={`flowchart LR
    a[Sur son poste<br/>localhost] --> b[Dans une machine virtuelle<br/>sur son poste]
    b --> c[Sur une machine louée<br/>joignable par Internet]
    a -.- n1[Pour développer]
    b -.- n2[Pour s'entraîner]
    c -.- n3[Pour de vrais utilisateurs]`}
/>

Le programme est le même aux trois étapes. Ce qui change, c'est qui peut le joindre, et qui s'en occupe quand il tombe.

Un serveur destiné à de vrais utilisateurs doit redémarrer seul après une panne ou un redémarrage de la machine. Ce n'est pas le cas d'un programme lancé à la main dans un terminal : il s'arrête à la fermeture de la fenêtre. Les [conteneurs](/virtualisation/docker) règlent entre autres ce problème.

## Dans le projet

Ce qu'un serveur rendrait possible, du plus simple au plus ambitieux :

| Idée | Ce que fait le serveur | Difficulté |
| --- | --- | --- |
| Classement en ligne | Garde les meilleurs scores, les renvoie | Faible. C'est l'exemple du cours [API](/reseau/api) |
| Sauvegardes en ligne | Garde les fichiers `save_N.json` | Moyenne |
| Partie à deux à distance | Garde l'état de la partie, reçoit les coups de chaque joueur | Élevée |

La dernière a une condition : que les règles du jeu puissent tourner **sans fenêtre Pygame**, puisqu'un serveur n'a pas d'écran. C'est exactement la séparation proposée dans l'architecture cible (documentation du jeu).

## À retenir

- Le client demande, le serveur attend et répond.
- Une adresse IP désigne une machine, un port désigne un programme.
- `localhost` est la machine elle-même. `0.0.0.0` écoute pour tout le monde.
- Un port, un seul programme.
- En cas de doute, lire les journaux du serveur.

## Exercices

1. Lancer `python3 -m http.server 8000` dans le dossier `documentation` et afficher `recap.md` avec `curl`, puis avec le navigateur.
2. Sans l'arrêter, lancer un second serveur sur le même port. Lire l'erreur, puis le lancer sur un autre port.
3. Trouver avec `lsof` quel programme écoute sur le port 3000 quand `npm run dev` tourne.
4. Demander avec `curl -i` un fichier qui n'existe pas. Que répond le serveur, et qu'écrit-il dans ses journaux ?
5. Relancer le serveur avec l'option `--bind 127.0.0.1`. Qu'est-ce que cela change pour une autre machine du même réseau ?
