Aller au contenu

ADR-015 : Handshake TLS par thread client pour le serveur de développement

Statut

Accepté, Forge 1.0.0-beta.9 (ticket APP-PY-TLS-HANDSHAKE-PER-THREAD-001).

Date

2026-05-25

Contexte

Forge fournit un serveur de développement HTTPS intégré à app.py, basé sur http.server.ThreadingHTTPServer.
Ce serveur est destiné au développement local, à la pédagogie et aux tests : il permet d'expérimenter avec un cookie Secure, un en-tête HSTS, ou le comportement réel d'un navigateur sur HTTPS sans imposer un reverse proxy en local.

En production, le périmètre reste clair : TLS doit être terminé par Nginx ou un reverse proxy équivalent, et Forge écoute en HTTP local.
Voir la documentation wsgi-deployment et le ticket WSGI-APP-FACTORY-CONFIG-001.

État avant la décision

L'activation TLS dans app.py se faisait par :

server.socket = ssl_ctx.wrap_socket(server.socket, server_side=True)

Cette ligne enveloppe le socket d'écoute : chaque appel accept() rend alors un SSLSocket, et do_handshake_on_connect=True par défaut force le handshake TLS à s'exécuter de manière synchrone dans le thread appelant.

Comme accept() tourne dans le thread principal de serve_forever(), le handshake TLS bloque ce thread tant qu'il n'est pas terminé.
ThreadingMixIn ne lance son thread enfant qu'après le retour de get_request(), donc après le handshake.
Le thread-par-requête ne protège donc pas du handshake TLS bloquant.

Symptômes terrain

Reproductibles sur la configuration courante du projet (VS Code Remote SSH, navigateur distant, port forwarding, certificat auto-signé non encore accepté) :

  • Après 2 à 6 requêtes navigateur (selon le pre-connect), le serveur se fige sans traceback.
  • ss -tlnp | grep 8000 montre Recv-Q: 5, la file d'attente du kernel est saturée.
  • Côté client : ERR_TIMED_OUT dans Chrome, Connection timed out after 10001 milliseconds sur curl.
  • Particulièrement facile à déclencher quand le navigateur refuse le certificat auto-signé : les handshakes interrompus (alerte CERTIFICATE_UNKNOWN) se cumulent et finissent par bloquer la boucle.

Décision

  1. Le socket d'écoute n'est pas wrappé par ssl_ctx.wrap_socket(...).
    accept() rend toujours un socket TCP brut.
  2. Le wrap TLS s'exécute dans process_request_thread() de la sous-classe TLSThreadingHTTPServer, dans le thread du client lancé par ThreadingMixIn.
  3. Le handshake est borné par TLS_HANDSHAKE_TIMEOUT = 10s via request.settimeout(...).
    Après le handshake, le socket repasse en mode bloquant standard pour la requête HTTP elle-même.
  4. Les erreurs ssl.SSLError, OSError et socket.timeout sont attrapées, loggées en WARNING avec l'adresse client et le message d'origine, et la connexion est fermée proprement via shutdown_request(request).
  5. Le contexte SSL est posé en attribut server.ssl_context au lieu de muter server.socket.

Flux résultant :

TCP accept()                       (thread principal - non bloquant)
  → ThreadingMixIn lance un thread (thread du client)
      → wrap_socket()              (handshake TLS, borné par timeout)
          → RequestHandler         (requête HTTP normale)

Conséquences

Positives

  • Le serveur dev ne se fige plus après quelques connexions TLS interrompues ou refusées.
  • Un client TLS lent, muet, mal configuré, ou parlant le mauvais protocole n'occupe que son propre thread, la boucle d'accept reste disponible.
  • Le port 8000 reste utilisable avec VS Code Remote SSH, port forwarding, navigateurs distants, et scanners de sécurité agressifs sans dégradation.
  • Le comportement est plus robuste face aux certificats auto-signés non encore acceptés par le navigateur.
  • Les handshakes échoués sont visibles dans les logs (WARNING, Handshake TLS échoué depuis <addr> : <message>).

