Skip to content

Stop scheduled library probing: reconcile the index from watcher signals - #58

Merged
vyrti merged 1 commit into
mainfrom
fix/no-scheduled-library-scans
Oct 17, 2026
Merged

vyrti merged 1 commit into
mainfrom
fix/no-scheduled-library-scans

Conversation

@vyrti

@vyrti vyrti commented Oct 17, 2026

Copy link
Copy Markdown
Contributor

What

The reconciliation tick ran validate_and_cleanup_deleted_files — a stat pass over every indexed path — unconditionally every five minutes. 288 times a day, and on a NAS or a slow spinning drive each pass opens every file again. This PR removes the schedule: the index is now reconciled only when the watcher itself reports a problem.

Why the probe was there, and why it is not needed anymore

The probe was a backstop for event handling that had gaps at the time. Those gaps have since been closed by the preceding work:

  • OS events update the index and notify TVs directly. Created/Modified/Deleted events (plus renames that move content out of a library, moves into Trash, subtitle sidecars) upsert or remove rows and publish a ContentDirectory change — publish_content_change bumps the revision, clears cached Browse responses, and sends GENA notifications. What a TV shows changes the moment the OS tells us.
  • Restart holes are closed — the startup scan publishes its revision after completing, and revisions no longer restart at 1 per boot, so TV caches from a previous session are retired.
  • The watcher reports its own failures. A queue overflow (debouncer error) and a pathless rescan signal mark roots dirty; the next tick sweeps and reconciles exactly those roots. This was already in the tick; the new coverage pins it down (a_watcher_signal_reconciles_missing_files_and_notifies_tvs).

With all three in place, a scheduled probe only paid the cost without carrying correctness:

  • Cost: 5-minute cadence over the whole index — the exact thing a NAS or slow HDD cannot afford, precisely what full_rescan_interval_hours was introduced to avoid in Make a large library affordable: flat idle CPU, and a third of the memory #39.
  • What it still caught: only files deleted with neither an arriving event nor any dirty signal, with the interval disabled. Those now wait for the next startup scan (enabled by default), which reconciles the whole library and publishes the change on completion.

Changes

  • monitoring.rs: validate_and_cleanup_deleted_files now runs only under full_sweep_due || !dirty_roots.is_empty() — the roots the backend reported or the user-configured backstop. Availability checks (read_dir per root) and dirty-root sweeps are unchanged; no per-file stats happen without cause.
  • config/model.rs: full_rescan_interval_hours default changed 24 → 0. The watcher is authoritative; the sweep is the operator opt-in for mounts that cannot deliver events (a network share changing on another machine never will). Explicit configs are untouched, VUIO_FULL_RESCAN_INTERVAL_HOURS still overrides, and the admin UI description already documents the 0 behavior. cleanup_deleted_files semantics are unchanged (honored per tick, live).
  • watcher/mod.rs: test-only mark_roots_dirty() to simulate a backend reporting lost events.
  • events.rs: replaces the test that codified the five-minute probe with two tests — ticks_without_a_watcher_signal_do_not_scan_the_library (interval 0: rows stay, revision stays, cached listings stay warm) and a_watcher_signal_reconciles_missing_files_and_notifies_tvs (dirty root: sweep + reconcile + revision bump + cache retired + refreshed listing, UpdateID published).

Validation

  • cargo test -p vuio-core: 842 passed, 8 ignored, 0 failed
  • cargo fmt -p vuio-core -p vuio-cli -p vuio-cast -p vuio-web --check: clean
  • cargo clippy -p vuio-cli -p vuio-core -p vuio-cast -p vuio-web --all-targets: 0 warnings

…probe

The reconciliation tick validated every indexed path every five minutes —
a stat pass over the whole index 288 times a day, on a NAS or a slow
spinning disk the most expensive thing an idle server does every five
minutes. It only ever existed as a backstop for event handling that
needed fixing sooner, which it now has: deletions, moves out of the
library, empty libraries, restart revisions and dropped-event signals
all apply to the index directly and publish the change to TVs.

The tick now reconciles the index only when the watcher itself reports a
problem — a root marked dirty by a queue overflow or a rescan signal —
or when the configured full-rescan interval is due. That interval is
now disabled by default: the watcher is authoritative, and a mount whose
changes happen on another machine is exactly the case the setting
documents and leaves up to the operator. OS events, wildcards and
startup scans behave as they already did.
@vyrti
vyrti merged commit 374ab2f into main Oct 17, 2026
21 checks passed
@vyrti
vyrti deleted the fix/no-scheduled-library-scans branch October 17, 2026 04:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant