bidi2pdf 0.1.20 → 0.1.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 523b63ba5c422c92dd950e0045261ebcd9b888d042d930fa312b87b4c94f3e31
-  data.tar.gz: b6aeb5c8ba74244bd890434a0c46ed18c92afd827dfaa47a9520fca20039d676
+  metadata.gz: 93fc35bee7628afb6627782be91a2fc62caf14f8f365929c166f133d74adebfc
+  data.tar.gz: ca9381a65bd24341c2e486f34fd47f920fbf996e540c54fb421129c2f175f29e
 SHA512:
-  metadata.gz: 7dbae17f4831478c506f67a0b1e72ca4890b2716c183e5c25b40a68e9009c78f12d8414bae9f9fc4e5f6eab52e51d04c9c217ed0b48cd73f8d54af3d4feca9e6
-  data.tar.gz: 000bc92f8ea29444b652f45e48ef9daca4f460e90d71cc731b84e825e32e20296b24df6161febc2efc214bd4fa74577079634a23260785235c4bf977ec49c53b
+  metadata.gz: a457600c1c6a638ee87a28d4f6221918b754a065d6d07acef9e057a4a6a3dce7c0411947cf2c340cb0a5e0ff62171bd9e934f65ca9bd15d9d514f754de11746c
+  data.tar.gz: 383a01704a6871e5e5aafcd7fdd7a97e499009fb7cba63e13adfe2f08c91ba190b78a9d2117e02fd22de1381686c61ab1c94f43fb2d6b6e92e45c9365cfb5122

data/CHANGELOG.md

@@ -8,10 +8,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.20..HEAD
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.21..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [0.1.21] - 2026-10-09
+
+### 🐛 Fixed
+- Define the word the hyphenation control prints
+- Run image specs against the image from the PR
+- Pin hyphenation data to a fixed language set
+- Check hyphenation in the published image
+- Move the hyphenation spec to its own PR
+- Build chromedriver images one at a time
+- Read watchdog settings as decimal numbers
+- Close spares first and free their leases
+
+### 🔄 Changed
+- Merge pull request #159 from dieter-medium/feat/hyphenation-spec
+- Merge pull request #158 from dieter-medium/feat/hyphenation-data
+- Merge pull request #157 from dieter-medium/fix/chromedriver-build-race
+- Merge pull request #156 from dieter-medium/feat/chromedriver-watchdog
+- Merge pull request #155 from dieter-medium/feat/shutdown-deadline
+
+### 🚀 Added
+- Install hyphenation dictionaries in the images
+- Restart a stuck chromedriver container
+- Bound the warmer shutdown by a deadline
+
 ## [0.1.20] - 2026-09-30
 
 ### 🐛 Fixed
@@ -531,7 +555,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 🔄 Released
 
-- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.20..HEAD)
+- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.21..HEAD)
+- [0.1.21](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.20..v0.1.21)
 - [0.1.20](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.19..v0.1.20)
 - [0.1.19](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.18..v0.1.19)
 - [0.1.18](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.17..v0.1.18)

data/README.md

@@ -459,6 +459,67 @@ the box in either image, no extra install step needed.
 Chromium comes from Debian's packages at build time, so every build can carry a different
 Chromium - for a byte-exact pin use the digest (`docker buildx imagetools inspect <image:tag>`).
 
