716ae14b0f
* docs: brainstorm resilience/adoption features and plan follow-up work
Brainstorm and deep-dive on where Immich Folio breaks under Immich
outages and what blocks self-hosted adoption, plus an implementation
plan for the remaining gaps after v0.9.2 (route-handler tests,
stale-while-error caching, loading skeletons).
* test: enable route-handler tests and cover admin guards and image content-type
vitest.config.ts only ran lib/__tests__/**, so route handlers were
structurally untestable. Two mechanisms live only at the route level and
cannot be extracted the way lib/imageSize.ts was: the admin auth guards
and the image proxy's Content-Type sanitisation (the stored-XSS fix from
c2fa8e7). Both were correct but unverified by any test.
Adds a table-driven test over all ten guarded /api/admin/* handlers,
including a filesystem walk that fails if a future route is added
without a row in the table. Adds a route-level test for
/api/image/[id] covering token validation, the six Content-Type
rewrite cases, ETag/304, and the 404 vs 503 (ImmichUnavailableError)
distinction.
Verified both catch real regressions by temporarily removing the admin
guards and the Content-Type rewrite and confirming the expected tests
fail, then restoring and confirming green again.
134 new tests (244 total, up from 210), tsc 0 errors, build succeeds.
* feat: serve stale cache entries while Immich is unavailable
v0.9.2 (#394) correctly split "gone" (404/410) from "unavailable"
(ImmichUnavailableError), and pages now render a 5xx instead of a false
404 during an outage — but that 5xx still replaced a gallery that had
loaded fine seconds earlier. lib/cache.ts deleted expired entries on
access, so nothing survived long enough to fall back to.
Cache entries now carry two deadlines: staleAt (the existing CACHE_TTL,
after which get() still reports a miss) and hardExpiresAt (the new
STALE_MAX_AGE, default 24h, after which the entry is dropped entirely).
Between the two, getStale() can still return the data.
getAlbums(), getAlbum() and getAssetInfo() catch ImmichUnavailableError
and fall back to getStale() before propagating. The two MISSING-sentinel
writes (definitive 404s) are deliberately left on the short cacheTtl
window — a corrected asset ID should take effect after the normal TTL,
not sit in the 24h stale window meant for outages.
STALE_MAX_AGE=0 disables the fallback. Verified the fallback only
engages on a real outage, not on a cache hit at the TTL boundary, and
that a definitive 404 still reports missing rather than falling back.
256 tests (up from 244), tsc 0 errors, build succeeds.
* feat: add loading skeletons for dynamic gallery routes
Every gallery route is force-dynamic and waits on a live Immich
round-trip — up to IMMICH_TIMEOUT_MS when the server is struggling —
with nothing rendered until it resolves. loading.tsx renders instantly
while the page component awaits its data.
Not browser-verified against live data: this worktree has no
.env.local and only .example content files, so the app boots into
setup mode (confirmed the dev server starts cleanly and the setup
screen renders, HTTP 200). tsc 0 errors, build succeeds, no new lint
errors.
* docs: document stale cache window, image token revocation, route-test convention
- README: STALE_MAX_AGE env var and a "Behaviour when Immich is
unreachable" section (stale-serves-until-STALE_MAX_AGE, 503 not 404,
outages never cached).
- docs/gallery-config.md: new "Image Token Revocation" subsection under
System & Security — un-publishing an album does not revoke already
issued image URLs; rotating AUTH_SECRET does.
- CLAUDE.md: updated cache description to cover the stale window and
MISSING sentinel, and a new code-convention note that route-level
logic (guards, header sanitisation) should get a route-level test
rather than being extracted into lib/ just to reach the test runner.
---------
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
70 lines
3.5 KiB
Plaintext
70 lines
3.5 KiB
Plaintext
# ── Immich Server Connection (required) ──────────────────────────
|
|
# Validated by Zod at startup — missing or invalid values produce clear errors.
|
|
|
|
# Base URL of your Immich instance (must be a valid URL)
|
|
IMMICH_API_URL=http://your-immich-server:2283
|
|
|
|
# Immich API key (from Admin → API Keys)
|
|
IMMICH_API_KEY=your-api-key-here
|
|
|
|
# ── Optional Settings ────────────────────────────────────────────
|
|
# All have sensible defaults and are type-checked by Zod.
|
|
|
|
# Site title shown in the header (string, default: "Gallery")
|
|
SITE_TITLE=My Photography
|
|
|
|
# Subtitle displayed below the title (string, default: "")
|
|
SITE_SUBTITLE=A visual journal
|
|
|
|
# Cache TTL in seconds (integer >= 0, default: 300 = 5 minutes)
|
|
CACHE_TTL=300
|
|
|
|
# How long (in seconds) an expired cache entry may still be served while the
|
|
# Immich server is unreachable. Keeps the public gallery online across an
|
|
# Immich restart instead of showing an error page. Set to 0 to disable.
|
|
# Default: 86400 (24 hours)
|
|
STALE_MAX_AGE=86400
|
|
|
|
# Cache-buster for image and video URLs (any string, default: empty = off).
|
|
# Images are served with a one-year immutable cache, so browsers never
|
|
# revalidate them. If you regenerate thumbnails in Immich, or rotate/edit a
|
|
# photo, the asset ID stays the same and visitors keep seeing the old version.
|
|
# Bump this value (e.g. 1 → 2) to change every image URL at once and force a
|
|
# refetch. Leave it unset in normal operation.
|
|
# IMAGE_CACHE_VERSION=1
|
|
|
|
# How long to wait for a response from Immich, in milliseconds
|
|
# (integer, minimum 1000, default: 15000 = 15 seconds).
|
|
# Bounds the wait for a *response* only — downloading a large photo or a long
|
|
# video is not capped by this. Raise it if metadata search on very large albums
|
|
# times out; lower it to fail faster when Immich is unreachable.
|
|
# IMMICH_TIMEOUT_MS=15000
|
|
|
|
# Rate limit for image proxy (integer >= 1, requests per minute per IP, default: 120)
|
|
# RATE_LIMIT_RPM=120
|
|
|
|
# Number of reverse proxies in front of the app (nginx/Traefik/Caddy = 1,
|
|
# Cloudflare in front of nginx = 2). Required for correct rate limiting behind
|
|
# a proxy — without it the client IP is read from a spoofable header.
|
|
# The app must be reachable ONLY through the proxy (bind to 127.0.0.1).
|
|
# TRUSTED_PROXY_HOPS=1
|
|
|
|
# Secret for signing auth cookies and encrypting asset tokens (string, min 16 chars).
|
|
# If not provided, IMMICH_API_KEY will be used as a fallback (not recommended).
|
|
# AUTH_SECRET=your-super-long-random-secret-here
|
|
|
|
# Webhook secret for cache invalidation (optional, string).
|
|
# Set this to a long random string and configure Immich to send webhooks to
|
|
# POST /api/webhook with an x-immich-signature header (HMAC-SHA256 of the body).
|
|
# If not set, the webhook endpoint returns 501 and is effectively disabled.
|
|
# WEBHOOK_SECRET=your-long-random-webhook-secret
|
|
|
|
# ── Admin Panel ──────────────────────────────────────────────────
|
|
# Set a password to enable the visual admin panel at /admin.
|
|
# Leave unset or empty to disable the admin UI entirely.
|
|
# ADMIN_PASSWORD=your-secure-admin-password
|
|
|
|
# ── Album configuration ──────────────────────────────────────────
|
|
# Albums, subpages, hero image, and passwords are defined in content/gallery.yaml
|
|
# See content/gallery.yaml.example for the full reference.
|