Limites

  • Le serveur dev reste un serveur de développement.
    Il ne remplace pas Gunicorn + reverse proxy en production (cf ADR-005, ADR-006, et la documentation wsgi-deployment).
  • TLS_HANDSHAKE_TIMEOUT est une constante de module.
    Sa configurabilité via config.py est un ticket de suivi (APP-TLS-HANDSHAKE-TIMEOUT-CONFIG, hors scope de cet ADR).
  • L'observabilité des handshakes TLS échoués reste limitée au log (WARNING).
    Pas de compteur, pas de métrique exportée, un ticket de suivi optionnel a été suggéré.
  • Le serveur dev reste mono-processus.
    Le multi-worker (Gunicorn, uWSGI) reste l'apanage du déploiement production via WSGI.

Alternatives écartées

A : Continuer à wrapper le socket d'écoute

Maintenir server.socket = ssl_ctx.wrap_socket(server.socket, ...).

Rejeté : c'est exactement le code qui produit le blocage.
Tout client TLS qui ne complète pas son handshake fige toute la boucle d'acceptation.
La preuve a été reproduite et documentée.

B : Surcharger uniquement get_request() pour wrapper là

Surcharger BaseServer.get_request() pour appeler wrap_socket() après accept().

Rejeté : get_request() est appelée par serve_forever() dans le thread principal, exactement comme accept().
Le handshake TLS y est aussi bloquant.
Cette approche avait été proposée dans un ticket antérieur, c'est une fausse piste.

C : Supprimer TLS du serveur de développement

Désactiver le mode HTTPS de app.py, imposer HTTP en dev.

Rejeté : HTTPS local reste utile pour tester certains comportements navigateur, notamment les cookies Secure, le contenu mixte HTTPS/HTTP, et les en-têtes HSTS.
Supprimer ce mode appauvrirait la pédagogie sans contrepartie.

D : Imposer un reverse proxy même en développement

Documenter l'usage obligatoire d'un Nginx/Caddy local pour terminer TLS, même en dev.

Rejeté : trop lourd pour un usage pédagogique et quotidien.
Forge vise un démarrage en quelques minutes (python app.py).
Imposer un reverse proxy en plus contredirait cet objectif.

E : Utiliser ThreadingHTTPSServer (Python 3.14+)

http.server.ThreadingHTTPSServer a été ajouté en Python 3.14 et résout nativement ce problème.

Rejeté pour l'instant : Forge cible Python 3.12+ (ADR-006).
La compatibilité 3.12 et 3.13 doit être préservée.
Une future bascule sur ThreadingHTTPSServer sera évaluée quand Python 3.14 sera la cible minimale.

Hors périmètre de cet ADR

  • Rendre TLS_HANDSHAKE_TIMEOUT configurable via config.py.
  • Modifier les niveaux de logs TLS (déclasser CERTIFICATE_UNKNOWN en INFO).
  • Ajouter un compteur d'observabilité des handshakes échoués.
  • Documenter un guide complet Nginx/Caddy/systemd pour la production.
  • Modifier la configuration WSGI ou la stratégie de déploiement production.

Référence

  • Code livré : app.py, classe TLSThreadingHTTPServer, constante TLS_HANDSHAKE_TIMEOUT.
  • Ticket d'implémentation : APP-PY-TLS-HANDSHAKE-PER-THREAD-001 (commit fc520cf sur la branche fix/tls-per-thread-handshake).
  • Ticket documentaire : APP-PY-TLS-HANDSHAKE-DOCS-001 (cet ADR).
  • ADR-005 Packaging : docs/adr/005-packaging.md (périmètre WSGI/prod).
  • ADR-006 Python 3.12+ : docs/adr/006-python-version.md (pourquoi ThreadingHTTPSServer n'est pas une option immédiate).
  • Documentation WSGI : docs/wsgi-deployment.md (terminer TLS via reverse proxy en production).