+### Hyphenation
+
+The images (`chromedriver`, `bidi2pdf` and its slim variant) ship Chromium's hyphenation dictionaries
+in `/usr/lib/chromium/hyphen-data/`, so CSS `hyphens: auto` breaks long words in the page's language
+(`lang="de"` on the element or the document) - for exactly these languages, by the `lang` tag Blink
+maps to each dictionary (case does not matter; Blink drops trailing subtags until one matches):
+
+| `lang` | Dictionary |
+|---|---|
+| `de`, `de-DE`, `de-AT`, `de-CH` (and `de-DE-1901` - the region wins) | German, 1996 spelling (`de-1996`) |
+| `de-1901` | German, traditional spelling |
+| `de-CH-1901`, `de-LI-1901` | Swiss German, traditional spelling |
+| `en`, `en-US` | US English |
+| `en-GB`, `en-AU`, `en-IE`, ... (every other `en-*`) | British English |
+| `fr`, `es`, `it`, `nl`, `pt` (with any region, e.g. `pt-BR`) | French, Spanish, Italian, Dutch, Portuguese |
+
+The hyphenation spec prints one word in each of these, against a control without hyphenation.
+Debian's Chromium has none, and the component it would download needs a profile that outlives the
+session. `docker/install-hyphen-data.sh` fetches them at build time from Chromium's source, pinned by
+the `HYPHEN_DATA_REF` build argument - deliberately independent of the Debian Chromium the image
+installs, since the pattern data and its format change far more rarely; the hyphenation spec catches a
+Chromium that stops reading them - with their licence notice (`LICENSE` next to them). Do not pass `--disable-component-update` in
+`chrome_args`: Chromium then skips the dictionaries.
+
+### ChromeDriver health check and watchdog
+
+The image has a Docker `HEALTHCHECK` (chromedriver's `/status`), so `docker ps` shows a
+chromedriver that stopped answering as `unhealthy`. It does not see a Chrome that is wedged behind
+a chromedriver that still answers - memory thrashing shows only to the watchdog. And Docker does
+not restart a container for being unhealthy - only when its main process exits.
+
+That is what the opt-in watchdog does. With `WATCHDOG_ENABLED=true` it checks every
+`WATCHDOG_INTERVAL` seconds and, after `WATCHDOG_FAILURES` failed checks in a row, stops
+chromedriver; the container exits non-zero and its restart policy starts a fresh one - any policy
+but `no` (`--restart unless-stopped` or `on-failure`, `restart:` in Compose; Kamal sets
+`unless-stopped` for accessories). Without one, a watchdog restart just stops the container. A
+check fails when chromedriver does not answer `/status`, or when the
+container's memory thrashes: Linux's pressure stall information (`memory.pressure`, "full") shows
+every task stalled on memory for at least `WATCHDOG_MEMORY_PRESSURE` percent of the last 10 s - a
+Chrome swapping at its memory limit, which answers no command but never crashes.
+
+Renders still running on that Chrome fail when it restarts; a client with a sweeper retries them.
+
+| Variable                   | Default                          | Description                                                  |
+|----------------------------|----------------------------------|--------------------------------------------------------------|
+| `WATCHDOG_ENABLED`         | `false`                          | `true` starts the watchdog.                                  |
+| `WATCHDOG_INTERVAL`        | `15`                             | Seconds between checks.                                      |
+| `WATCHDOG_FAILURES`        | `3`                              | Failed checks in a row before the restart.                   |
+| `WATCHDOG_STATUS_TIMEOUT`  | `5`                              | Seconds `/status` may take.                                  |
+| `WATCHDOG_MEMORY_PRESSURE` | `50`                             | "full avg10" percent that fails a check; `0` turns it off.   |
+| `WATCHDOG_STOP_GRACE`      | `10`                             | Seconds between stopping chromedriver (TERM) and killing it. |
+| `WATCHDOG_PRESSURE_FILE`   | `/sys/fs/cgroup/memory.pressure` | The PSI file; without one (cgroup v1, PSI off) only `/status` counts. |
+
+All values are whole numbers (seconds, percent). A malformed value stops the watchdog from
+starting - chromedriver keeps running unwatched, and the container log says why.
+
+Picking `WATCHDOG_MEMORY_PRESSURE`: "full" counts only the time *every* task waited on memory, so it
+stays near 0 while renders merely run; 50 % of the last 10 s is a container that is stuck, not busy.
+Before lowering it, watch `/sys/fs/cgroup/memory.pressure` inside the container under your usual
+render load and stay well above what you see there.
+
 ### Docker Compose
 
 ```bash
@@ -574,6 +635,7 @@ Bidi2pdf::SessionWarmer.shutdown
 | `registry_dir`       | `Dir.tmpdir`          | Where the session registry file lives - every process that should clean up after the others must share it. |
 | `sweeper`            | `nil`                 | Remote only: settings for a [`ChromeSweeper`](#leaked-chrome-sessions-bidi2pdfchromesweeper) on the same chromedriver, e.g. `{ scope: :all, max_sessions: :auto, pids_limit: 1024, interval: 60 }`. The warmer's own sessions are never touched; `Bidi2pdf::SessionWarmer.sweep!` sweeps on demand. |
 | `retry_refused_sessions` | `true`         | With a `sweeper`: when chromedriver refuses a new session, sweep under pressure and try once more. `false` leaves it to the caller. |
+| `shutdown_timeout`   | `10`                  | Seconds `shutdown` waits, all in all, for its background threads and for closing the warm sessions. `nil` waits for ever. |
 
 #### Leftover sessions on a shared chromedriver
 
@@ -595,6 +657,13 @@ With a `sweeper` configured, the warmer also sweeps in the background every `int
 and when chromedriver refuses a new session ("session not created" - typically a container out of
 room for another Chrome) it sweeps once and tries once more.
 
+`shutdown` is bounded by `shutdown_timeout`. A Chrome that hangs or ran out of memory answers no
+command, and closing each of its sessions would wait out every command timeout in turn - long
+enough that a stopping server looks hung. At the deadline the warmer stops waiting, logs what is
+still running and instruments `session_warmer.shutdown_timeout.bidi2pdf` (`timeout`, `pending`);
+`shutdown` returns the same tally, e.g. `{ "spare" => 1 }`, and `{}` when everything finished.
+Sessions it could not close stay in the registry, so a later sweep closes them.
+
 > **Security note:** an idle warm session is an open, unauthenticated automation endpoint
 > (chromedriver's port, Chrome's debugging port - loopback only for a local chromedriver) for as
 > long as it waits. `max_idle_age` bounds that window; keep it set unless the process runs somewhere
@@ -663,7 +732,7 @@ session is refused.
 | `pids_limit`          | `nil`       | The chromedriver container's pids limit (Docker counts threads). `:auto` without it means no limit.         |
 | `pids_budget`         | `0.8`       | Share of `pids_limit` the Chrome sessions may use.                                                           |
 | `threads_per_session` | `110`       | Threads one Chrome session uses.                                                                             |
-| `interval`            | `nil`       | Seconds between background sweeps (`start`/`stop`).                                                          |
+| `interval`            | `nil`       | Seconds between background sweeps (`start`/`stop`). `stop(timeout: 10)` waits that long for a sweep in progress, then stops waiting and returns `false` (`nil` waits for ever). |
 | `dry_run`             | `false`     | Report what would be closed, close nothing.                                                                  |
 | `registry_dir`        | `Dir.tmpdir`| The registry to read and update - same meaning as the warmer's setting.                                      |
 | `own_sessions`        | `-> { [] }` | A callable returning the caller's live session ids; they are never touched.                                  |

data/docker/Dockerfile

@@ -13,11 +13,23 @@ RUN apt-get update && apt-get upgrade -y &&\
     libatk-bridge2.0-0 \
     libgtk-3-0 \
     libdrm2 \
-    curl \
+    curl ca-certificates \
     unzip \
     xvfb \
     && rm -rf /var/lib/apt/lists/*
 
+# Chromium's hyphenation dictionaries, so that `hyphens: auto` works in the PDFs. Debian's chromium
+# ships none and Chrome cannot download them here - see docker/install-hyphen-data.sh for the whole
+# story. They go next to the chromium binary, where the component installer looks for a bundled copy.
+# The patterns are data files and intentionally do not track the Debian Chromium installed above (the
+# minikin .hyb format is unchanged since 2016, the files since 2023): update this ref when the pattern
+# data itself changes. The hyphenation integration spec, run against the image's own Chromium, catches
+# a Chromium that stops reading them.
+ARG HYPHEN_DATA_REF=refs/tags/154.0.8037.92
+COPY ./docker/install-hyphen-data.sh /usr/local/bin/install-hyphen-data.sh
+RUN chmod +x /usr/local/bin/install-hyphen-data.sh && \
+    /usr/local/bin/install-hyphen-data.sh "${HYPHEN_DATA_REF}" /usr/lib/chromium/hyphen-data
+
 # Create a non-root user
 RUN groupadd -r appuser && useradd -r -g appuser -m -d /home/appuser appuser
 

data/docker/Dockerfile.chromedriver

@@ -18,7 +18,7 @@ RUN echo "deb http://deb.debian.org/debian bookworm contrib non-free" > /etc/apt
     libatk-bridge2.0-0 \
     libgtk-3-0 \
     libdrm2 \
-    curl \
+    curl ca-certificates \
     unzip \
     xvfb \
     x11vnc \
@@ -34,11 +34,24 @@ RUN echo "deb http://deb.debian.org/debian bookworm contrib non-free" > /etc/apt
     && locale-gen en_US.UTF-8 \
     && rm -rf /var/lib/apt/lists/*
 
+# Chromium's hyphenation dictionaries, so that `hyphens: auto` works in the PDFs. Debian's chromium
+# ships none and Chrome cannot download them here - see docker/install-hyphen-data.sh for the whole
+# story. They go next to the chromium binary, where the component installer looks for a bundled copy.
+# The patterns are data files and intentionally do not track the Debian Chromium installed above (the
+# minikin .hyb format is unchanged since 2016, the files since 2023): update this ref when the pattern
+# data itself changes. The hyphenation integration spec, run against the image's own Chromium, catches
+# a Chromium that stops reading them.
+ARG HYPHEN_DATA_REF=refs/tags/154.0.8037.92
+COPY ./docker/install-hyphen-data.sh /usr/local/bin/install-hyphen-data.sh
+RUN chmod +x /usr/local/bin/install-hyphen-data.sh && \
+    /usr/local/bin/install-hyphen-data.sh "${HYPHEN_DATA_REF}" /usr/lib/chromium/hyphen-data
+
 # Create a non-root user
 RUN groupadd -r appuser && useradd -r -g appuser -G audio,video -m -d /home/appuser appuser
 
 COPY ./docker/entrypoint.sh /usr/local/bin/entrypoint.sh
-RUN chmod +x /usr/local/bin/entrypoint.sh
+COPY ./docker/chromedriver-watchdog.sh /usr/local/bin/chromedriver-watchdog.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh /usr/local/bin/chromedriver-watchdog.sh
 
 # ARM compatibility workaround:
 # On ARM architectures (such as Apple Silicon), downloading chromedriver via automated scripts may fail or cause ELF binary errors,
@@ -69,4 +82,9 @@ EXPOSE ${CHROMEDRIVER_PORT}
 # VNC
 EXPOSE 5900
 
+# Marks the container "unhealthy" in docker ps when chromedriver stops answering. Docker does not
+# restart it for that - WATCHDOG_ENABLED=true does (chromedriver-watchdog.sh).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD curl -fs -m 4 -o /dev/null "http://127.0.0.1:${CHROMEDRIVER_PORT}/status" || exit 1
+
 CMD ["/usr/local/bin/entrypoint.sh"]

data/docker/Dockerfile.slim

@@ -50,13 +50,25 @@ RUN apt-get update && apt-get upgrade -y &&\
     libatk-bridge2.0-0 \
     libgtk-3-0 \
     libdrm2 \
-    curl \
+    curl ca-certificates \
     unzip \
     xvfb \
     && rm -rf /var/lib/apt/lists/*
 
 COPY --from=builder /usr/local/bundle /usr/local/bundle
 
+# Chromium's hyphenation dictionaries, so that `hyphens: auto` works in the PDFs. Debian's chromium
+# ships none and Chrome cannot download them here - see docker/install-hyphen-data.sh for the whole
+# story. They go next to the chromium binary, where the component installer looks for a bundled copy.
+# The patterns are data files and intentionally do not track the Debian Chromium installed above (the
+# minikin .hyb format is unchanged since 2016, the files since 2023): update this ref when the pattern
+# data itself changes. The hyphenation integration spec, run against the image's own Chromium, catches
+# a Chromium that stops reading them.
+ARG HYPHEN_DATA_REF=refs/tags/154.0.8037.92
+COPY ./docker/install-hyphen-data.sh /usr/local/bin/install-hyphen-data.sh
+RUN chmod +x /usr/local/bin/install-hyphen-data.sh && \
+    /usr/local/bin/install-hyphen-data.sh "${HYPHEN_DATA_REF}" /usr/lib/chromium/hyphen-data
+
 # Create a non-root user
 RUN groupadd -r appuser && useradd -r -g appuser -m -d /home/appuser appuser
 

data/docker/chromedriver-watchdog.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+# Restarts the chromedriver container when Chrome is in a state it does not recover from by itself:
+# chromedriver no longer answers /status, or the container's memory is thrashing (PSI "full" - every
+# task stalled on memory for that share of the last 10 s). It stops chromedriver, entrypoint.sh
+# exits, and the container's restart policy (unless-stopped, also Kamal's for accessories) starts a
+# fresh one. Docker itself never restarts a merely "unhealthy" container. Renders still running on
+# that Chrome fail - the client's retry and sweeper handle that.
+#
+# Opt-in: entrypoint.sh starts it when WATCHDOG_ENABLED=true.
+# Usage: chromedriver-watchdog.sh <chromedriver pid> [marker file]
+# Before a restart it creates the marker file, so entrypoint.sh can exit non-zero and a restart
+# policy of on-failure restarts the container too.
+#
+#   WATCHDOG_INTERVAL         seconds between checks                 (default 15)
+#   WATCHDOG_FAILURES         failed checks in a row before restart  (default 3)
+#   WATCHDOG_STATUS_TIMEOUT   seconds /status may take               (default 5)
+#   WATCHDOG_MEMORY_PRESSURE  PSI full avg10 percent that fails a check, 0 = off (default 50)
+#   WATCHDOG_STOP_GRACE       seconds between TERM and KILL          (default 10)
+#   WATCHDOG_PRESSURE_FILE    the cgroup's PSI file (default /sys/fs/cgroup/memory.pressure)
+set -euo pipefail
+
+pid="${1:-}"
+marker="${2:-}"
+port="${CHROMEDRIVER_PORT:-3000}"
+interval="${WATCHDOG_INTERVAL:-15}"
+failures="${WATCHDOG_FAILURES:-3}"
+status_timeout="${WATCHDOG_STATUS_TIMEOUT:-5}"
+pressure_limit="${WATCHDOG_MEMORY_PRESSURE:-50}"
+stop_grace="${WATCHDOG_STOP_GRACE:-10}"
+pressure_file="${WATCHDOG_PRESSURE_FILE:-/sys/fs/cgroup/memory.pressure}"
+reason=""
+
+log() {
+  printf 'chromedriver-watchdog: %s\n' "$*" >&2
+}
+
+# Prints the value as a plain decimal - "050" is 50, never bash's octal 40 - or fails closed on a
+# malformed setting: the watchdog does not start (chromedriver keeps running).
+decimal() {
+  local name="$1" value="$2" min="$3"
+  case "$value" in
+    '' | *[!0-9]*) ;;
+    *)
+      if ((10#$value >= min)); then
+        printf '%d\n' "$((10#$value))"
+        return
+      fi
+      ;;
+  esac
+  log "error: ${name} must be an integer >= ${min}, got '${value}' - not watching"
+  exit 1
+}
+
+pid="$(decimal "chromedriver pid" "$pid" 1)"
+port="$(decimal CHROMEDRIVER_PORT "$port" 1)"
+interval="$(decimal WATCHDOG_INTERVAL "$interval" 1)"
+failures="$(decimal WATCHDOG_FAILURES "$failures" 1)"
+status_timeout="$(decimal WATCHDOG_STATUS_TIMEOUT "$status_timeout" 1)"
+pressure_limit="$(decimal WATCHDOG_MEMORY_PRESSURE "$pressure_limit" 0)"
+stop_grace="$(decimal WATCHDOG_STOP_GRACE "$stop_grace" 1)"
+
+# Whole percent of the last 10 s in which every task of this cgroup stalled on memory; 0 when the
+# kernel offers no PSI file (cgroup v1, PSI disabled). Truncated, not rounded: 49.9 is 49, so a
+# limit of 50 means at least 50.0.
+memory_pressure() {
+  if [[ ! -r "$pressure_file" ]]; then
+    printf '0\n'
+    return
+  fi
+  awk '$1 == "full" { split($2, kv, "="); printf "%d\n", kv[2]; found = 1 } END { if (!found) print 0 }' "$pressure_file"
+}
+
+check() {
+  local pressure
+  if ! curl -fs -m "$status_timeout" -o /dev/null "http://127.0.0.1:${port}/status"; then
+    reason="chromedriver did not answer /status within ${status_timeout}s"
+    return 1
+  fi
+  if ((pressure_limit > 0)); then
+    pressure="$(memory_pressure)"
+    if ((pressure >= pressure_limit)); then
+      reason="memory pressure ${pressure}% (full avg10), limit ${pressure_limit}%"
+      return 1
+    fi
+  fi
+}
+
+restart() {
+  log "restarting: stopping chromedriver (pid ${pid}) so the container exits and its restart policy starts a fresh one"
+  if [[ -n "$marker" ]] && ! : >"$marker"; then
+    log "could not write ${marker} - the container may exit 0"
+  fi
+  kill -TERM "$pid" 2>/dev/null || true
+  for ((waited = 0; waited < stop_grace; waited++)); do
+    kill -0 "$pid" 2>/dev/null || exit 0
+    sleep 1
+  done
+  kill -KILL "$pid" 2>/dev/null || true
+  exit 0
+}
+
+log "watching chromedriver (pid ${pid}) every ${interval}s, restart after ${failures} failed checks"
+failed=0
+while kill -0 "$pid" 2>/dev/null; do
+  sleep "$interval"
+  if check; then
+    failed=0
+    continue
+  fi
+  failed=$((failed + 1))
+  log "check ${failed}/${failures} failed: ${reason}"
+  if ((failed >= failures)); then
+    restart
+  fi
+done

data/docker/entrypoint.sh

@@ -17,7 +17,7 @@ if [ "$ENABLE_XVFB" = "true" ]; then
 
   xauth generate :99 . trusted
 
-  umask $old_umask
+  umask "$old_umask"
 
 
 
@@ -38,17 +38,45 @@ if [ "$ENABLE_VNC" = "true" ]; then
   old_umask=$(umask)
   umask 077
   mkdir -p /home/appuser/.vnc
-  x11vnc -storepasswd $VNC_PASS /home/appuser/.vnc/passwd
-  umask $old_umask
+  x11vnc -storepasswd "$VNC_PASS" /home/appuser/.vnc/passwd
+  umask "$old_umask"
   x11vnc -display WAIT:99 -xkb -noxrecord -noxfixes -noxdamage -forever -shared -noshm -usepw -rfbauth /home/appuser/.vnc/passwd &
 fi
 
 # DISPLAY=:99 /home/appuser/.webdrivers/chromedriver --port=33259 --whitelisted-ips=""  --allowed-origins="*" --disable-dev-shm-usage --disable-gpu  --verbose
-/home/appuser/.webdrivers/chromedriver --port=${CHROMEDRIVER_PORT} \
+/home/appuser/.webdrivers/chromedriver --port="${CHROMEDRIVER_PORT}" \
                                        --allowed-ips="" \
                                        --allowed-origins="*" \
                                        --disable-dev-shm-usage \
                                        --disable-gpu \
-                                       --user-data-dir=${USER_DATA_DIR} \
-                                       --log-level=${CHROMEDRIVER_LOG_LEVEL:-INFO} \
-                                       --readable-timestamp
+                                       --user-data-dir="${USER_DATA_DIR}" \
+                                       --log-level="${CHROMEDRIVER_LOG_LEVEL:-INFO}" \
+                                       --readable-timestamp &
+chromedriver_pid=$!
+
+# docker stop sends TERM to this script (PID 1): pass it on so chromedriver ends its sessions.
+trap 'kill -TERM "$chromedriver_pid" 2>/dev/null' TERM INT
+
+# Opt-in watchdog (see chromedriver-watchdog.sh): stops chromedriver when it no longer answers or
+# memory thrashes, so this script exits and the restart policy starts a fresh container. It leaves
+# a marker first, in a private temp dir, so the exit below is non-zero for any restart policy.
+watchdog_marker=""
+if [ "${WATCHDOG_ENABLED:-false}" = "true" ]; then
+  if watchdog_dir="$(mktemp -d)"; then
+    watchdog_marker="${watchdog_dir}/restarted"
+  fi
+  /usr/local/bin/chromedriver-watchdog.sh "$chromedriver_pid" "$watchdog_marker" &
+fi
+
+# A trapped signal interrupts wait before chromedriver has ended: wait again until it has.
+status=0
+wait "$chromedriver_pid" || status=$?
+while kill -0 "$chromedriver_pid" 2>/dev/null; do
+  status=0
+  wait "$chromedriver_pid" || status=$?
+done
+
+if [ -n "$watchdog_marker" ] && [ -e "$watchdog_marker" ] && [ "$status" -eq 0 ]; then
+  status=1
+fi
+exit "$status"

data/docker/install-hyphen-data.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# Installs Chromium's hyphenation dictionaries so that `hyphens: auto` works in the PDFs.
+#
+# Why this exists: Chromium on Linux does not ship its hyphenation dictionaries in the binary. They
+# come as a "Hyphenation" component which the component updater downloads at runtime into
+# <user-data-dir>/hyphen-data/<version>/. In our containers that never sticks: chromedriver makes a
+# fresh, throw-away user-data-dir for every session (a download would be gone with it), a sandboxed
+# remote-chrome has no internet access to download from, and Debian's chromium package (chromium,
+# chromium-common) ships no hyphen-data at all. So `hyphens: auto` silently renders as
+# `hyphens: manual` - no automatic word breaks, however `lang` is set.
+#
+# How it works: before looking in the user-data-dir, Chromium's component installer looks for a
+# "preinstalled" copy of every component next to its own binary (ComponentInstaller::StartRegistration ->
+# FindPreinstallation, rooted at chrome::DIR_COMPONENTS = base::DIR_ASSETS = the directory of the chromium
+# executable, /usr/lib/chromium on Debian). It expects <root>/hyphen-data/manifest.json with a valid
+# "version" plus the hyph-<locale>.hyb files. That is exactly how Chrome for Testing bundles them
+# (chrome/BUILD.gn -> third_party/hyphenation-patterns:bundle_hyphen_data), with the same bogus version
+# "1.0.0.0" that is used below. The dictionaries themselves are the AOSP minikin .hyb files that live in
+# chromium/src at third_party/hyphenation-patterns/hyb and are fetched from there, pinned to a Chromium tag
+# (unchanged since 2023 - the de/en files of 151 and 154 are byte-identical). The pin intentionally does
+# not follow the Debian Chromium the image installs: the patterns are data in a format unchanged since
+# 2016, updated when the pattern data changes; the hyphenation integration spec, run against the
+# image's own Chromium, catches a Chromium that stops reading them.
+#
+# The component is only registered by the full browser (chrome_browser_main.cc), never by the old
+# headless shell - fine for Debian's chromium >= 132, where --headless is the new headless mode - and
+# not when --disable-component-update is passed, which neither chromedriver nor bidi2pdf does. Never add it.
+#
+# Usage: install-hyphen-data.sh [chromium-ref] [target-dir]
+set -euo pipefail
+
+ref="${1:-${HYPHEN_DATA_REF:-refs/tags/154.0.8037.92}}"
+target="${2:-/usr/lib/chromium/hyphen-data}"
+source_dir="third_party/hyphenation-patterns"
+archive_url="https://chromium.googlesource.com/chromium/src/+archive/${ref}/${source_dir}.tar.gz"
+
+# The image's language contract: exactly these dictionaries are installed, and each must be in the
+# download or the build fails - a renamed or dropped dictionary shows up at build time, not as a silent
+# fallback to no hyphenation, and the image does not grow when Chromium adds languages. The archive
+# carries ~50; add a language here (and to README "Hyphenation") to support it. Inside Blink "de" maps
+# to de-1996, "en" tries en-gb, then en-us
+# (third_party/blink/renderer/platform/text/hyphenation/hyphenation_minikin.cc, MapLocale).
+dictionaries="hyph-de-1996.hyb hyph-de-1901.hyb hyph-de-ch-1901.hyb hyph-en-us.hyb hyph-en-gb.hyb hyph-fr.hyb hyph-es.hyb hyph-it.hyb hyph-nl.hyb hyph-pt.hyb"
+
+workdir="$(mktemp -d)"
+trap 'rm -rf "$workdir"' EXIT
+mkdir -p "${workdir}/src/hyb"
+
+# Gitiles exports a subtree as one tarball. If that is unreachable, fall back to the GitHub mirror of
+# chromium/src (tags are mirrored), one file at a time, with the file list taken from the same BUILD.gn
+# that Chrome for Testing bundles from.
+fetch_from_gitiles() {
+  echo "Fetching Chromium hyphenation dictionaries from ${archive_url}"
+  curl -fsSL --retry 3 --retry-delay 2 -o "${workdir}/hyb.tar.gz" "${archive_url}" &&
+    tar -xzf "${workdir}/hyb.tar.gz" -C "${workdir}/src"
+}
+
+fetch_from_github() {
+  local raw="https://raw.githubusercontent.com/chromium/chromium/${ref#refs/tags/}/${source_dir}"
+  echo "Fetching Chromium hyphenation dictionaries from ${raw}"
+  curl -fsSL --retry 3 --retry-delay 2 -o "${workdir}/BUILD.gn" "${raw}/BUILD.gn"
+  curl -fsSL --retry 3 --retry-delay 2 -o "${workdir}/src/LICENSE" "${raw}/LICENSE"
+  grep -o '"hyb/hyph-[^"]*\.hyb"' "${workdir}/BUILD.gn" | tr -d '"' | sort -u | while read -r file; do
+    curl -fsSL --retry 3 --retry-delay 2 -o "${workdir}/src/${file}" "${raw}/${file}"
+  done
+}
+
+fetch_from_gitiles || { echo "gitiles download failed, trying the GitHub mirror" >&2; fetch_from_github; }
+
+mkdir -p "${target}"
+for file in ${dictionaries}; do
+  if [ ! -s "${workdir}/src/hyb/${file}" ]; then
+    echo "hyphenation dictionary ${file} missing from ${archive_url}" >&2
+    exit 1
+  fi
+  install -m 0644 "${workdir}/src/hyb/${file}" "${target}/${file}"
+done
+# The patterns are TeX hyphenation patterns under a mix of licenses; keep their notice with the data
+# (Chromium's file covers every language, these included).
+install -m 0644 "${workdir}/src/LICENSE" "${target}/LICENSE"
+
+# Chromium's component installer only accepts the directory with a manifest carrying a valid version.
+# 1.0.0.0 is what Chrome for Testing uses for its bundled copy: lower than anything the component
+# updater would ever serve, and not all zeros (that means "no component").
+cat > "${target}/manifest.json" <<'EOF'
+{
+  "manifest_version": 2,
+  "name": "hyphens-data",
+  "version": "1.0.0.0"
+}
+EOF
+chmod 0644 "${target}/manifest.json"
+chmod 0755 "${target}"
+
+dictionaries=("${target}"/*.hyb)
+echo "Installed ${#dictionaries[@]} hyphenation dictionaries to ${target}"

data/lib/bidi2pdf/chrome_sweeper/settings.rb

@@ -9,6 +9,7 @@ module Bidi2pdf
     DEFAULT_PIDS_BUDGET = 0.8
     DEFAULT_THREADS_PER_SESSION = 110
     DEFAULT_LEASE_TTL = SessionRegistry::DEFAULT_LEASE_TTL
+    DEFAULT_STOP_TIMEOUT = 10
 
     # What a ChromeSweeper closes and when - validated on construction; an unknown setting raises
     # ArgumentError.

data/lib/bidi2pdf/chrome_sweeper.rb

@@ -167,21 +167,32 @@ module Bidi2pdf
       end
     end
 
-    # Starts the periodic sweep thread (needs an +interval+). Idempotent.
+    # Starts the periodic sweep thread (needs an +interval+). Idempotent. Each thread has its own
+    # wakeup queue, so one that #stop stopped waiting for can never take a later thread's :stop.
+    # After such a #stop, a new thread can sweep while the abandoned sweep is still running: the
+    # lock file lets only one of them sweep at a time, the other's sweep is skipped.
     def start
       raise Bidi2pdf::InvalidConfigError, "chrome_sweeper: start needs an interval" unless interval
+      return self if @thread
 
-      @thread ||= Thread.new { sweep!(reason: :periodic) until @wakeup.pop(timeout: interval) == :stop }
+      wakeup = @wakeup = Thread::Queue.new
+      @thread = Thread.new { sweep!(reason: :periodic) until wakeup.pop(timeout: interval) == :stop }
       self
     end
 
-    # Stops the periodic sweep thread and waits for a sweep in progress to finish.
-    def stop
-      return unless @thread
+    # Stops the periodic sweep thread and waits up to +timeout+ seconds (nil: for ever) for a sweep
+    # in progress to finish - one inspecting sessions of a Chrome that no longer answers can take
+    # far longer. A sweep still running then is left to finish on its own; the thread ends after it.
+    #
+    # @return [Boolean] true when the thread has ended.
+    def stop(timeout: DEFAULT_STOP_TIMEOUT)
+      return true unless @thread
 
       @wakeup << :stop
-      @thread.join
+      stopped = !@thread.join(timeout).nil?
+      Bidi2pdf.logger.warn "chrome_sweeper: a sweep of #{@session_url} still running after #{timeout}s - not waiting for it" unless stopped
       @thread = nil
+      stopped
     end
 
     private

data/lib/bidi2pdf/session_warmer.rb

@@ -72,7 +72,15 @@ module Bidi2pdf
       #   pressure and try once more. Default true; false leaves a refused session to the caller.
       attr_accessor :retry_refused_sessions
 
+      # @return [Numeric, nil] Seconds #shutdown waits, all in all, for its background threads and
+      #   for closing the warm spares. A Chrome that hangs or ran out of memory answers no command,
+      #   and every close would wait out its own timeout - an exiting process must not hang on that.
+      #   What is still running then is left behind (a warning, +session_warmer.shutdown_timeout+);
+      #   its sessions stay in the registry and a later sweep closes them. +nil+ waits for ever.
+      attr_accessor :shutdown_timeout
+
       DEFAULT_MAX_IDLE_AGE = 300
+      DEFAULT_SHUTDOWN_TIMEOUT = 10
 
       def initialize
         @size = 1
@@ -85,6 +93,7 @@ module Bidi2pdf
         @registry_dir = nil
         @sweeper = nil
         @retry_refused_sessions = true
+        @shutdown_timeout = DEFAULT_SHUTDOWN_TIMEOUT
       end
 
       # The orphan age in seconds, or nil when the sweep is off (also when +:auto+ has no
@@ -93,12 +102,20 @@ module Bidi2pdf
         orphan_age == :auto ? max_idle_age && (max_idle_age * 2) : orphan_age
       end
 
+      # nil (no limit) or a positive number of seconds - for shutdown_timeout and #shutdown's argument.
+      def self.validate_timeout!(name, value)
+        return if value.nil? || (value.is_a?(Numeric) && value.positive?)
+
+        raise ArgumentError, "#{name} must be nil or a positive number of seconds, got #{value.inspect}"
+      end
+
       # @raise [ArgumentError] if a setting can't be honored - checked once, at construction.
       def validate!
         validate_size!
         validate_max_idle_age!
         validate_orphan_age!
         validate_sweeper!
+        validate_shutdown_timeout!
       end
 
       private
@@ -121,6 +138,10 @@ module Bidi2pdf
         raise ArgumentError, "orphan_age must be :auto, nil or a positive number of seconds, got #{orphan_age.inspect}"
       end
 
+      def validate_shutdown_timeout!
+        Configuration.validate_timeout!("shutdown_timeout", shutdown_timeout)
+      end
+
       def validate_sweeper!
         return if sweeper.nil? || sweeper.is_a?(Hash)
 
@@ -273,20 +294,78 @@ module Bidi2pdf
     # finish (each of those, seeing @shutdown, retires its own result instead of stashing it - see
     # #stash_or_retire). A subsequent #with_tab still works - it just falls back to a synchronous
     # slot, since checkout never depends on a warm one being there.
-    def shutdown
-      spares, threads = @mutex.synchronize do
+    #
+    # All of that within +timeout+ seconds together (Configuration#shutdown_timeout; nil waits for
+    # ever). The spares start closing first, side by side, so a hung sweep cannot use up their share
+    # of the deadline. Whatever is still running at the deadline is left to finish on its own, or to
+    # die with the process; a spare still closing loses its lease (it keeps its registry entry), so
+    # a sweeper can take its session even while this process lives on.
+    #
+    # @return [Hash{String => Integer}] what was still running at the deadline ("spare" => 1, ...) -
+    #   empty when everything finished in time.
+    # @raise [ArgumentError] for a +timeout+ that is neither nil nor a positive number.
+    def shutdown(timeout: @config.shutdown_timeout)
+      Configuration.validate_timeout!("timeout", timeout)
+      spares, threads = stop_accepting
+      deadline = timeout && (now + timeout)
+      closers = retire_all(spares)
+      pending = (stop_background(threads, deadline) + abandoned_spares(closers, deadline)).tally
+      warn_abandoned(pending, timeout) unless pending.empty?
+      pending
+    end
+
+    private
+
+    def stop_accepting
+      @mutex.synchronize do
         @shutdown = true
         [@available.dup.tap { @available.clear }, @replenish_threads.dup.tap { @replenish_threads.clear }]
       end
+    end
 
+    # The labels of whatever is still running at the deadline: reaper, sweeper, replenishments.
+    def stop_background(threads, deadline)
       @reaper_wakeup << :stop
-      @reaper&.join
-      @sweeper&.stop
-      threads.each(&:join)
-      spares.each { |slot| retire(slot) }
+      pending = unfinished([@reaper].compact, deadline, "reaper")
+      pending << "sweeper" unless @sweeper.nil? || @sweeper.stop(timeout: remaining(deadline))
+      pending + unfinished(threads, deadline, "replenishment")
     end
 
-    private
+    def remaining(deadline)
+      deadline && [deadline - now, 0].max
+    end
+
+    # Thread#join returns nil when the time ran out first.
+    def unfinished(threads, deadline, label)
+      threads.reject { |thread| thread.join(remaining(deadline)) }.map { label }
+    end
+
+    # [slot, closing thread] pairs.
+    def retire_all(slots)
+      slots.map do |slot|
+        closer = Thread.new do
+          retire(slot)
+        rescue StandardError => e
+          Bidi2pdf.logger.warn "session_warmer: retiring a spare failed: #{e.message}"
+        end
+        [slot, closer]
+      end
+    end
+
+    # Spares still closing at the deadline, with their lease released: the heartbeat would otherwise
+    # keep renewing it, and no sweeper takes a leased session.
+    def abandoned_spares(closers, deadline)
+      closers.reject { |_, closer| closer.join(remaining(deadline)) }.map do |slot, _|
+        @registry&.release(session_id_of(slot))
+        "spare"
+      end
+    end
+
+    # Only called with something pending, which needs a deadline - so +timeout+ is a number here.
+    def warn_abandoned(pending, timeout)
+      Bidi2pdf.logger.warn "session_warmer: shutdown gave up after #{timeout}s, still running: #{pending.map { |what, count| "#{count} #{what}" }.join(", ")}"
+      Bidi2pdf.notification_service.instrument("session_warmer.shutdown_timeout.bidi2pdf", { timeout: timeout, pending: pending })
+    end
 
     # Fail-fast on purpose (a Chrome that can't start at boot should be loud), but not leaky: if slot
     # N fails, no instance is returned to own slots 1..N-1, so they are retired here first.

data/lib/bidi2pdf/test_helpers/testcontainers/chromedriver_container.rb

@@ -10,6 +10,14 @@ module Bidi2pdf
         # then sits silently in the pull for many minutes.
         DEFAULT_IMAGE = "dieters877565/chromedriver:latest"
 
+        # BIDI2PDF_BUILD_CHROMEDRIVER_IMAGE=true: build the image from the checkout (build_dir,
+        # docker_file) and run that, so a change to the image is tested before it is published -
+        # bidi2pdf's own CI sets it. Unset, the published image is pulled. Testcontainers' #start
+        # always pulls, so a locally built tag cannot go through it; #start_local_image builds instead.
+        def self.build_locally?(env = ENV)
+          env["BIDI2PDF_BUILD_CHROMEDRIVER_IMAGE"] == "true"
+        end
+
         attr_reader :docker_file, :build_dir
 
         def initialize(image = DEFAULT_IMAGE, **options)

data/lib/bidi2pdf/test_helpers/testcontainers/chromedriver_test_helper.rb

@@ -132,7 +132,7 @@ def start_chromedriver_container(build_dir:, mounts:, shared_network:, chromedri
 
   container.with_filesystem_binds(mounts) if mounts&.any?
 
-  container.start
+  ChromedriverTestcontainer.build_locally? ? container.start_local_image : container.start
 
   container
 end

data/lib/bidi2pdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
-  VERSION = "0.1.20"
+  VERSION = "0.1.21"
 end

data/sig/bidi2pdf/chrome_sweeper/settings.rbs

@@ -14,6 +14,8 @@ module Bidi2pdf
 
     DEFAULT_LEASE_TTL: untyped
 
+    DEFAULT_STOP_TIMEOUT: 10
+
     # What a ChromeSweeper closes and when - validated on construction; an unknown setting raises
     # ArgumentError.
     #

data/sig/bidi2pdf/chrome_sweeper.rbs

@@ -133,11 +133,18 @@ module Bidi2pdf
     # @return [Result]
     def sweep!: (?reason: ::Symbol, ?check_interval: untyped?, ?pressure: bool) -> untyped
 
-    # Starts the periodic sweep thread (needs an +interval+). Idempotent.
+    # Starts the periodic sweep thread (needs an +interval+). Idempotent. Each thread has its own
+    # wakeup queue, so one that #stop stopped waiting for can never take a later thread's :stop.
+    # After such a #stop, a new thread can sweep while the abandoned sweep is still running: the
+    # lock file lets only one of them sweep at a time, the other's sweep is skipped.
     def start: () -> self
 
-    # Stops the periodic sweep thread and waits for a sweep in progress to finish.
-    def stop: () -> (nil | untyped)
+    # Stops the periodic sweep thread and waits up to +timeout+ seconds (nil: for ever) for a sweep
+    # in progress to finish - one inspecting sessions of a Chrome that no longer answers can take
+    # far longer. A sweep still running then is left to finish on its own; the thread ends after it.
+    #
+    # @return [Boolean] true when the thread has ended.
+    def stop: (?timeout: untyped) -> (true | untyped)
 
     private
 

data/sig/bidi2pdf/session_warmer.rbs

@@ -72,6 +72,8 @@ module Bidi2pdf
 
       @retry_refused_sessions: untyped
 
+      @shutdown_timeout: untyped
+
       # @return [Integer] Number of Chrome slots to keep pre-warmed.
       attr_accessor size: untyped
 
@@ -120,14 +122,26 @@ module Bidi2pdf
       #   pressure and try once more. Default true; false leaves a refused session to the caller.
       attr_accessor retry_refused_sessions: untyped
 
+      # @return [Numeric, nil] Seconds #shutdown waits, all in all, for its background threads and
+      #   for closing the warm spares. A Chrome that hangs or ran out of memory answers no command,
+      #   and every close would wait out its own timeout - an exiting process must not hang on that.
+      #   What is still running then is left behind (a warning, +session_warmer.shutdown_timeout+);
+      #   its sessions stay in the registry and a later sweep closes them. +nil+ waits for ever.
+      attr_accessor shutdown_timeout: untyped
+
       DEFAULT_MAX_IDLE_AGE: 300
 
+      DEFAULT_SHUTDOWN_TIMEOUT: 10
+
       def initialize: () -> void
 
       # The orphan age in seconds, or nil when the sweep is off (also when +:auto+ has no
       # max_idle_age to derive it from).
       def effective_orphan_age: () -> untyped
 
+      # nil (no limit) or a positive number of seconds - for shutdown_timeout and #shutdown's argument.
+      def self.validate_timeout!: (untyped name, untyped value) -> (nil | untyped)
+
       # @raise [ArgumentError] if a setting can't be honored - checked once, at construction.
       def validate!: () -> untyped
 
@@ -139,6 +153,8 @@ module Bidi2pdf
 
       def validate_orphan_age!: () -> (nil | untyped)
 
+      def validate_shutdown_timeout!: () -> untyped
+
       def validate_sweeper!: () -> (nil | untyped)
     end
 
@@ -204,10 +220,40 @@ module Bidi2pdf
     # finish (each of those, seeing @shutdown, retires its own result instead of stashing it - see
     # #stash_or_retire). A subsequent #with_tab still works - it just falls back to a synchronous
     # slot, since checkout never depends on a warm one being there.
-    def shutdown: () -> untyped
+    #
+    # All of that within +timeout+ seconds together (Configuration#shutdown_timeout; nil waits for
+    # ever). The spares start closing first, side by side, so a hung sweep cannot use up their share
+    # of the deadline. Whatever is still running at the deadline is left to finish on its own, or to
+    # die with the process; a spare still closing loses its lease (it keeps its registry entry), so
+    # a sweeper can take its session even while this process lives on.
+    #
+    # @return [Hash{String => Integer}] what was still running at the deadline ("spare" => 1, ...) -
+    #   empty when everything finished in time.
+    # @raise [ArgumentError] for a +timeout+ that is neither nil nor a positive number.
+    def shutdown: (?timeout: untyped) -> untyped
 
     private
 
+    def stop_accepting: () -> untyped
+
+    # The labels of whatever is still running at the deadline: reaper, sweeper, replenishments.
+    def stop_background: (untyped threads, untyped deadline) -> untyped
+
+    def remaining: (untyped deadline) -> untyped
+
+    # Thread#join returns nil when the time ran out first.
+    def unfinished: (untyped threads, untyped deadline, untyped label) -> untyped
+
+    # [slot, closing thread] pairs.
+    def retire_all: (untyped slots) -> untyped
+
+    # Spares still closing at the deadline, with their lease released: the heartbeat would otherwise
+    # keep renewing it, and no sweeper takes a leased session.
+    def abandoned_spares: (untyped closers, untyped deadline) -> untyped
+
+    # Only called with something pending, which needs a deadline - so +timeout+ is a number here.
+    def warn_abandoned: (untyped pending, untyped timeout) -> untyped
+
     # Fail-fast on purpose (a Chrome that can't start at boot should be loud), but not leaky: if slot
     # N fails, no instance is returned to own slots 1..N-1, so they are retired here first.
     def prewarm: () -> untyped

data/sig/bidi2pdf/test_helpers/testcontainers/chromedriver_container.rbs

@@ -23,6 +23,12 @@ module Bidi2pdf
         # then sits silently in the pull for many minutes.
         DEFAULT_IMAGE: "dieters877565/chromedriver:latest"
 
+        # BIDI2PDF_BUILD_CHROMEDRIVER_IMAGE=true: build the image from the checkout (build_dir,
+        # docker_file) and run that, so a change to the image is tested before it is published -
+        # bidi2pdf's own CI sets it. Unset, the published image is pulled. Testcontainers' #start
+        # always pulls, so a locally built tag cannot go through it; #start_local_image builds instead.
+        def self.build_locally?: (?untyped env) -> untyped
+
         attr_reader docker_file: untyped
 
         attr_reader build_dir: untyped

data/sig/bidi2pdf/version.rbs

@@ -1,3 +1,3 @@
 module Bidi2pdf
-  VERSION: "0.1.20"
+  VERSION: "0.1.21"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bidi2pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.20
+  version: 0.1.21
 platform: ruby
 authors:
 - Dieter S.
@@ -408,8 +408,10 @@ files:
 - docker/Dockerfile.chromedriver
 - docker/Dockerfile.slim
 - docker/chrome-driver/chrome.json
+- docker/chromedriver-watchdog.sh
 - docker/docker-compose.yml
 - docker/entrypoint.sh
+- docker/install-hyphen-data.sh
 - docker/nginx/default.conf
 - docker/nginx/htpasswd
 - exe/bidi2pdf