# Provoz

## Docker image

Image je dvoufazovy. Prvni faze stavi zavislosti, do vysledneho image se
prekladace nedostanou.

Runtime obsahuje:

- systemove knihovny WeasyPrintu: cairo, pango, gdk-pixbuf, harfbuzz
- Chromium nainstalovany pres `playwright install --with-deps chromium`
- fonty DejaVu, Liberation a Noto vcetne ceske diakritiky
- `qpdf` jako zaloha pro praci s PDF
- `curl` pro healthcheck

Image je velky, radove jednotky GB. To je u sluzby, ktera v sobe ma cely
prohlizec a dve renderovaci knihovny, ocekavane.

## Port

Sluzba posloucha na `0.0.0.0:8000`, coz odpovida `app.yml`. Port se nemeni bez
odpovidajici upravy metadat aplikace v AppFactory.

## Healthcheck

Dockerfile ma `HEALTHCHECK`, ktery vola `/health` na `127.0.0.1:8000`.
Endpoint pri kazdem volani overuje dostupnost enginu vcetne skutecneho
nastartovani Chromia.

## Sdilena pamet pro Chromium

Chromium se spousti s `--disable-dev-shm-usage`, takze si vystaci s malym
`/dev/shm`. Pokud by se v logu objevovaly pady rendereru, je potreba containeru
zvysit `--shm-size`.

## Overeni po nasazeni

```bash
curl -i https://services.csbot.cz/apps/html-to-pdf/health
curl -i https://services.csbot.cz/apps/html-to-pdf/docs
```

Ve Swagger UI overit, ze Try it out vola adresy s prefixem
`/apps/html-to-pdf`, ne bez nej.

Pozor na znamou vlastnost AppFactory: Caddy propousti GET pozadavky jen
z omezeneho seznamu IP adres. Try it out ve Swaggeru proto muze z bezneho
prohlizece vracet 403 jako `text/plain`, i kdyz je sluzba v poradku. Overovat
curlem primo ze serveru.

## Logy

Kazdy zaznam je jeden radek JSON. Vsechno, co patri k jednomu jobu, nese
`job_id`.

Co stoji za sledovani:

- `Asset could not be loaded` v PDF neco chybi
- `WeasyPrint render failed, falling back to Chromium` dokument neprosel
  primarnim enginem
- `Restarting Chromium to release memory` bezna udrzba, ne chyba
- `Callback could not be delivered` job dobehl, ale klient se to nedozvedel
- `Job failed` konverze selhala, kod chyby je v poli `error_code`

Secrets se do logu nezapisuji.

## Znama omezeni

- Fronta je v pameti procesu. Restart znamena ztratu rozpracovanych jobu, ty se
  oznaci jako failed s kodem `service_restarted`.
- Obsah s cisly stranek umi jen WeasyPrint. Chromium neumi rict, na ktere
  strance nadpis skoncil.
- U cleneneho dokumentu nejsou odkazy v obsahu klikatelne, protoze cil lezi
  v jine casti souboru. Cisla stranek jsou spravna a sluzba na to upozorni ve
  `warnings`.
- Slucovani pres pypdf drzi stranky vysledku v pameti. Je to nejnarocnejsi krok
  konverze.
- WeasyPrint nespousti JavaScript. Pro dokumenty dokreslovane skripty je nutne
  Chromium.
- WeasyPrint neumi procentualni sirku obrazku uvnitr bunky tabulky. Sluzba to
  obchazi prepsanim na `width: auto`, viz api.md. Podobne vlastnosti se mohou
  objevit i jinde, protoze WeasyPrint neni prohlizec. Kdyz neco v PDF chybi
  a `missing_assets` je prazdne, stoji za to zkusit `engine: chromium`.

## Testy

Testy se spousti jen na vyslovne pozadani, nikdy automaticky.

```bash
pip install -r requirements-dev.txt
pytest                    # bez pomalych testu spusti vse ostatni
pytest -m slow            # jen mereni nad dokumentem o zhruba 1200 strankach
```

Testy, ktere potrebuji WeasyPrint, se same preskoci, pokud neni nainstalovany.

Co je pokryte:

- SSRF vcetne domeny mirici na 127.0.0.1
- deleni dokumentu, ktery se delit da, i toho, ktery se delit neda
- spravnost cisel stranek po slouceni
- obsah ukazuje na skutecne stranky
- nedostupny asset render nezastavi a objevi se v odpovedi
- procentualni sirka obrazku v bunce tabulky se prepise na auto
- zruseni beziciho jobu, plna fronta, chovani pri ukonceni sluzby