html-to-pdf/documentation/README.md

Dokumentace sluzby html-to-pdf

Sluzba prevadi HTML dokument na PDF. Prijme adresu dokumentu nebo HTML primo v tele requestu a vrati soubor PDF. Zvlada dokumenty o tisicich stranek.

Obsah dokumentace

• api.md popis endpointu a tel requestu
• architektura.md jak sluzba funguje uvnitr
• konfigurace.md environment variables
• provoz.md nasazeni, Docker, znama omezeni
• zmeny.md zaznam zmen

Aktualni stav

Verze 1.0.1, stav development.

Hotovo:

• synchronni endpoint POST /convert
• asynchronni endpoint POST /jobs se sledovanim stavu a stahovanim vysledku
• dva render enginy, weasyprint a chromium, plus rezim auto
• chunkovani velkych dokumentu a slucovani vysledku
• dvoupruchodovy render obsahu se skutecnymi cisly stranek
• cislovani stranek pres CSS countery nebo pres cislovaci vrstvu
• SSRF ochrana s kontrolou po DNS resolvu a na kazdem presmerovani
• hlaseni nedostupnych assetu v odpovedi jobu
• fronta s omezenym poctem paralelnich workeru
• volitelny callback po dokonceni jobu
• strukturovane JSON logovani s job_id
• obchazeni chyby WeasyPrintu u obrazku s procentualni sirkou v bunce tabulky
• Swagger popisuje moznosti strankovani i uchovavani souboru

Neni hotovo a neni ani v zadani:

• autentizace. Sluzba je bez overovani, pristup resi reverse proxy. Pokud ma byt chranena, je potreba se domluvit na zpusobu, typicky hlavicka X-Api-Key. Do te doby zadna neni.
• trvala fronta. Restart sluzby znamena ztratu rozpracovanych jobu, ty se oznaci jako failed s duvodem service_restarted.

Rychly priklad

curl -X POST https://services.csbot.cz/apps/html-to-pdf/convert \
  -H "Content-Type: application/json" \
  -d '{"source": {"url": "https://example.com/dokument.html"}}' \
  --output dokument.pdf

Pro velky dokument se pouziva asynchronni cesta:

curl -X POST https://services.csbot.cz/apps/html-to-pdf/jobs \
  -H "Content-Type: application/json" \
  -d '{"source": {"url": "https://example.com/velky.html"}, "toc": {"enabled": true}}'