feat(export): server-rendered artifacts behind one signed download URL (#160)

The finished-game export (GCG + a new PNG of the final position) is one
signed, short-lived relative URL (game.export_url; HMAC-SHA256, 10-min
TTL, BACKEND_EXPORT_SIGN_KEY) resolved against the client's own origin
and delivered by the best affordance each platform has (five on-device
review rounds):

- TG Android/desktop: native showPopup chooser -> native downloadFile
  dialog (bridge-only chain, activation-safe).
- TG iOS: app-modal chooser -> OS share sheet with the fetched file
  (a popup callback cannot supply the activation the sheet needs).
- VK iOS: VKWebAppDownloadFile for both formats.
- VK Android: the PNG opens in VK's native image viewer, the GCG copies
  to the clipboard (the VK Android downloader hangs on any download,
  Content-Length/Range notwithstanding).
- VK desktop iframe / desktop browsers: plain anchor downloads.
- Mobile browsers: the OS share sheet (fetch-then-share).
- Legacy TG (< Bot API 8.0): app modal + GCG clipboard, no image option.

The PNG is rasterized on demand by the new internal `renderer` sidecar
(node:22-slim + skia-canvas + baked Liberation/Noto Color Emoji fonts)
executing the SAME ui/src/lib/gameimage.ts the ui project unit-tests;
the backend rebuilds the render payload from the journal +
engine.AlphabetTable, and the device date locale, IANA time zone and
localized non-play labels ride the signed URL. Nothing is stored — the
artifact re-derives from the immutable journal on each GET. The gateway
forwards /dl/* (caddy @gateway matcher extended) behind the per-IP
public rate limiter and serves bytes via http.ServeContent.

Deploy: renderer service in compose + prod overlay + rolling order +
prod push list; TEST_/PROD_EXPORT_SIGN_KEY secrets; the sidecar smoke
runs in the ui CI job. Docs: ARCHITECTURE, FUNCTIONAL(+_ru), UI_DESIGN,
TESTING, deploy/README, renderer/README.

deploy/.env.example

@@ -21,6 +21,11 @@ DICT_VERSION=v1.3.0
 # --- Logging ----------------------------------------------------------------
 LOG_LEVEL=info
 
+# --- Finished-game export ----------------------------------------------------
+# HMAC key signing the public export download URLs (/dl/*). Required; generate a
+# real contour value with `openssl rand -base64 32` (Gitea TEST_/PROD_EXPORT_SIGN_KEY).
+EXPORT_SIGN_KEY=dev-export-sign-key
+
 # --- Edge / caddy -----------------------------------------------------------
 # Test: ":80" (the host caddy terminates TLS and forwards to scrabble:80 on the
 # external `edge` network). Prod: a domain so caddy does its own ACME.

deploy/README.md

@@ -16,6 +16,7 @@ operational reference for **every environment variable**.
 | `landing` | built (`gateway/Dockerfile`, target `landing`) | Static landing page at `/` (caddy:2-alpine + the shared Vite build, `deploy/landing/Caddyfile`); absorbs stray public paths. |
 | `backend` | built (`backend/Dockerfile`) | Domain service; bakes in the DAWG dictionaries; runs migrations at boot. |
 | `postgres` | `postgres:17-alpine` | Database (named volume, `pg_isready` healthcheck). |
+| `renderer` | built (`renderer/Dockerfile`) | Finished-game image-render sidecar (Node + skia-canvas running the shared `ui/src/lib/gameimage.ts`); internal-only HTTP at `renderer:8090`, called by the backend for the PNG export artifact. |
 | `validator` | built (`platform/telegram/Dockerfile`, target `validator`) | Telegram HMAC validator (no VPN, no Bot API); internal gRPC at `validator:9091`. Game login depends only on this. |
 | `vpn` + `bot` | sidecar + built (`platform/telegram/Dockerfile`, target `bot`) | Telegram bot, gated to the **`telegram-local`** profile; egresses through the AmneziaWG sidecar and dials the gateway bot-link (mTLS) at `gateway:9443`. The test contour activates the profile; the prod **main** host omits it and runs the bot standalone on its **own host** (`docker-compose.bot.yml`, no VPN — native Bot API egress). |
 | `otelcol` | `otel/opentelemetry-collector-contrib` | OTLP/gRPC `:4317` → Prometheus scrape (`:9464`) + Tempo. |
@@ -62,6 +63,7 @@ compose binds from this directory.
 | `POSTGRES_PASSWORD` | secret | Postgres password (also embedded in `BACKEND_POSTGRES_DSN`). |
 | `GM_BASICAUTH_HASH` | secret | bcrypt hash gating `/_gm` (admin console + Grafana). Generate with `docker run --rm caddy:2-alpine caddy hash-password --plaintext '<pw>'`. |
 | `TELEGRAM_MINIAPP_URL` | variable | The Mini App URL the bot hands out in deep links / buttons. |
+| `EXPORT_SIGN_KEY` | secret | HMAC key signing the public finished-game export download URLs (`/dl/*`). Generate with `openssl rand -base64 32`. |
 
 **Plus the bot token** — `TELEGRAM_BOT_TOKEN` (secret), shared by the validator (HMAC
 secret) and the bot (Bot API). It defaults to empty in compose, but both **fail at
@@ -106,7 +108,8 @@ at each other on the `internal` network — listed here so they are not mistaken
 missing config: `BACKEND_POSTGRES_DSN` (→ `postgres`, `search_path=backend`),
 `GATEWAY_BACKEND_HTTP_URL`/`_GRPC_ADDR` (→ `backend`),
 `GATEWAY_VALIDATOR_ADDR` (→ `validator:9091`), `BACKEND_CONNECTOR_ADDR` (→ the gateway
-bot-link relay `gateway:9092`), the bot's `TELEGRAM_GATEWAY_ADDR` (→ `gateway:9443`,
+bot-link relay `gateway:9092`), `BACKEND_RENDERER_URL` (→ `renderer:8090`, the image-render
+sidecar), the bot's `TELEGRAM_GATEWAY_ADDR` (→ `gateway:9443`,
 mTLS) with the `GATEWAY_BOTLINK_*` / `TELEGRAM_BOTLINK_*` cert paths under `/certs` (the
 mTLS material is generated by `deploy/gen-certs.sh`, gitignored, regenerated each
 deploy), and all services' `*_OTEL_*_EXPORTER=otlp` →
@@ -194,7 +197,7 @@ players arrive.
 
 **`PROD_` Gitea set** (mirrors `TEST_`, mapped onto the unprefixed names above) — secrets:
 `PROD_{POSTGRES_PASSWORD, GM_BASICAUTH_HASH, GRAFANA_ADMIN_PASSWORD, TELEGRAM_BOT_TOKEN,
-TELEGRAM_PROMO_BOT_TOKEN, REGISTRY_PASSWORD, SSH_KEY, SSH_KNOWN_HOSTS, BOTLINK_CA,
+TELEGRAM_PROMO_BOT_TOKEN, EXPORT_SIGN_KEY, REGISTRY_PASSWORD, SSH_KEY, SSH_KNOWN_HOSTS, BOTLINK_CA,
 BOTLINK_GATEWAY_CERT, BOTLINK_GATEWAY_KEY, BOTLINK_BOT_CERT, BOTLINK_BOT_KEY}`; variables:
 `PROD_{REGISTRY_USER, MAIN_HOST, TG_HOST, CADDY_SITE_ADDRESS, GM_BASICAUTH_USER,
 GRAFANA_ROOT_URL, LOG_LEVEL, DICT_VERSION, TELEGRAM_MINIAPP_URL, TELEGRAM_GAME_CHANNEL_ID,

deploy/caddy/Caddyfile

@@ -53,7 +53,7 @@
 	# The game SPA and the Connect edge are served by the gateway. Strip any
 	# client-supplied X-Scrabble-Honeypot here so the gateway only ever honours the
 	# tag the honeypot block sets below (a client cannot self-tag a real request).
-	@gateway path /app /app/* /telegram /telegram/* /vk /vk/* /dict/* /metrics/* /scrabble.edge.v1.Gateway/*
+	@gateway path /app /app/* /telegram /telegram/* /vk /vk/* /dict/* /dl/* /metrics/* /scrabble.edge.v1.Gateway/*
 	handle @gateway {
 		reverse_proxy gateway:8081 {
 			header_up -X-Scrabble-Honeypot

deploy/docker-compose.prod.yml

@@ -50,6 +50,13 @@ services:
         limits:
           memory: 384M
 
+  renderer:
+    image: ${REGISTRY:?set REGISTRY}/scrabble-renderer:${TAG:?set TAG}
+    deploy:
+      resources:
+        limits:
+          memory: 160M
+
   validator:
     image: ${REGISTRY:?set REGISTRY}/scrabble-telegram-validator:${TAG:?set TAG}
     deploy:

deploy/docker-compose.yml

@@ -61,6 +61,36 @@ services:
           memory: 512M
     networks: [internal]
 
+  # The finished-game image-render sidecar: internal-only, called by the backend for the
+  # PNG export artifact. It runs the same ui/src/lib/gameimage.ts the web client
+  # unit-tests, on skia-canvas (renderer/README.md). node:22-slim carries a shell, so —
+  # uniquely among the built services — it has a real container healthcheck the backend's
+  # depends_on gates on.
+  renderer:
+    container_name: scrabble-renderer
+    image: scrabble-renderer:latest
+    build:
+      context: ..
+      dockerfile: renderer/Dockerfile
+      args:
+        VERSION: ${APP_VERSION:-dev}
+    restart: unless-stopped
+    logging: *default-logging
+    environment:
+      RENDERER_PORT: "8090"
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8090/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 10s
+      timeout: 3s
+      retries: 12
+    # A render peaks well under 100 MiB (a 2-MP canvas + skia); idle sits near 60 MiB.
+    deploy:
+      resources:
+        limits:
+          cpus: "1.0"
+          memory: 192M
+    networks: [internal]
+
   backend:
     container_name: scrabble-backend
     image: scrabble-backend:latest
@@ -80,9 +110,15 @@ services:
     depends_on:
       postgres:
         condition: service_healthy
+      renderer:
+        condition: service_healthy
     environment:
       # search_path=backend matches the migrations (00001 creates the schema).
       BACKEND_POSTGRES_DSN: postgres://${POSTGRES_USER:-scrabble}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-scrabble}?sslmode=disable&search_path=backend
+      # The finished-game export: the render sidecar address + the HMAC key signing the
+      # public download URLs (deploy env: TEST_/PROD_EXPORT_SIGN_KEY).
+      BACKEND_RENDERER_URL: http://renderer:8090
+      BACKEND_EXPORT_SIGN_KEY: ${EXPORT_SIGN_KEY:?set EXPORT_SIGN_KEY — the export download URL signing secret}
       # The pool caps at 25 conns (~28 backends) around 500 players; 40 gives headroom
       # for bursts. Postgres (2 cores / 512 MiB) handles it.
       BACKEND_POSTGRES_MAX_OPEN_CONNS: "40"

deploy/prod-deploy.sh

@@ -134,6 +134,7 @@ fi
 
 # Roll one service at a time, least -> most dependent; any failure rolls everything back.
 roll postgres  health_postgres                              || { rollback; exit 1; }
+roll renderer  health_running scrabble-renderer             || { rollback; exit 1; }
 roll backend   health_backend                               || { rollback; exit 1; }
 roll gateway   health_running scrabble-gateway              || { rollback; exit 1; }
 roll landing   health_landing                               || { rollback; exit 1; }