fix(api): prevent flash notification startup fd exhaustion

[Eli Bosley (elibosley)]

Summary

• stop using chokidar initial replay to hydrate existing notifications on startup
• bound notification stat/read work in batches to avoid fd spikes with large flash-backed directories
• add regression coverage for ignoreInitial startup behavior and capped concurrent reads

Testing

• pnpm --filter @unraid/api exec vitest run src/unraid-api/graph/resolvers/notifications/loadNotificationsFile.test.ts
• pnpm --filter @unraid/api exec vitest run src/unraid-api/graph/resolvers/notifications/notifications.service.spec.ts
• pnpm --filter @unraid/api exec eslint --config .eslintrc.ts src/unraid-api/graph/resolvers/notifications/notifications.service.ts src/unraid-api/graph/resolvers/notifications/loadNotificationsFile.test.ts src/unraid-api/graph/resolvers/notifications/notifications.service.spec.ts

Notes

• pnpm --filter @unraid/api exec tsc --noEmit still fails on an existing unrelated TEMPERATURE_METRICS type error in src/unraid-api/graph/resolvers/metrics/metrics.resolver.ts.

Summary by CodeRabbit

• Bug Fixes

  • Better handling of missing notification files and automatic creation/initialization of notification directories
  • Watcher now ignores initial events during startup and replays buffered additions after initialization to prevent lost notifications

• Performance

  • File reads and stats are processed in controlled batches to limit concurrent IO and reduce resource spikes

• Tests

  • Added tests for watcher initialization, replay behavior, concurrent file loading limits, and improved test state cleanup

[coderabbitai]

Walkthrough

Adds batched file I/O (max 32 concurrent), an initialization/hydration flow that ensures notification directories exist and queues watcher adds during hydration, improves ENOENT/missing-file handling, and updates tests with chokidar/fs mocks and cleanup utilities. No exported API signatures changed.

Changes

Cohort / File(s)	Summary
Tests — watcher & fs mocks api/src/unraid-api/graph/resolvers/notifications/loadNotificationsFile.test.ts	Hoisted chokidar watch mock (mockWatch) providing chainable on/close; extended fs/promises mock with mockStat and mockReadFile; added tests for ignoreInitial watcher option, replaying buffered add events after hydration, concurrency constraint (≤32) for reads, and stat-failure propagation.
Tests — service lifecycle helpers api/src/unraid-api/graph/resolvers/notifications/notifications.service.spec.ts	Added test helpers zeroOverview and disableNotificationsWatcher; ensure watcher is closed and global overview/remainder reset during test setup/teardown; made initialization waits async where needed.
Service implementation — batching & init api/src/unraid-api/graph/resolvers/notifications/notifications.service.ts	Added FILE_IO_BATCH_SIZE = 32, initialization state, settleInBatches helper; new initialization flow (initializeNotificationsState, ensureNotificationDirectories) that hydrates overview, sets watcher with ignoreInitial, queues/flushes pending adds; split add handling into handleNotificationAdd / processNotificationAdd; added isMissingFileError, buildOverviewSnapshot, and recalculateOverview; replaced unbounded Promise.all with batched processing for stat/read operations.

Sequence Diagram(s)

sequenceDiagram
participant Test as Tests
participant Service as NotificationsService
participant FS as FileSystem
participant Watcher as ChokidarWatcher
Test->>Service: initializeNotificationsState(basePath)
Service->>FS: ensureNotificationDirectories(basePath)
FS-->>Service: dirs created/exist
Service->>FS: list files (batched stat)
FS-->>Service: file list & stats
Service->>Service: buildOverviewSnapshot (load files batched)
Service-->>Test: overview published
Service->>Watcher: create watch(path, { ignoreInitial: true })
Watcher-->>Service: on('add') events (during hydration) -> queued
Service->>Service: after hydration -> replay queued adds
Service->>FS: load added files (batched, skip ENOENT)
FS-->>Service: file contents / ENOENT errors
Service->>Service: recalculateOverview -> publish

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐇 I nibbled paths and counted each file bright,
Batching thirty-two so nothing would bite.
I built up the snapshot, then watched with a hop,
Queued tiny adds while hydration did stop.
Now overview sings — all tidy and right. 📬

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(api): prevent flash notification startup fd exhaustion' directly and specifically describes the main change: preventing file descriptor exhaustion during flash notification startup through batched IO and initialization flow improvements.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/fix-flash-notification-open-files

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:0c0c6d5a34

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "Codex (@codex) review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".

[github-actions]

This plugin has been deployed to Cloudflare R2 and is available for testing.
Download it at this URL:

https://preview.dl.unraid.net/unraid-api/tag/PR1893/dynamix.unraid.net.plg

[coderabbitai]

🧹 Nitpick comments (1)

api/src/unraid-api/graph/resolvers/notifications/notifications.service.ts (1)

279-284: Biome static analysis: forEach callback should not return a value.

Set.add() returns the Set, so the forEach callback implicitly returns a value. While functionally correct, this violates the lint rule. Use a for-of loop or add braces to make the return void explicit.

♻️ Proposed fix

 const recalculate = async (type: NotificationType) => {
const ids = await this.listFilesInFolder(this.paths()[type]);
- ids.forEach((id) => seenPaths.add(id));+ for (const id of ids) {+ seenPaths.add(id);+ }
const [notifications] = await this.loadNotificationsFromPaths(ids, {});
notifications.forEach((n) => this.increment(n.importance, overview[type.toLowerCase()]));
};

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@api/src/unraid-api/graph/resolvers/notifications/notifications.service.ts`
around lines 279 - 284, The forEach callback in recalculate implicitly returns
the Set because seenPaths.add(id) returns a value, violating the lint rule;
change the ids.forEach((id) => seenPaths.add(id)); line to an explicit
void-returning form such as a for-of loop: for (const id of ids) {
seenPaths.add(id); } so the callback does not return a value—update the
recalculate function (and keep the subsequent this.loadNotificationsFromPaths
and this.increment usage unchanged).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@api/src/unraid-api/graph/resolvers/notifications/notifications.service.ts`:
- Around line 279-284: The forEach callback in recalculate implicitly returns
the Set because seenPaths.add(id) returns a value, violating the lint rule;
change the ids.forEach((id) => seenPaths.add(id)); line to an explicit
void-returning form such as a for-of loop: for (const id of ids) {
seenPaths.add(id); } so the callback does not return a value—update the
recalculate function (and keep the subsequent this.loadNotificationsFromPaths
and this.increment usage unchanged).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 467c0971-7546-47a1-a532-2e8014b78c9f

📥 Commits

Reviewing files that changed from the base of the PR and between 0c0c6d5 and 55ee1b4.

📒 Files selected for processing (2)

• api/src/unraid-api/graph/resolvers/notifications/loadNotificationsFile.test.ts
• api/src/unraid-api/graph/resolvers/notifications/notifications.service.ts

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 49.73%. Comparing base (337aecc) to head (55ee1b4).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...h/resolvers/notifications/notifications.service.ts	90.00%	11 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #1893 +/- ##
==========================================
+ Coverage 49.25% 49.73% +0.48% 
==========================================
Files 1020 1021 +1 Lines 69765 69966 +201 Branches 7254 7383 +129 ==========================================
+ Hits 34364 34799 +435 + Misses 35278 35044 -234 
Partials 123 123 

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.