0.2.76 - Icon Packs

server/README.md

@@ -429,6 +429,56 @@ favourites and resume positions are per-user and cannot be shared across a house
 they still come from Emby live. The imported copy powers search and the recommendation
 candidate pool.
 
+### Event-driven ingest
+
+Sonarr and Radarr are the things that put files on disk, so they are what the catalogue
+learns from. Both post to the gateway, each event is recorded in `library_ingest_queue`,
+and a single worker reads the named title out of Emby a minute later — rather than the
+whole catalogue waiting on the next sweep. An episode imported at 19:05 is searchable at
+19:06 instead of as late as 20:00.
+
+| | |
+|---|---|
+| Sonarr | `POST /hooks/sonarr?token=$MEMBY_SONARR_WEBHOOK_TOKEN` |
+| Radarr | `POST /hooks/radarr?token=$MEMBY_RADARR_WEBHOOK_TOKEN` |
+
+In each *arr: **Settings → Connect → + → Webhook**, method POST, with **On Import, On
+Upgrade, On Rename, On File Delete** and **On Series/Movie Delete** ticked. The token may
+also be sent as `X-Memby-Token`, a bearer token or basic-auth password; an unset token
+makes the hook 404, so a deployment that never configured one cannot be posted to. Press
+**Test** to check reachability — it answers 200 and records nothing.
+
+Both hooks sit outside the maintenance gate *and* outside the quiet-time gate, which is
+the point of the queue being durable: the gate answers 503 and neither *arr re-delivers,
+so a quiet hour would otherwise discard every import that happened during it. The hook
+records at any hour; the worker is where quiet time is honoured.
+
+**What each event does.** An import or an upgrade re-reads the item — an upgrade is silent
+as *news*, because the film was already there, but the file genuinely changed. A rename is
+a refresh and never an invalidation: the Emby item id survives a move, and so does the
+credits marker measured against it. A delete removes the row and its credits marker, and
+only counts when the media went with it — a series unfollowed in Sonarr with its files
+left on disk is still in the library.
+
+**Nothing is done twice.** The queue key is derived from the *file* rather than the
+delivery, so a repeated webhook collapses onto one row; a file deleted and re-imported is
+a different file and its own work. Emby not having scanned a new file yet is the expected
+first answer rather than a fault: one rescan nudge is sent and the row retries on a
+widening backoff (1m, 5m, 20m, 1h, then four-hourly) before being given up on.
+
+**The sweep is reconciliation now.** `MEMBY_SYNC_INTERVAL` still runs the incremental
+import, and with both webhooks wired up it exists for what the *arrs do not manage — a
+file dropped in by hand, a title edited in Emby, a notification that never arrived because
+the container was down. Six hours is a sensible value then; the console can set it at
+**Settings → Catalogue sweep** without a redeployment, and it takes effect on the next
+cycle rather than at the next restart.
+
+**Where to look.** Admin console → **Imports** shows whether each hook is configured, what
+is waiting, and the last fifty events with why each was queued and what happened to it —
+which is the page to read when somebody says a new episode is not showing up. In the log
+it is `event=arr_ingest` with an `outcome` of `queued`, `imported`, `removed`, `absent`,
+`not_found` or `deferred`.
+
 ## Maintenance mode
 
 Takes Memby down independently of Emby: all `/v1` routes answer `503` with