Proton/cs

Projekty Wikimedia Foundation Proton Vygenerujte PDF verzi libovolného článku Wikipedie Skupina: Čtenáři Začal: 2018-12 Historie změn: #Proton

Proton umožňuje uživatelům stáhnout si článek z Wikipedie jako PDF. Podporuje tisk vhodný pro stolní i mobilní zařízení.

Technické podrobnosti

Proton je jednoduchá služba, která generuje PDF pomocí Chromium řízené knihovnou Puppeteer. Skládá se ze dvou složek:

• Systém front, který řadí všechny požadavky do fronty (protože generování PDF je náročné na zdroje i čas)
• Vykreslovací kód, který dává pokyn Puppeteer vytisknout požadovanou stránku jako PDF.

Proton je strukturován jako webová služba a je napsán v JavaScriptu s využitím Node.js. Jeho cílem je poskytovat krásné a čisté soubory PDF. Na wikinách Wikimedie bude Proton zastoupen na RESTBase. Používá knihovnu puppeteer-core, prohlížeč chromium není součástí puppeteer-core a je nutné jej stáhnout samostatně. Proměnná prostředí PUPPETEER_EXECUTABLE_PATH se používá k odkazování na spustitelný soubor chromium.

Nejlepší způsob, jak vygenerovat článek PDF, je použít funkci prohlížeče zabudovanou do PDF. Tato metoda poskytuje nejlepší výsledky a navíc nám umožňuje znovu použít stávající styly tisku dostupné pro desktopovou i mobilní verzi Wikipedie. Systém nezpracovává požadované HTML. Články se tisknou stejným způsobem, jako se zobrazují v náhledu tisku v prohlížeči uživatele. Vygenerované soubory PDF jsou velmi podobné (ne-li totožné) s tím, čeho může kdokoli dosáhnout pomocí Tisk do PDF ve svém prohlížeči Chrome. Pro dosažení nejlepších výsledků Proton zakáže JavaScript. Provádí se za účelem deaktivace všech transformací dynamického obsahu, jako jsou pomalu načítané obrázky na mobilních stránkách.

Poznámka: pro některé uživatele se může PDF, které získají z tisku prohlížeče, a to, které získají ze služby Proton, trochu lišit, protože konfigurace písem v uživatelském systému může mít specifická nastavení související s hintingem/kerningem písem.

QueueSystem – systém front

Systém Queue je srdcem rendereru Proton. Zpracovává tok každé úlohy prostřednictvím logiky čekání/zpracování/časový limit. Každá úloha ve frontě může mít dva stavy – čekání a zpracování. Systém front nejenže umožňuje spouštění určitého počtu úloh současně, ale také zpracovává časové limity úloh a jejich zrušení. Kvůli složitosti fronty jsme museli implementovat řešení, které nám umožňuje:

• omezit počet čekajících úloh
• po definovaném počtu sekund odmítnout čekající úlohu
• omezit počet vykreslovacích úloh (protože vykreslování PDF vyžaduje spoustu zdrojů)
• záchranná síť pro odmítnutí renderovacích úloh, které zabírají příliš mnoho času
• pro úsporu zdrojů, když je požadavek přerušen, fronta se pokusí zrušit úlohu, nezáleží na tom, v jakém stavu se přerušená úloha nachází (zpracování/vykreslování).

Systém front je založen na slibech Bluebird a využívá funkci zrušení (o které viz #Známé hacky níže).

Renderer

Renderer je jednoduchá fasáda pro přístup k metodě page.pdf() z knihovny loutkářů. Renderer je zodpovědný za nastavení správného prostředí chromium a zobrazované oblasti prohlížeče, vyžádání stránky Wikipedie a volání funkce page.pdf(). Navíc dohlíží na proces prohlížeče. Každé vykreslení spustí novou instanci Chromium a po úspěšném vykreslení se proces Chromium ukončí. Aby se šetřily zdroje a udržoval náš systém v dobrém stavu, Renderer požádá Chromium o vypnutí, a pokud z nějakého důvodu prohlížeč stále zpracovává požadavek, odešle procesu SIGKILL do prohlížeče, aby se ujistil, že se tak nestalo. Nepoužívejte další CPU ani paměť.

Další funkce

Když se úloha nezdaří, protože fronta je plná nebo vyprší časové limity úlohy v jakémkoli stavu, služba Proton vrátí odpověď 503 Služba není k dispozici s hlavičkou Retry-After. Záhlaví Retry-After nástroje pro vyrovnávání zatížení, aby se shromáždil daný uzel Proton, aby mohl dokončit zpracování aktuálních úloh. System sets Retry-After header to app.config.render_queue_timeout configuration value. After that time all processing jobs should finish, and the system should be able to pick up new jobs.

Known hacks

Proton utilizes the BBPromise cancellation feature. Cancellation feature is disabled by default, to enable promise cancellation BBPromise.config() has to be called with cancellation:true flag. The trick is that the BBPromise config has to be set before any promise is created. 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 cancellation 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 APP_ENABLE_CANCELLABLE_PROMISES environment variable, which has to be set to truthy value. If the environment variable is not set, Proton initialization will fail with error.

In order to support a wide variety of languages its suggested to install the following fonts in the deployment:

• 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

Development

Development happens in the Proton service Git repository. Code review happens in Gerrit. See Getting started to set up an account for yourself. Service uses the ServiceTemplateNode project template and follows all Service development rules.

Running the tests

To run all swagger tests and mocha tests:

npm test

To run all coverage tests:

npm run coverage

Technical documents

• README.md has the documentation about Proton internals and configuration variables.

• Kubernetes deployment How to deploy Proton (for example) service

• Reading/Web/Projects/Print Styles - Print styles and limitations are identical to Browser print styles.

Links for Proton developers

• Proton Gerrit repository

• Proton GitHub repository

- mirrored from Gerrit

• Puppeteer documentation

• BBPromise documentation

See also

• PDF export

• RESTBase : a caching / storing API proxy for PDFs generated by Proton
• wikitech:Proton: details on monitoring, deployment, and data flow

Contact

If you need help or have questions/feedback, you can contact us in #wikimedia-infrastructure ^{připojit se} or the wikitech-l mailing list.