notify-bridge/RELEASE_NOTES.md

v0.3.0 (2026-04-22)

Major polling perf overhaul for large Immich libraries plus a UX fix for slow bot commands. Combined impact on idle albums: per-tick cost drops from ~150 MB fetched to a few hundred bytes; active albums now fetch O(changes) instead of O(library). Tested against a ~200k-asset library.

Schema change: adds a meta_fingerprint JSON column to notification_tracker_state — applied automatically by the startup migration, no manual step required.

Performance

• Skip full album fetch on idle ticks — new ImmichAlbumMeta + get_album_meta() probe using ?withoutAssets=true as a cheap change-detection fingerprint. When the fingerprint matches and no pending assets are outstanding, poll() short-circuits and does no asset fetch at all. (fe38d20)
• Delta-fetch active albums — when the fingerprint changes, poll with updatedAfter instead of refetching the whole album; falls back to a full fetch only on count decrease or mixed add+remove that delta can't reconcile. (fe38d20)
• Parallel meta probes — asyncio.gather over album meta probes so a 20-album tracker pays one round-trip of latency instead of 20. (fe38d20)
• Tick-scoped shared-links cache — new get_all_shared_links_by_album() coalesces to one /api/shared-links request per tick instead of one per changed album. (fe38d20)
• Module-level users cache — 1 h TTL, sha256-keyed, shared across providers that target the same Immich server. (fe38d20)
• Skip asset_ids DB rewrite on idle ticks — watcher no longer rewrites the (potentially ~8 MB for huge albums) JSON column when the fingerprint didn't change. (fe38d20)
• Adaptive polling — after 10 empty ticks the scheduler skips 1-in-2, after 30 empty ticks skips 1-in-4; resets on the first detected change or any schedule edit. (fe38d20)
• APScheduler jitter — interval/4, capped at 30 s, to smooth thundering-herd bursts when many trackers share the same scan_interval. (fe38d20)
• Event payload cap — 50 added / 200 removed assets per event so a bulk import can't explode a Jinja template or exceed Telegram message limits. (fe38d20)

Features

• Chat-action hint stays alive during slow command fetches — Telegram chat actions expire after ~5 s, so slow bot commands (/latest, /random, /favorites, /memory, /search, /find, /person, /place, /summary) previously showed a hint that vanished long before the media arrived and users saw nothing happening. New telegram_chat_action async context manager starts a keep-alive task that re-posts the action every 4 s until it exits; classify_command_chat_action maps each command to the right action (upload_photo for media-returning commands, typing for /summary, none for fast DB-only commands like /status / /events). Wired into both the webhook and long-poll paths. (69711bb)

---

All Commits

• 69711bb — feat(commands): keep chat-action hint alive during slow command fetches (alexei.dolgolyov)
• fe38d20 — perf(immich): skip full album fetch on idle ticks; delta-fetch for active ones (alexei.dolgolyov)