Proton/fr

Proton permet aux utilisateurs de télécharger un article de Wikipedia au format PDF. Il prend en charge à la fois les impressions de bureau et les impressions conviviales pour les mobiles.

Détails techniques
Proton est un service simple qui génère le PDF en utilisant la bibliothèque Chromium activée par by Puppeteer. Il est formé de deux composants :
 * la file d'attente qui enregistre toutes les demandes (car la génération de PDF est une tâche qui consomme des ressources et beaucoup de temps)
 * le code du générateur qui indique à Puppeteer d'imprimer la page demandée en tant que PDF.

Proton est structuré comme un service web. Il est écrit en JavaScript et utilise Node.js. Son but est de fournir des PDFs jolis et propres. Sur les wikis Wikimedia, Proton est accédé via le proxy RESTBase. Il utilise la bibliothèque puppeteer-core ; le navigateur chromium n'est pas livré avec puppeteer-core et doit être téléchargé séparément. La variable d'environnement  désigne l'emplacement de l'exécutable chromium.

La meilleure manière de générer le PDF d'un article est d'utiliser la fonctionnalité d'impression en PDF de votre navigateur. Cette méthode fournit les meilleurs résultats et en plus elle nous permet de réutiliser les styles d'impression disponibles à la fois pour les versions bureau et mobile de Wikipedia. Le système ne réalise pas le post-traitement du HTML demandé. Les articles sont imprimés tels qu'ils apparaîssent dans l'aperçu avant impression, dans le navigateur de l'utilisateur. Les PDFs générés sont très similaires (si non identiques) à ce que chacun peut obtenir en utilisant Imprimer en PDF dans son navigateur Chrome. Pour obtenir les meilleurs résultats, Proton désactive JavaScript. C'est fait pour empêcher toute transformation dynamique de contenu, comme le chargement des images lazy-load sur les pages pour mobile.

Principes de la file d'attente
La file d'attente est le coeur du générateur Proton. Il gère le flot de chaque tâche au travers de la logique attente/traitement/expiration. Chaque tâche de la file d'attente peut prendre deux états - 'en attente' et 'en cours de traitement'. Le système de la file d'attente ne permet pas uniquement d'exécuter une quantité de tâches en parallèle, mais il gère aussi le dépassement du temps d'exécution ainsi que l'annulation des tâches. A cause de la complexité de la file d'attente, nous avons dû implémenter une solution qui nous permette de :


 * limiter le nombre de tâches en attente
 * rejeter les tâches en attente après un délai prédéfini
 * limiter le nombre de tâches de génération en cours (car la génération du PDF demande beaucoup de ressources)
 * d'avoir un filet de sécurité pour rejeter les tâches de génération qui prennent trop de temps
 * d'essayer d'annuler la tâche lorsque la requête est abortée afin d'économiser des ressources, et ce quelque soit l'état de cette tâche (traitement/génération).

La gestion de la file d'attente est basée sur les promesses de Bluebird, et utilise la fonctionnalité d'annulation détaillée ci-dessous.

Générateur
Le générateur est une simple façade pour accéder à la méthode  de la bibliothèque puppeteer. Renderer is responsible for setting proper chromium environment and browser viewport, requesting the Wikipedia page, calling the  function. De plus il garde un oeil sur le processus du navigateur. Chaque génération commence par la création d'une instance Chromium et une fois la génération terminée, le processus Chromium se termine. To save resources, and keep our system in good state Renderer asks Chromium to shut down and if because of any reason browser still keeps processing the request it will send the  to browser process to make sure it doesn't use any more CPU nor the memory.

Fonctionnalités supplémentaires
When a job fails because the queue is full or job timeouts in any state the Proton service will return  response with Retry-After header. The Retry-After header instruments load balancer to depool given Proton node so it can finish processing current jobs. System sets Retry-After header to  configuration value. After that time all processing jobs should finish, and the system should be able to pick up new jobs.

Contournements connus
Proton utilise la fonctionnalité d'annulation de BBPromise. Cancellation feature is disabled by default, to enable promise cancellation BBPromise.config has to be called with  flag. Le raison est que la configuration de BBPromise doit être définie avant que toute promesse ne soit créée. But because Proton uses the Service-runner, and Service-runner uses BBPromises for everything, even reading configuration files this wasn't easy to implement. The  flag cannot be set in the Proton application, because the Proton code is executed after Service-runner initialization. It also couldn't be defined in config, as Service-runner uses promises when reading the config. In version 2.6.6 of Service-runner introduces use of the  environment variable, which has to be set to truthy value. Si la variable d'environnement n'est pas définie, l'initialisation de Proton va échouer avec erreur.

Pour prendre en charge une grande variété de langues nous vous recommandons d'installer les fontes suivantes durant le déploiement :


 * fonts-liberation
 * fonts-noto
 * fonts-noto-cjk
 * fonts-noto-cjk-extra
 * fonts-noto-color-emoji
 * fonts-noto-extra
 * fonts-noto-mono
 * fonts-noto-ui-core
 * fonts-noto-ui-extra
 * fonts-noto-unhinted

Développement
Development happens in the. La relecture de code se fait dans Gerrit. Voir Débuter avec Gerrit pour créer votre compte. Service uses the ServiceTemplateNode project template and follows all Service development rules.

Exécuter les tests
To run all swagger tests and mocha tests:

npm test

Pour exécuter tous les tests de couverture :

npm run coverage

Documents techniques

 * README.MD contient la documentation concernant les variables internes et les paramètres de configuration.
 * Déploiement du service Proton
 * Les styles d'impression et les limitations sont identiques aux styles d'impression du navigateur.

Liens pour les développeurs Proton

 * dépôt Github Proton
 * documentation Puppeteer
 * documentation BBPromise

Voir aussi

 * RESTBase: une API de proxy pour mettre en cache ou enregistrer les PDF générés par Proton
 * Proton: détails sur la gestion, le déploiement et le flux de données
 * Proton: détails sur la gestion, le déploiement et le flux de données

Contact
Si vous avez besoin d'aide ou si vous avez des questions ou des commentaires, vous pouvez nous contacter sur ou via la liste de diffusion wikitech-l.