Vue lecture

epub, le convertisseur EPUB3 à la volée de LinuxFr.org

Le site LinuxFr.org utilise divers logiciels libres pour son fonctionnement et ses services : une large majorité provient de projets tiers (Debian, MariaDB, Redis - version d’avant le changement de licence, nginx, Postfix, conteneurs LXC et Docker, Ruby On Rails, Sympa, etc.) et d’autres composants sont développés pour nos propres besoins. Cette dernière catégorie comprend le code principal du site web en Ruby On Rails, et principalement 5 services autour : le cache d’images img, la tribune board, le convertisseur EPUB 3 epub, le partageur sur les réseaux sociaux share et le convertisseur LaTeX vers SVG svg. Cette dépêche va s’intéresser à epub, un code sous AGPLv3.

Elle est née d’une envie personnelle d’expliquer, documenter et montrer ce qui a été fait sur le convertisseur EPUB3 à la volée de LinuxFr.org, et elle vient accompagner la précédente sur img, le cache d’images sur LinuxFr.org.

    Sommaire

    Des EPUB de vos contenus et commentaires

    LinuxFr.org vous permet de lire les contenus et commentaires du site, au format EPUB3, par exemple dans votre liseuse préférée. Il y a une exception à cela, les liens, parce que certes ça ferait des EPUB tout mignons, mais surtout petits voire un poil inutiles. Le lien EPUB est présent automatiquement sur chaque contenu (hormis les liens donc).

    Le principe est simple : on donne un lien vers un contenu HTML à epub, il le demande à la partie Ruby on Rails du site, ainsi que les images associées, convertit le tout au format EPUB3 et le renvoie à la personne qui l’a demandé. Techniquement epub n'est pas exposé frontalement mais se trouve derrière un nginx.

    Côté code Ruby on Rails

    C’est assez basique : on ajoute juste sur chaque contenu un lien pour télécharger au format EPUB. Ainsi, y compris sur cette dépêche, vous allez trouver un lien à la fin pour récupérer le tout au format EPUB (et un autre pour récupérer le source en Markdown mais c’est un autre sujet).

    app/views/news/_news.atom.builder:    epub = content_tag(:div, link_to("Télécharger ce contenu au format EPUB", "#{url}.epub"))
    app/views/polls/_poll.atom.builder:  epub = content_tag(:div, link_to("Télécharger ce contenu au format EPUB", "#{url}.epub"))
    app/views/posts/_post.atom.builder:  epub = content_tag(:div, link_to("Télécharger ce contenu au format EPUB", "#{url}.epub"))
    app/views/nodes/_actions.html.haml:    = link_to "EPUB", "#{path_for_content node.content}.epub", title: "Télécharger ce contenu au format EPUB", class: "action download"
    app/views/diaries/_diary.atom.builder:  epub = content_tag(:div, link_to("Télécharger ce contenu au format EPUB", "#{url}.epub"))
    app/views/wiki_pages/_wiki_page.atom.builder:  epub = content_tag(:div, link_to("Télécharger ce contenu au format EPUB", "#{url}.epub"))

    Côté epub

    Le service est plutôt simple, par rapport à img, car il n’a pas de dépendance sur redis par exemple, et qu’il a, au final, peu de paramétrage (un couple adresse+port d’écoute, un fichier de trace et un hôte pour aller chercher les contenus).

    Il est possible de faire un GET /status et on obtient une réponse HTTP 200 avec un contenu OK. C’est utile pour tester que le service est lancé (depuis l’intérieur de la plateforme).

    Sinon on lui demande une dépêche, un journal, une entrée de forum, un sondage, une entrée de suivi ou une page wiki en prenant le chemin sur LinuxFr.org et ajoutant un petit .epub à la fin, et il va renvoyer un fichier EPUB. Ou bien il va répondre un contenu non trouvé HTTP 404 s’il y a un souci. Et vu son fonctionnement, si on a un souci de HTML non valide ou si img a un problème avec une image, alors derrière epub pourrait avoir le même souci.

    epub est un binaire dynamique en Go. Il impose le https pour l’hôte (du coup on aura tous les liens en HTTPS en interne normalement). Il ne peut pas vraiment être compilé statiquement (on a besoin de libxml2, libonig2 et de la même version de la libc au déploiement). Il ne gère pas les images in-line.

    Dans les logs on va trouver des infos comme :

    2024/11/03 16:34:02 Status code of http:/example.invalid/exemple.png is: 404
    (…)
    2024/11/03 16:38:23 Fetch https://linuxfr.org/news/capitole-du-libre-2024-au-programme-du-16-et-17-novembre
    2024/11/03 16:38:24 Fetch https://linuxfr.org/users/liberf0rce/journaux/libreast-2006-is-out-of-order
    

    Historique

    epub a été créé par Bruno Michel en 2013 et Bruno est le seul à travailler dessus (48 commits) jusqu’en 2018. Comme img, on peut considérer que epub a fait le job pendant ce temps-là, sans besoin de retouche.

    Mon premier commit de 2021 concerne la gestion d’un cas de collision de nommages des images.

    En 2022, Bruno quitte l’équipe du site, et par ailleurs il y a des montées de versions et des migrations à faire sur les serveurs de LinuxFr.org, et epub fait partie des services à reprendre en main. Ce qui veut dire le comprendre, le documenter et au besoin l’améliorer.

    Bref je décide de me plonger dans epub (2022-2024), dans la foulée de img, car a priori ce n’est pas un composant compliqué du site (il vit dans son coin, il offre une interface, c’est du Go, donc on a un binaire seulement à gérer - divulgâchage en fait non pas seulement).

    Le choix est le même que pour img (cf la dépêche précédente) : ajouter un Dockerfile permettant de recompiler epub dans un conteneur, en contrôlant la version de Go utilisée, en effectuant une détection d’éventuelles vulnérabilités au passage avec govulncheck. Cela me permet de valider que l’on sait produire le binaire d’une part, et que l’on offre à tout le monde la possibilité de contribuer facilement sur ce composant. Et de découvrir qu’une version statique n’est pas facilement envisageable.

    Puis je vais tester le composant pour vérifier qu’il fonctionne comme je le pense et qu’il fait ce qu’on attend de lui. Je vais ajouter une suite des tests qui couvrent les différentes fonctionnalités et les vérifient en IPv4 et en IPv6, en HTTP 1.1 et en HTTP 2.0. Les tests utilisent Hurl et docker-compose, et encore une fois l’idée de donner la possibilité de contribuer facilement. Ils comprennent des tests de types de contenus non pris en charge, le test de la limite à 5 MiB, différents types de contenus, le test de vie, des appels erronés (mauvais chemin, mauvaise méthode, etc). Et surtout de vérifier avec epubcheck que le fichier epub produit est correct. Le choix des cas de tests est basé sur le trafic réellement constaté sur le serveur de production, sur les différents cas dans le code et un peu sur l’expérience du testeur.

    Les différents travaux effectués vont permettre de détecter et corriger quelques soucis :

    Et à la fin, j’écris une dépêche pour parler de tout cela.

    Évolutions récentes

    Dockerfile

    Le fichier Dockerfile du projet permet :

    • de partir d’une image officielle Go d’une version donnée, basée sur une distribution Debian (en raison des dépendances)
    • de l’utiliser pendant la construction en prenant la liste des dépendances de compilation, en les téléchargeant, en prenant l’unique fichier source epub.go et en le compilant dynamiquement avec l’option pour retirer les chemins de compilation
    • de rechercher les éventuelles vulnérabilités avec govulncheck
    • de tester avec golangci/golangci-lint le code (fait à la construction de l’image, car on dispose de toutes les dépendances à ce moment-là)
    • de repartir d’une base Debian en y mettant les autorités de certification, les dépendances de fonctionnement et le binaire issus de la partie construction, de déclarer le port d’écoute et de lancer le binaire avec des variables disposant de valeurs par défaut.

    La suite de tests

    Pour l’utiliser, c’est assez simple, il faut aller dans le répertoire tests et lancer un docker-compose up --build, qui va produire le conteneur contenant epub, et démarrer le nginx-cert qui fournit les certificats et le nginx préconfiguré pour les tests. Si tout va bien, on attend, et au bout d’un moment il s’affiche :

    linuxfr.org-epub-test_1  | All tests look good!
    tests_linuxfr.org-epub-test_1 exited with code 0
    

    Rentrons un peu dans les détails.

    D’abord un fichier docker-compose.yaml qui décrit le réseau IPv4/IPv6 utilisé pour les tests, l’image nginx-cert qui sera utilisée pour créer une autorité de certification et un certificat serveur de test, l’image nginx qui sera utilisée avec sa configuration et ses fichiers à servir pour les tests, l’image epub et son paramétrage (dont l’accès au nginx) ainsi que le répertoire de l’autorité de certification de tests et enfin l’image de la suite de tests qui est construit avec son Dockerfile et son répertoire de dépôt des fichiers EPUB.

    Le Dockerfile de tests est basé sur une image Hurl (un outil pour faire des tests HTTP). On ajoute les fichiers de tests en .hurl, le script shell qui pilote le tout, on prévoit d’avoir les paquets dont on aura besoin : bash (pas par défaut dans les Alpine), curl, openjdk17 (pour epubcheck), openssl, unzip (transitoirement), bind-tools et shellcheck. On installe epubcheck. Et on lance les tests par défaut.

    La configuration nginx de test écoute en HTTP sur le port 80 en IPV4 et IPv6 et permet de définir des chemins avec des réponses en HTTP 301, 302, 308, 400, 401, 403, etc. jusqu’à 530 et même 666 pour les codes invalides, ainsi qu’une redirection infinie.

    Dans les données de tests servies par nginx, on trouve des contenus du mauvais type, des contenus dans divers formats, une image très grande et des images qui ne seront pas accessibles.

    Sont aussi présents deux fichiers de tests avec une extension en .hurl :

    • le test de vie et les chemins hors des contenus autorisés
    • les tests sur les contenus

    Vient enfin le script shell qui pilote le tout :

    • on définit les variables pour les cibles IPv4/IPv6 que l’on veut utiliser dans les autres conteneurs Docker
    • on purge le stockage des EPUB sur disque
    • on lance les premiers tests (en IPv4 et IPv6, en HTTP 1.1 et en HTTP 2.0)
    • sur chaque EPUB produit, on lance epubcheck et on regarde si la validation donne le résultat attendu (succès ou échec)
    • si on est arrivé jusque-là on écrit que tout va bien et on déclenche un sourire de satisfaction.

    Les problématiques restantes

    Il y a quelques entrées encore ouvertes dans le suivi :

    • les images trop grandes (en octet), non récupérables, de format inconnu, etc. : la suite de tests actuelle « couvre » le cas des images de plus de 5 MiB ou non récupérables, avec des tests qui échouent, comme prévu, vu que c’est img qui est censé faire le job de les éviter. Cependant il pourrait être sympa de remplacer toute image non disponible/invalide par une image de remplacement « Image indisponible » du bon Content-Type et du bon nom (vu qu’elle est déclarée dans le MANIFEST).
    • les images trop grandes (en pixel) : globalement on revient à la question des images que laisse passer img
    • les epub non fonctionnels en rédaction et modération : pour des questions de droits, la génération EPUB ne marche pas dans les espaces de rédaction et de modération, à voir si on trouve un contournement ou si on évite de proposer le lien.

    Il y a la question habituelle de la montée de versions des dépendances (pour nous actuellement contraintes celles du code Ruby on Rails). Et des questions à se poser sur l’avenir de nginx ?. Les dépendances pendant le fonctionnement amènent aussi leur lot de contraintes.

    Conclusion ?

    Encore une fois, sans surprise et me répétant, il reste des problématiques et du code à faire pour les gérer (c’est rare un composant sans demandes d’évolution ou de correction). Yapuka (mais probablement plus tard, il faut aussi partager le temps avec les autres composants, ou avoir plus de contributions).

    epub rend la fonction que l’on attend de lui, même si on pourrait faire un peu mieux. Plonger dans ce composant s’est avéré assez intéressant et formateur (et nécessaire) : techniquement cela a été l’occasion de faire du Go, du docker et du docker-compose, du nginx, du hurl, de l’HTTP et de gérer des problématiques statique/dynamique et des dépendances. Il s’agissait encore de comprendre ce que faisait un code écrit par une autre personne, de se poser des questions pour choisir les tests et le contenu de la documentation, de se demander pour quelles raisons tel ou tel choix a été fait, de rendre ce composant plus « contribuable », et de compléter le tout de façon détaillée avec une dépêche.

    Commentaires : voir le flux Atom ouvrir dans le navigateur

    img, le cache d’images sur LinuxFr.org

    Le site LinuxFr.org utilise divers logiciels libres pour son fonctionnement et ses services : une large majorité provient de projets tiers (Debian, MariaDB, Redis - version d’avant le changement de licence, nginx, Postfix, conteneurs LXC et Docker, Ruby On Rails, Sympa, etc.) et d’autres composants sont développés pour nos propres besoins. Cette dernière catégorie comprend le code principal du site web en Ruby On Rails, et principalement 5 services autour : le cache d’images img, la tribune board, le convertisseur EPUB 3 epub, le partageur sur les réseaux sociaux share et le convertisseur LaTeX vers SVG svg. Cette dépêche va s’intéresser à img, un code sous AGPLv3.

    Elle est née d’une envie personnelle d’expliquer, documenter et montrer ce qui a été fait sur le cache d’images de LinuxFr.org, complétée d’une demande d’un « article technique sur le fonctionnement de ce cache, les choix techniques qui ont été faits, les erreurs commises donc à éviter… ».

      Sommaire

      Des images sur le site

      LinuxFr.org vous permet d’utiliser des images externes dans les contenus et commentaires du site. Ces images sont incluses en syntaxe markdown avec ![description textuelle](adresse "titre optionnel") (soit en saisissant directement du Markdown, soit en cliquant sur l’icône d’ajout d’image dans l’éditeur). Profitons-en pour rappeler que pour utiliser une image sur LinuxFr.org, vous devez vous assurer de respecter sa licence.

      Nous vous encourageons donc à utiliser des images sous licence libre et à citer les auteurs (c’est même obligatoire pour les licences CC-by et CC-by-sa). Cette citation est tirée de la dépêche d’annonce Un nouveau reverse-proxy cache pour les images externes sur LinuxFr.org de 2012.

      Il est aussi recommandé de mettre une vraie description textuelle, qui finira dans l’attribut alt de la balise img utilisée pour l’accessibilité ou si l’image ne peut être chargée. Il peut être utile de lui donner un titre qui apparaîtra l’autre du survol de l’image à la souris par exemple.

      Exemple :

      ![Logo LinuxFr.org](https://linuxfr.org/images/logos/linuxfr2_classic_back.png "L’actualité du logiciel libre et des sujets voisins (DIY, Open Hardware, Open Data, les Communs, etc.), sur un site francophone contributif géré par une équipe bénévole par et pour des libristes enthousiastes.")

      Logo LinuxFr.org

      Buts du cache d’images

      Les raisons évoquées à la mise en place de img (sans ordre particulier) :

      • la sécurité : si une image externe n’est servie qu’en HTTP (en clair donc) et est appelée au milieu d’une page LinuxFr.org elle-même servie en HTTPS, alors le navigateur va râler sur le mélange des genres. img permet de servir toutes les images identiquement (par exemple en HTTPS, et avec le certificat de LinuxFr.org, via le serveur frontal devant img). À noter que ces images ne sont pas servies directement depuis le domaine principal linuxfr.org mais depuis un sous-domaine img.linuxfr.org pour éviter que le JavaScript embarqué dans les images en SVG puisse servir de vecteur d’attaque contre le site.
      • la protection de la vie privée des personnes visitant LinuxFr.org : seul LinuxFr.org voit les informations en provenance de leur navigateur (dont l’adresse IP). Les équipes d’administration des différents sites ne les voient plus (elles voient l’adresse IP du serveur LinuxFr.org).
      • une meilleure gestion du trafic : au lieu d’envoyer tout notre public chercher individuellement chaque image, LinuxFr.org la récupère une fois et la rend disponible. Si le site externe fournissant l’image est un serveur à faibles ressources (liaison ADSL avec faible débit montant par exemple), la mise en cache permet de garantir qu’il ne recevra qu’un faible volume de requêtes (la récupération se faisant initialement toutes les 10 min tant que des demandes arrivent, le cache expirant après 10 min).
      • la conservation des images : les images incluses depuis des sites externes peuvent ne plus être disponibles (l’entité a disparu, le serveur a été arrêté, le domaine a été perdu, l’adresse a changé, etc.). Nous avons donc un mécanisme de cache pour que nous puissions continuer à servir une image même si elle devient indisponible.

      Parmi les conséquences de cette implémentation initiale, on peut citer :

      • si le fichier est changé sur le serveur distant (modifié, converti dans un autre format), l’ancien fichier est servi jusqu’à la prochaine récupération et le nouveau fichier ne sera servi qu’à la prochaine récupération ;
      • si le fichier est supprimé sur le serveur distant, l’image ne sera plus servie après la prochaine récupération (car le serveur a répondu que l’image n’existe plus) ;
      • il est possible de modifier l’image au passage : les images d’avatar sont retaillées pour une hauteur de 64 pixels par exemple ;
      • il est possible de bloquer des images : les images problématiques (pub/spam, contenus pour adultes, images injurieuses, etc.) peuvent être bloquées et ne plus être servies ;
      • par ailleurs img n’accepte de servir que les images connues de LinuxFr.org dont le poids fait moins de 5 MiB.

      À l’utilisation

      Lors de l’écriture d’un commentaire ou d’un contenu sur LinuxFr.org, une personne va ajouter une image externe via la syntaxe Markdown, par exemple ![Logo LinuxFr.org](https://linuxfr.org/images/logos/linuxfr2_classic_back.png)

      Ce qui donne à l’affichage :

      Logo LinuxFr.org

      Et côté code HTML :

      <img src="https://linuxfr.org/images/logos/linuxfr2_classic_back.png" alt="Logo LinuxFr.org">

      OK, mauvais exemple ce n’est pas une image externe, puisqu’elle est hébergée sur LinuxFr.org justement. Prenons un autre exemple ![April - Campagne d’adhésion](https://april.org/campagne-2024/relais/banniereCampagneApril.svg).

      Ce qui donne à l’affichage :

      April - Campagne d’adhésion

      Et côté code :

      <img src="//img.linuxfr.org/img/68747470733a2f2f617072696c2e6f72672f63616d7061676e652d323032342f72656c6169732f62616e6e6965726543616d7061676e65417072696c2e737667/banniereCampagneApril.svg" alt="April - Campagne d’adhésion" title="Source : https://april.org/campagne-2024/relais/banniereCampagneApril.svg">

      Donc on sert l’image via le sous-domaine img.linuxfr.org. On peut aussi noter le titre rempli automatiquement avec la source. Expliquons la nouvelle adresse :

      • // on sert en https si la page est en https et en http si la page est en http (c’est plutôt un oubli qu’autre chose, vu que le site est uniquement en https)
      • img.linuxfr.org on sert depuis un sous-domaine du site
      • 68747470733a2f2f617072696c2e6f72672f63616d7061676e652d323032342f72656c6169732f62616e6e6965726543616d7061676e65417072696c2e737667 est la version en texte-vers-hexadécimal de l’adresse d’origine (68 pour h, 74 pour t (deux fois), 70 pour p, etc.). Il existe des sites et des outils en local pour faire cette conversion, mais cela ne concerne pas la simple utilisation du site.
      • banniereCampagneApril.svg on met à la fin le nom du fichier pour être sympa si vous voulez sauver l’image en local avec un nom plus explicite

      Ceci était le cas où tout se passe bien, comme prévu, comme le voulait la personne qui voulait utiliser une image externe.

      Voyons maintenant ce qui se passe dans le cas pas si rare où la personne a donné une adresse d’image invalide, une adresse ne pointant pas vers une image vers autre chose (cas extrêmement fréquent), une image trop grosse (plus de 5 MiB), etc. Il se passe la même chose côté code, mais côté affichage, pas d’image, et on voit seulement le texte alternatif dans son navigateur. Dans les coulisses, img a répondu 404, cette adresse n’est pas disponible.

      On note donc qu’une même image servie en http:// ou en https:// aura une adresse convertie en hexadécimal différente, donc sera vue comme une autre image par img. Même chose si le serveur externe accepte des adresses sans tenir compte de la casse, ou si on rajoute des paramètres dans l’adresse comme « ?mot_magique=merci ».

      Côté code Ruby on Rails

      Un contenu ou commentaire est en cours de création et une image externe a été mentionnée. Le code de gestion des images va vérifier que l’image est déclarée dans redis (créer l’entrée img/<adresse> avec adresse l’adresse de l’image en clair, ajouter un champ created_at avec l’horodatage, ajouter l’adresse dans la liste des dernières images img/latest) et renvoyer l’adresse via img.

      Le code peut aussi modifier le champ status d’une image dans redis pour mettre ou enlever un blocage (valeur Blocked) par l’équipe du site, et l’ajouter/enlever de la liste des images bloquées img/blocked.

      Côté img

      Les schémas dans la documentation du service img explicitent les possibilités et les comportements.

      Il est possible de faire un GET /status et on obtient une réponse HTTP 200 avec un contenu OK. C’est utile pour tester que le service est lancé (depuis l’intérieur de la plateforme).

      Sinon, on peut envoyer des requêtes GET /img/<adresse_en_hexa> or GET /img/<adresse_en_hexa>/<nom_de_fichier> pour les images, et GET /avatars/<adresse_en_hexa> ou GET /avatars/<adresse_en_hexa>/<nom_de_fichier> pour les avatars.

      En se limitant aux requêtes légitimes, le comportement de img est le suivant :

      • l’adresse demandée a été précédemment déclarée (dans redis par la partie code Ruby On Rails) sinon il répond 404 ;
      • l’adresse demandée n’est pas bloquée par l’équipe du site sinon il répond 404 ;
      • l’adresse est déjà dans le cache disque, alors il renvoie l’image ;
      • l’adresse n’est pas dans le cache disque et la récupération échoue, il renvoie 404 (et va noter temporairement l’échec dans img/err/<uri>) ;
      • l’adresse n’est pas dans le cache disque et la récupération a lieu (noté temporairement dans img/update/<uri>): si le serveur répond positivement à la demande, avec une image comme attendue, pas trop volumineuse, alors on la met en cache disque. Si c’est un avatar, on peut retailler l’image. On aura des champs supplémentaires stockés type avec la nature de l’image (en-tête Content-Type), checksum avec un hachage SHA1 et etag avec la valeur ETag (entête ETag).

      Le cache est rafraîchi régulièrement.

      img est un binaire statique en Go. Il offre des options pour définir le couple adresse:port d’écoute, pour définir où envoyer les logs, pour se connecter à une base redis, pour définir le répertoire du cache disque, pour choisir le User-Agent qui sera utilisé pour les requêtes externes, pour définir l’avatar qui sera renvoyé par défaut, et la possibilité de le lancer uniquement en mode audit interne pour vérifier la cohérence et l’état des données et des fichiers.

      Dans les logs on va trouver des infos comme :

      2024/10/20 20:39:24 Status code of http://example.invalid/exemple1.png is: 404
      2024/10/20 20:39:24 Fail to fetch http://example.invalid/exemple1.png (serve from disk cache anyway)
      2024/10/20 20:44:12 Fetch http://example.invalid/exemple2.png (image/png) (ETag: "be5e-4dba836030980")
      2024/10/20 20:44:12 http://example.invalid/exemple3.png has an invalid content-type: text/html;charset=UTF-8
      2024/10/20 20:44:12 Fail to fetch http://example.invalid/exemple3.png (serve from disk cache anyway)
      

      Ici l’exemple 1 est déjà en cache et peut être servi même si on échoue à le récupérer à ce moment-là. L’exemple 2 vient d’être récupéré. L’exemple 3 a désormais une adresse invalide (qui renvoie une page HTML au lieu d’une image) mais il existe en cache une image précédemment récupérée.

      Historique

      img a été créé par Bruno Michel en 2012. Adrien Kunysz amène 5 commits en novembre 2013, mais globalement Bruno est le seul à travailler dessus (43 commits) jusqu’en 2018. img fait le job et il n’est pas besoin d’y retoucher trop souvent.

      En 2022, Bruno quitte l’équipe du site, et par ailleurs il y a des montées de versions et des migrations à faire sur les serveurs de LinuxFr.org, et img fait partie des services à reprendre en main. Ce qui veut dire le comprendre, le documenter et au besoin l’améliorer.

      Bref je décide de me plonger dans img (2022-2024), car a priori ce n’est pas le composant le plus compliqué du site (il vit dans son coin, il offre une interface, c’est du Go, donc on a un binaire seulement à gérer).

      Étape 1 : je vais commencer par ajouter un Dockerfile permettant de recompiler img dans un conteneur, en contrôlant la version de Go utilisée, en effectuant une détection d’éventuelles vulnérabilités au passage avec govulncheck. Cela me permet de valider que l’on sait produire le binaire d’une part, et que l’on offre à tout le monde la possibilité de contribuer facilement sur ce composant.

      Étape 2 : je vais tester le composant pour vérifier qu’il fonctionne comme je le pense et qu’il fait ce qu’on attend de lui. Je vais ajouter une suite des tests qui couvrent les différentes fonctionnalités et les vérifient en IPv4 et en IPv6, en HTTP 1.1 et en HTTP 2.0. Les tests utilisent Hurl et docker-compose (avec des images redis et nginx), et encore une fois l’idée de donner la possibilité de contribuer facilement. Ils comprennent des tests de types de contenus non pris en charge, le test de la limite à 5 MiB, différents types d’images, le test de vie, des appels erronés (mauvais chemin, mauvaise méthode, etc). Le choix des cas de tests est basé sur le trafic réellement constaté sur le serveur de production, sur les différents cas dans le code et un peu sur l’expérience du testeur.

      Étape 2,5 : l’avatar par défaut renvoie sur le site de production, y compris sur les tests en développement en local et sur le serveur de test du site. J’en profite pour ajouter un paramètre pour cela (et cela permettra de passer du PNG au SVG par défaut).

      Étape 3 : encore une fois essayons de simplifier la vie d’hypothétiques personnes contributrices. Une petite modification pour que hurl et redis soient fournis via docker-compose et ne soient plus nécessaires sur le poste de développement.

      Étape 4 : il est temps de documenter plus le fonctionnement. J’avais déjà décrit les infos stockées dans redis, mais pour comprendre le système de cache, autant fournir des diagrammes pour illustrer ce qui se passe lors d’une requête et comment on passe d’un état à un autre. C’est aussi l’occasion de compléter la suite de tests en ajoutant des tests avant et après expiration du cache, histoire de pouvoir documenter ces cas précis.

      Étape 5 : en cas d’échec de récupération, une image était indisponible jusqu’à la prochaine récupération (donc potentiellement pendant 10 min). Autant servir l’ancienne version en cache lorsque cela se produit : je modifie le code et les tests en conséquence.

      Étape 6 : je sais que certaines images ont été perdues, que des adresses d’images ont toujours été erronées, que des contenus et commentaires ont été supprimés et qu’il n’y a donc plus lieu de garder les images associées. Je décide d’implémenter dans img un audit interne qui indiquera si des anomalies sont présentes dans redis, si des images sont indisponibles ou si des entrées dans le cache disque ne correspondent plus à aucune image. Et j’ajoute cet audit dans la suite de tests.

      Étape 7 : j’écris une dépêche pour parler de tout cela.

      Évolutions récentes

      Dockerfile

      Le fichier Dockerfile du projet permet :

      • de partir d’une image officielle Go d’une version donnée, basée sur une distribution minimale Alpine
      • de l’utiliser pendant la construction en prenant la liste des dépendances, en les téléchargeant, en prenant l’unique fichier source img.go et en le compilant statiquement avec l’option pour retirer les chemins de compilation
      • de rechercher les éventuelles vulnérabilités avec govulncheck
      • d’ajouter le paquet tzdata pour avoir les définitions fuseaux horaires (nécessaire pour les conversions de/vers GMT pour les entêtes type Last-Modified).
      • de repartir d’une base Alpine en y mettant les définitions de fuseaux horaires et le binaire issus de la partie construction, de déclarer le port d’écoute et de lancer le binaire avec des variables disposant de valeurs par défaut.

      La suite de tests

      Pour l’utiliser, c’est assez simple, il faut aller dans le répertoire tests et lancer un docker-compose up --build, qui va produire le conteneur contenant img, et démarrer le redis et le nginx préconfigurés pour les tests. Si tout va bien, on attend, et au bout d’un moment il s’affiche :

      linuxfr.org-img-test_1  | All tests look good!
      tests_linuxfr.org-img-test_1 exited with code 0
      

      Rentrons un peu dans les détails.

      D’abord un fichier docker-compose.yaml qui décrit le réseau IPv4/IPv6 utilisé pour les tests, l’image redis qui sera utilisée (stockage géré par docker), l’image nginx qui sera utilisée avec sa configuration et ses fichiers à servir pour les tests, l’image img et son paramétrage (dont l’accès au redis et au nginx) ainsi que le répertoire du cache et enfin l’image de la suite de tests qui est construit avec son Dockerfile, prévue pour faire du Docker-in-Docker et avoir accès au cache img et aux fichiers nginx.

      Le Dockerfile de tests est basé sur une image Hurl (un outil pour faire des tests HTTP). On ajoute les fichiers de tests en .hurl, le script shell qui pilote le tout, on prévoit d’avoir les paquets dont on aura besoin : bash (pas par défaut dans les Alpine), coreutils, docker et xxd (pour les conversions texte vers hexadécimal). Et on lance les tests par défaut.

      La configuration nginx de test écoute en HTTP sur le port 80 en IPV4 et IPv6 et permet de définir des chemins avec des réponses en HTTP 301, 302, 308, 400, 401, 403, etc. jusqu’à 530 et même 666 pour les codes invalides, ainsi qu’une redirection infinie.

      Dans les données de tests servies par nginx, on trouve des contenus du mauvais type, une image destinée à être bloquée, des images dans divers formats, une image très grande en pixels mais pas trop en octets, une image trop grande en octets, et un avatar à servir par défaut.

      Sont aussi présents cinq fichiers de tests avec une extension en .hurl :

      • le test de vie et les chemins hors img/ et avatars/
      • les tests sur les avatars : adresse valide ou invalide, image inexistante, bon et mauvais types, comportements sur les différents codes HTTP et sur une boucle de redirection infinie
      • les tests sur les images (découpés en trois parties, la partie initiale, la partie entre la récupération initiale et l’expiration du cache et enfin la partie après la récupération et l’expiration du cache.

      Vient enfin le script shell qui pilote le tout :

      • on définit les variables pour les cibles IPv4/IPv6 et les binaires redis et img que l’on veut utiliser dans les autres conteneurs Docker
      • on liste les images dans différentes catégories :
        • celles qui vont échouer et ne comporteront donc qu’une entrée dans redis sans rien dans le cache disque (avec sous-catégories possibles bloquées/non-bloquées)
        • les images devant être en erreur
        • les images qui iront normalement dans le cache
      • on prépare des images qui seront altérées plus tard
      • on purge le cache sur disque, on nettoie redis et on déclare toutes nos images comme le faire le code Ruby on Rails. Certaines sont déclarées bloquées pour les tests.
      • on lance les premiers tests (en IPv4 et IPv6, en HTTP 1.1 et en HTTP 2.0)
      • on modifie certaines images pour simuler un changement sur le serveur externe, une suppression sur le serveur externe ou un blocage par l’équipe de site
      • on lance les tests post-récupération initiale mais avant l’expiration du cache (toujours avec toutes les variantes)
      • on force l’expiration du cache
      • on lance les tests post-expiration du cache (toujours avec toutes les variantes)
      • si on est arrivé jusqu’ici, c’est qu’on a passé tous les tests Hurl, alors maintenant on recompte ce que l’on a dans redis et sur disque et on vérifie si ça correspond à nos attentes
      • on nettoie les images mises volontairement en échec
      • on lance le test d’audit interne qui doit nous dire que tout va bien
      • si on est arrivé jusque-là on écrit que tout va bien et on déclenche un sourire de satisfaction.

      L’audit interne

      L’objectif est de vérifier la cohérence des données dans redis, si des images sont indisponibles ou si des entrées dans le cache disque ne correspondent plus à aucune image.

      Le binaire d’img peut donc être appelé en mode audit et lancer des contrôles internes.

      D’abord il collecte la liste des fichiers dans le cache disque.

      Ensuite il vérifie que toutes les images listées dans les dernières images (img/latest) existent comme entrées individuelles.

      Puis il vérifie s’il existe des images bloquées (il râlera s’il y en a) et si chacune existe comme entrée individuelle le cas échéant.

      Ensuite on parcourt tous les entrées individuelles d’images :

      • on râle si on tombe sur une entrée img/updated/ ou img/err/ sans date d’expiration
      • on râle si on tombe sur une entrée img/ sans champ created_at, sans type ou d’un type inconnu, sans checksum, avec un statut inconnu, une image bloquée non présente dans les images bloquées, un champ inconnu, une présence inattendue dans le cache disque, etc. Et on marque les images que l’on a vu passer comme attendu dans le cache.
      • on râle sur tous les fichiers du cache restants (ne correspondant à aucune image)
      • si on a râlé, on renvoie 1, sinon 0

      Le grand nettoyage

      img a fonctionné pendant 12 ans en production : il a rencontré des bugs, des comportements inattendus, des contenus et commentaires ont été supprimés ou réédités, etc. Il est donc probable qu’il y ait besoin d’aller dépoussiérer un peu tout cela et de retirer ce qui est inutile.

      Les traces du grand nettoyage sont d’abord visibles dans la rétrospective de la première quinzaine de septembre 2024 :

      • une « image » sur sept présente un souci (n’est pas une image, adresse invalide, trop grosse, etc.) et n’est donc pas dans le cache sur disque (ce qui a conduit à pas mal de taf sur la partie gestion des images)
      • les types de contenu (Content-Type) en provenance de sites variés et divers, c’est quelque chose… entre les « image/JPEG » ou « image/PNG » en majuscules parce que, les charset=utf-8 ou UTF-8 ou… sur du binaire, les name= qui ne sont pas dans la norme… Wikimedia renvoie aussi du profile="https://www.mediawiki.org/wiki/Specs/SVG/1.0.0" (pareil ça semble en dehors de tout standard).

      D’abord j’attaque le sujet la fleur au fusil en me disant que ça va passer crème, je fais un joli tableau qui résume l’état initial :

                                    img/<uri>   img/updated/<uri>   img/err/<uri>   blocked
      total                           25565 -21       634               160            5
      
      no created_at                      23 -23         0                 0            0
      created_at                       2857 -3          0                 5            1
      created_at+type                   222             0                 0            0
      total not in cache               3104 -26         0                 0            0
      
      created_at+type+checksum(+etag) 22463 +5        634               155            4
      
      files in cache                  22778 +5
      

      Donc on a officiellement 25 565 images, mais 23 sont mal créées (état théoriquement impossible hors race condition), 222 sont incomplètes (état théoriquement impossible race condition), 22 463 sont attendues en cache et on a 22 778 fichiers dans le cache. Ça part mal. Je nettoie en premier le plus facile (on voit le delta +/- de mes corrections). Et on arrive à une situation où une image sur sept présente alors un souci et il faut gérer un grand volume de corrections à faire.

      Parmi les soucis on trouve des types de contenus inattendus (image/PNG ou image/JPEG avec majuscules, image, des images binaires annoncées avec un charset, des types invalides comme image/jpg au lieu de image/jpeg, etc), des erreurs de notre lectorat (mauvais lien, mauvais copier-coller, lien vers une page web au lieu d’une image), mais aussi des espaces insécables et autres blancs inopportuns, des guillemets convertis, des doubles scheme (http://https:// ou http://file://).

      Après cela se cache une autre catégorie encore plus pénible : les images que l’on a en cache, mais qui ne sont plus utiles au site : par exemple celles qui étaient dans des contenus ou commentaires supprimés (notamment le spam), celles qui étaient dans des commentaires ou contenus réédités depuis, etc.

      Un problème connu est devenu vite pénible : on n’a pas d’association entre les images externes et les contenus/commentaires concernés. Donc il faut d’abord extraire la liste de toutes les déclarations d’images externes des 12 tables SQL où l’on peut trouver des images et des avatars, sous forme HTML ou Markdown.

      Ensuite il faut sortir toutes les entrées dans redis et regarder si on les retrouve en clair ou converties en hexadécimal dans l’extraction SQL.

      Et par sécurité on fera une double vérification pour celles détectées en erreur, en relançant une recherche en base (attention à la casse dans la recherche texte).

      Au final, on peut supprimer des milliers d’entrées redis et de fichiers dans le cache.

      Et un jour l’audit dit :

      Connection 127.0.0.1:6379 0
      2024/10/19 12:11:21 Sanity check mode only
      2024/10/19 12:11:37 Files in cache: 17926
      2024/10/19 12:11:39 Total img keys in redis: 18374
      OK
      

      Ça aura pris un mois et demi (l’audit a été fusionné le 8 septembre 2024), certes pas en continu, mais ça a été long et guère palpitant de faire ce grand ménage. Et j’ai refait une seconde passe du traitement complet la semaine d’après pour vérifier que tout se passait correctement et que les soucis résiduels après tout ça étaient minimes ou nuls.

      Parmi les anecdotes, Web Archive / archive.org a eu sa fuite de comptes utilisateurs et a été indisponible sur la fin (ce qui rendait compliqué la récupération d’images perdues ou leur remplacement par un lien valide par exemple). Et, mentionné dans la rétrospective de la seconde quinzaine de septembre 2024, un compte de spammeur de 2015 supprimé… mieux vaut tard que jamais : détecté parce que comme beaucoup de visiteurs, le spammeur ne fait pas la différence entre un lien vers un document et l’ajout d’une image.

      Les problématiques restantes

      Il y a la question habituelle de la montée de versions des dépendances (pour nous actuellement contraintes celles du code Ruby on Rails) et du remplacement des composants devenus non-libres (migrer vers valkey plutôt que redis ? Questions à se poser sur l’avenir de nginx ?).

      On pourrait aussi ajouter la prise en charge du TLS et d’un certificat X.509 directement dans img plutôt que dans un frontal. Mais ce n’est utile que si on les sépare sur deux serveurs distants, ce qui n’est pas le cas actuellement. Donc même si ça ne paraît pas compliqué à faire, ce n’est pas urgent.

      Ensuite une entrée de suivi existe pour séparer le cache des avatars du cache des autres images : les contraintes pour le cache des avatars étant différentes de celui des autres images, le stockage en cache devrait être différent. Cela reste un problème mineur. Le changement doit d’abord être fait côté Ruby on Rails pour définir les avatars avec des clés redis différentes (genre avatars/ au lieu de img/). Ensuite on peut modifier img pour séparer le traitement des requêtes HTTP /img/<adresse_hexa> vers les clés redis img/<adresse> et le cache disque des images par rapport aux requêtes /avatars/<adresse_hexa> vers les clés avatars/<adresse> et le cache des avatars. Il faudra aussi déplacer les avatars stockés dans l’actuel cache des images dans leur propre cache. Et là on devrait pouvoir avoir la même adresse dans les deux caches mais avec un rendu éventuellement différent.

      Un autre problème concerne la non-association des contenus ou commentaires avec les images externes qu’ils contiennent, ce qui rend l’administration des anciennes images un peu pénible. Le fait que les contenus et commentaires peuvent être réédités ou simplement prévisualisés (donc que des images peuvent être supprimées et d’autres ajoutées) vient compliquer un peu la tâche. Actuellement un ensemble de scripts permettent d’obtenir ces infos et fournissent un contournement, mais ça reste un peu laborieux.

      Un cache rafraîchi périodiquement conserve les images pour éviter de surcharger le site d’origine, pas si le site a changé, déplacé ou perdu l’image. La modification pour servir depuis le cache disque en cas d’échec de récupération couvre le cas de la disparition d’une image avec une erreur sur l’adresse, pas celui où le serveur répond une mauvaise image. Il y a donc une autre entrée de suivi images et disparition du web évoquant l’augmentation des soucis sur les images externes avec un cache rafraîchi, en raison des domaines récupérés par des spammeurs et autres pénibles, ou perdus ou utilisés pour du phishing (imageshack.us, après framapic, pix.toilelibre, etc.). Diverses problématiques sont mentionnées comme la perte d’information et donc la diminution de l’intérêt des contenus anciens, la prime aux pénibles du référencement SEO qui pourrissent le net en récupérant les vieux domaines, la modification possible des images publiées. Pour résoudre cela techniquement, ça nécessite de suivre les images et les domaines perdus, et d’intervenir de façon régulière. Ou bien de ne plus rafraîchir le cache (que cela soit jamais, après la publication ou au bout d’un certain temps après la publication). Pour juste éviter la perte d’info, il est possible de remplacer par une image locale récupérée d’une archive du net type archive.org, avec le côté « pénible à faire » et sans garantie que ça soit toujours possible (merci waybackpy).

      Enfin une troisième entrée de suivi suggère l'hébergement des images des dépêches (et éventuellement des journaux), idéalement en permettant d’avoir une version modifiée d’une image en changeant sa taille. On peut citer en vrac comme problématiques la responsabilité légale, l’éventuelle volumétrie, l’impossibilité de corriger une image publiée facilement par la personne qui l’a soumise, la centralisation et la perte de référencement pour des tiers, l’éventuelle rétroactivité et le traitement de l’historique, le fait qu’il faut traiter tous les autres contenus/commentaires pouvant accueillir des images, etc. Autre question, faut-il différencier les images passées en modération a priori de celles en modération a posteriori ?

      Conclusion ?

      Bref sans surprise, il reste des problématiques et du code à faire pour les gérer (c’est rare un composant sans demandes d’évolution ou de correction). Yapuka (mais probablement plus tard, il faut aussi partager le temps avec les autres composants, ou avoir plus de contributions).

      img apporte les fonctionnalités que l’on attendait de lui même si on pourrait faire mieux. Plonger dans ce composant s’est avéré assez intéressant et formateur (et nécessaire) : techniquement cela a été l’occasion de faire du Go, du docker et du docker-compose, du redis et du nginx, du hurl et de l’HTTP. Et de comprendre ce que faisait un code écrit par une autre personne, de se poser des questions pour choisir les tests et le contenu de la documentation, de se demander pour quelles raisons tel ou tel choix a été fait, de rendre ce composant plus « contribuable », et de compléter le tout de façon détaillée avec une dépêche. Reste à savoir si j’ai répondu à l’attente d’un article technique sur le fonctionnement de ce cache, les choix techniques qui ont été faits, les erreurs commises donc à éviter… et la réponse est à trouver dans les commentaires.

      Commentaires : voir le flux Atom ouvrir dans le navigateur

      ❌