Cache a screen-sized copy of TIFF/HEIC images served by /images/

[lstein]

Fixes #414.

Summary

/images/ used to re-encode every TIFF/HEIC as a full-resolution PNG on every request, with no validators. It now serves a JPEG capped at 4096 px on the long edge, or a WebP when the image has real transparency. The copy is cached in the album's thumbnail directory and served with a content ETag (304 on revalidation). Downloads are unchanged because they use ?original=1.

Measured on a 6000×4000 LZW TIFF (97 MB):

	time	bytes
before (every request)	2.55 s	53.5 MB PNG
after, cold	0.67 s	3.9 MB JPEG
after, warm	~1 ms	3.9 MB JPEG

How it works

• Naming: <tile digest>_display_<album tag>_<source stamp>.<jpg|webp>.
  • The tile digest is the same one keep_hashes_for produces. That lets the post-index sweep and the per-image delete (discard) reclaim display copies with no second keep-set.
  • The album tag stops two albums whose index files share a directory from serving each other's same-named files.
  • The source stamp is a digest of the source's mtime_ns and size, taken before decoding. A file replaced with an older mtime (cp -p, a backup restore) is therefore reconverted. The stat is repeated after encoding, and if the source changed in between, the result is served but not cached.
• Relative path: taken from the resolved file, the way the index stores it. Before this, an album root reached through a symlink or a mapped Windows drive fell back to the bare filename, so same-named images collided.
• Concurrency: a per-stem lock plus write-then-rename. Concurrent requests (swiper preloads) convert once and never read a partial file. After each write, older copies of the same file are removed. A copy written after its source was deleted mid-conversion is removed as well.
• Mode handling: _png_safe's 16-bit, 32-bit, float and CMYK/ICC handling still applies. 16-bit is then reduced to 8-bit for JPEG. An alpha channel that is fully opaque is dropped, and an ICC profile is dropped whenever the mode changes.
• Failure handling: if the cache can't be written (e.g. a read-only index directory), the image is still served and the failure is logged once.
• Sweep safety: prune/discard now delete only the exact filename shapes the routes write. A hash-named user photo in a thumbnails/ folder next to a custom index path is left alone.

Review

Two rounds of adversarial fresh-context review. Every confirmed finding has a regression test that fails on the earlier code.

Known and deliberately out of scope, because each predates this change:

• When a custom index path lies inside an image root, cached files in thumbnails/ are indexed as photos. The default photomap_index/ is excluded from scanning.
• Deleting a directory album doesn't remove its thumbnails/ folder.
• On case-insensitive filesystems, a hand-typed URL with different capitalization creates extra copies that the per-image delete misses. They are reclaimed at the next index save. Tiles already behave this way.

Test plan

• pytest tests: 1308 passed
• ruff check photomap tests
• Manual: browse a folder of large TIFF/HEIC scans; check that revisits are instant and that the download button still saves the original

🤖 Generated with Claude Code