diff --git a/.planning/STATE.md b/.planning/STATE.md index a6d8cdb..a993dde 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -148,6 +148,7 @@ Recent decisions affecting current work: | 260610-cr8 | Adopt drizzle generate+migrate workflow, retire db:push on MariaDB — removed db:push script + repointed deployment.md to migrate with anti-push warning; dry-verified no destructive diff | 2026-06-10 | 1a95d81 | Verified | [260610-cr8-adopt-drizzle-generate-migrate-workflow-](./quick/260610-cr8-adopt-drizzle-generate-migrate-workflow-/) | | 260610-czd | Fix docs/deployment.md local-dev command — added "Running locally (host-side, no Docker)" subsection with correct env-sourced two-terminal run command (Phase 2 UAT gap) | 2026-06-10 | 39e2ee0 | | [260610-czd-fix-docs-deployment-md-local-dev-command](./quick/260610-czd-fix-docs-deployment-md-local-dev-command/) | | 260610-hbu | Phase 5 reminder scheduler resilience (UAT Test 1 gap) — catch-up scan `(now, now+16min]` + per-uid exactly-once dedup so a missed/late cron tick no longer drops a reminder; lead-accurate body; also fixes pre-existing cross-tick double-fire. 10/10 reminder tests pass | 2026-06-10 | 19d92c6 | Verified | [260610-hbu-make-phase-5-reminder-scheduler-resilien](./quick/260610-hbu-make-phase-5-reminder-scheduler-resilien/) | +| 260610-i4x | Replace node-cron with setInterval in all 3 broker workers (poller/outbox/reminder) — node-cron 4.2.1 skipped EVERY scheduled execution in the long-running API process ("missed execution" each tick), so reminders/poll/outbox never fired on schedule. setInterval fires reliably (verified). 91 broker tests pass | 2026-06-10 | d9efbc1 | Verified | [260610-i4x-replace-node-cron-with-setinterval-in-ba](./quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/) | ## Deferred Items diff --git a/.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-PLAN.md b/.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-PLAN.md new file mode 100644 index 0000000..754dc72 --- /dev/null +++ b/.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-PLAN.md @@ -0,0 +1,164 @@ +--- +phase: quick-260610-i4x +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - apps/api/src/broker/poller.ts + - apps/api/src/broker/outboxWorker.ts + - apps/api/src/broker/reminderScheduler.ts +autonomous: true +requirements: + - QUICK-i4x +must_haves: + truths: + - "The three background workers schedule their callbacks with setInterval, not node-cron schedule()" + - "No worker file imports node-cron" + - "runPoll / runOutboxDrain / runReminderCheck callback bodies are unchanged (still .catch-wrapped)" + - "Interval timings are preserved: poller 5 min, outbox 15 s, reminder 1 min" + - "apps/api typechecks clean and the broker unit tests still pass" + artifacts: + - path: "apps/api/src/broker/poller.ts" + provides: "startBrokerPoller scheduling runPoll via setInterval(5min)" + contains: "setInterval" + - path: "apps/api/src/broker/outboxWorker.ts" + provides: "startOutboxWorker scheduling runOutboxDrain via setInterval(15s)" + contains: "setInterval" + - path: "apps/api/src/broker/reminderScheduler.ts" + provides: "startReminderScheduler scheduling runReminderCheck via setInterval(1min)" + contains: "setInterval" + key_links: + - from: "apps/api/src/broker/poller.ts" + to: "runPoll" + via: "setInterval(cb, 5 * 60 * 1000)" + pattern: "setInterval\\(" + - from: "apps/api/src/broker/outboxWorker.ts" + to: "runOutboxDrain" + via: "setInterval(cb, 15 * 1000)" + pattern: "setInterval\\(" + - from: "apps/api/src/broker/reminderScheduler.ts" + to: "runReminderCheck" + via: "setInterval(cb, 60 * 1000)" + pattern: "setInterval\\(" +--- + + +Replace the node-cron `schedule()` scheduling mechanism with `setInterval` in the three +background worker `start*` functions so scheduled tasks actually fire in the long-running +API process. + +Purpose: node-cron 4.2.1 silently skips scheduled executions in the long-lived server +process — the orchestrator proved this live against the running prod container (continuous +`[NODE-CRON][WARN] missed execution` at every tick while CPU sat at 0.15%; a plain +`setInterval(…,1000)` in the SAME container fired 8/8 ticks, and a FRESH node-cron process +fired 8/8 — only the long-lived process misbehaves). Net effect: the CalDAV poller, the +outbox drain, and the reminder scan never fire on schedule. They only ran when triggered +manually during debugging. + +Output: Three worker files where `startBrokerPoller`, `startOutboxWorker`, and +`startReminderScheduler` schedule their existing callbacks with `setInterval` at the same +intervals, with the now-unused `node-cron` import removed and stale doc comments updated. + + + +@$HOME/.claude/gsd-core/workflows/execute-plan.md + + + +@./CLAUDE.md + +# The three worker files — only the start* functions and their doc comments change. +# Do NOT modify runPoll / runOutboxDrain / runReminderCheck logic. +@apps/api/src/broker/poller.ts +@apps/api/src/broker/outboxWorker.ts +@apps/api/src/broker/reminderScheduler.ts + + + + + + Task 1: Swap node-cron schedule() for setInterval in the three worker start* functions + apps/api/src/broker/poller.ts, apps/api/src/broker/outboxWorker.ts, apps/api/src/broker/reminderScheduler.ts + +In each of the three files, replace the node-cron scheduling call inside the start* function +with a setInterval call, keeping the callback body EXACTLY as written (it already wraps the +run function in `.catch(...)`). Then remove the now-unused `import { schedule } from 'node-cron'` +line from each file. Do NOT touch runPoll / runOutboxDrain / runReminderCheck, the constants, +helpers, or any other code. Do NOT touch index.ts, package.json, or the lockfile — the start* +function names and signatures are unchanged so index.ts keeps working as-is. + +Exact mapping (interval in ms = the cron cadence; setInterval fires after the first interval, +same first-run timing as the old cron — do NOT add an immediate kick, that is out of scope): + +- poller.ts `startBrokerPoller`: change `schedule('*/5 * * * *', () => { ... })` to + `setInterval(() => { ... }, 5 * 60 * 1000)` — keep the same arrow-function callback body + (the `runPoll().catch(...)` block). + +- outboxWorker.ts `startOutboxWorker`: change `schedule('*/15 * * * * *', () => { ... })` to + `setInterval(() => { ... }, 15 * 1000)` — keep the same `runOutboxDrain().catch(...)` body. + +- reminderScheduler.ts `startReminderScheduler`: change `schedule('* * * * *', () => { ... })` + to `setInterval(() => { ... }, 60 * 1000)` — keep the same `runReminderCheck().catch(...)` body. + +Do NOT call `.unref()` on the returned Timer — we WANT the interval to keep the event loop +alive (same effect as cron kept the process alive). Storing the returned Timer handle in a +module-level variable is acceptable if cleaner, but not required — fire-and-forget matches the +current pattern (the workers run for the process lifetime). + +Update the now-stale doc comments that reference node-cron so they describe setInterval, keeping +the WHY. Specifically: + - poller.ts: the file-header line "runs every 5 minutes via node-cron", the + "startBrokerPoller wraps it in node-cron's 5-minute schedule." line, the + "Source: https://github.com/node-cron/node-cron ..." source line, and the + "Starts the 5-minute background polling schedule." block. + - outboxWorker.ts: "startOutboxWorker wraps it in a 15-second node-cron schedule." and the + "Source: https://github.com/node-cron/node-cron (v4 stable)" line, plus the + "Starts the 15-second background outbox drain schedule." block. + - reminderScheduler.ts: the file-header "Fires every minute via node-cron." line and the + "Start the 1-minute reminder scan schedule." block comment ("keeps the cron out of the test + process" → setInterval phrasing). +Each updated comment must briefly state the WHY (node-cron 4.2.1 skipped scheduled executions +in the long-running server process, so scheduling uses setInterval instead). Keep edits brief — +do not rewrite the surrounding decision/threat-mitigation prose. Leave the `node-cron` dependency +in package.json (now unused, harmless); it is removable later but removing it now risks lockfile +drift and is out of scope for this tight change. + + + cd /home/luc/Projects/familysync && ! grep -rn "node-cron" apps/api/src/broker/poller.ts apps/api/src/broker/outboxWorker.ts apps/api/src/broker/reminderScheduler.ts | grep -v '^\s*[0-9]*:.*//' ; grep -c "setInterval" apps/api/src/broker/poller.ts apps/api/src/broker/outboxWorker.ts apps/api/src/broker/reminderScheduler.ts + cd /home/luc/Projects/familysync && pnpm --filter @familysync/api typecheck + cd /home/luc/Projects/familysync && pnpm --filter @familysync/api exec vitest run tests/broker/ + + +All three files import setInterval-based scheduling with no remaining `import { schedule } from 'node-cron'`; +each start* function calls setInterval at the correct interval (poller 300000 ms, outbox 15000 ms, +reminder 60000 ms) with its original callback body intact; `pnpm --filter @familysync/api typecheck` +exits 0; and `pnpm --filter @familysync/api exec vitest run tests/broker/` reports all broker tests +green (runPoll / runOutboxDrain / runReminderCheck behavior unchanged). + + + + + + +- No `import { schedule } from 'node-cron'` remains in any of the three worker files. +- `grep setInterval` matches in all three files (one per start* function). +- runPoll / runOutboxDrain / runReminderCheck logic is byte-for-byte unchanged (only doc + comments and the scheduling call were touched). +- `pnpm --filter @familysync/api typecheck` exits 0. +- `pnpm --filter @familysync/api exec vitest run tests/broker/` passes (crypto, expand, outboxWorker, + poller, reminderScheduler, sync, vevent, write). Do NOT run the full suite — it has ~68 pre-existing + DB-integration failures unrelated to this change (MariaDB host port not exposed in prod-compose). +- index.ts, package.json, and the lockfile are untouched. + + + +The three background workers schedule their callbacks via setInterval at the original intervals +(5 min / 15 s / 1 min), node-cron is no longer imported in src/broker, the apps/api typecheck is +clean, and the broker unit tests still pass — so in the long-running API process the poller, outbox +drain, and reminder scan will now actually fire on schedule. + + + +Create `.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-SUMMARY.md` when done. + diff --git a/.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-SUMMARY.md b/.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-SUMMARY.md new file mode 100644 index 0000000..e6733b1 --- /dev/null +++ b/.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-SUMMARY.md @@ -0,0 +1,80 @@ +--- +phase: quick-260610-i4x +plan: "01" +subsystem: broker +tags: [scheduler, setInterval, node-cron, fix] +dependency_graph: + requires: [] + provides: [reliable-broker-scheduling] + affects: [broker/poller, broker/outboxWorker, broker/reminderScheduler] +tech_stack: + added: [] + patterns: [setInterval-based-scheduling] +key_files: + created: [] + modified: + - apps/api/src/broker/poller.ts + - apps/api/src/broker/outboxWorker.ts + - apps/api/src/broker/reminderScheduler.ts +decisions: + - "Use setInterval for broker worker scheduling: node-cron 4.2.1 silently skipped executions in the long-running API process; setInterval is reliable in the same process" +metrics: + completed: "2026-06-10" +--- + +# Quick Task 260610-i4x: Replace node-cron with setInterval in Broker Workers Summary + +**One-liner:** Replaced `node-cron` `schedule()` calls with `setInterval` (300 s / 15 s / 60 s) in all three broker worker `start*` functions so scheduled tasks actually fire in the long-running API process. + +## Tasks Completed + +| Task | Name | Commit | Files | +|------|------|--------|-------| +| 1 | Swap node-cron schedule() for setInterval in the three worker start* functions | d9efbc1 | poller.ts, outboxWorker.ts, reminderScheduler.ts | + +## Changes Made + +### apps/api/src/broker/poller.ts +- Removed `import { schedule } from 'node-cron'` +- `startBrokerPoller`: `schedule('*/5 * * * *', cb)` → `setInterval(cb, 5 * 60 * 1000)` +- Updated file-header and JSDoc comments to reference setInterval and document the WHY + +### apps/api/src/broker/outboxWorker.ts +- Removed `import { schedule } from 'node-cron'` +- `startOutboxWorker`: `schedule('*/15 * * * * *', cb)` → `setInterval(cb, 15 * 1000)` +- Updated header comment and scheduler JSDoc + +### apps/api/src/broker/reminderScheduler.ts +- Removed `import { schedule } from 'node-cron'` +- `startReminderScheduler`: `schedule('* * * * *', cb)` → `setInterval(cb, 60 * 1000)` +- Updated file-header "Fires every minute" line and scheduler JSDoc + +Callback bodies (the `.catch`-wrapped `runPoll` / `runOutboxDrain` / `runReminderCheck` calls) are byte-for-byte unchanged. No `.unref()` added — intervals intentionally keep the event loop alive. + +## Verification Results + +- `! grep -rn "import.*node-cron" apps/api/src/broker/`: exits 1 (no matches) — all imports removed +- `pnpm --filter @familysync/api typecheck`: **exit 0** — clean +- `pnpm --filter @familysync/api exec vitest run tests/broker/`: **8 test files passed, 91 tests passed** + +## Deviations from Plan + +None — plan executed exactly as written. + +## Known Stubs + +None. + +## Threat Flags + +None — no new network surface, auth paths, file access, or schema changes introduced. + +## Self-Check: PASSED + +- [x] `apps/api/src/broker/poller.ts` modified — confirmed +- [x] `apps/api/src/broker/outboxWorker.ts` modified — confirmed +- [x] `apps/api/src/broker/reminderScheduler.ts` modified — confirmed +- [x] Commit d9efbc1 exists on branch gsd/v1.0-milestone +- [x] No `import { schedule } from 'node-cron'` in any of the three files +- [x] typecheck: exit 0 +- [x] broker tests: 8 files / 91 tests — all green diff --git a/.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-VERIFICATION.md b/.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-VERIFICATION.md new file mode 100644 index 0000000..a6e4a74 --- /dev/null +++ b/.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-VERIFICATION.md @@ -0,0 +1,73 @@ +--- +phase: quick-260610-i4x +verified: 2026-06-10T17:08:30Z +status: passed +score: 5/5 must-haves verified +--- + +# Quick Task 260610-i4x: Verification Report + +**Task Goal:** Replace node-cron with setInterval in the three background workers (poller, outboxWorker, reminderScheduler) so scheduled tasks fire in the long-running process. +**Verified:** 2026-06-10T17:08:30Z +**Status:** passed +**Re-verification:** No — initial verification + +## Goal Achievement + +### Observable Truths + +| # | Truth | Status | Evidence | +|---|-------|--------|----------| +| 1 | The three background workers schedule their callbacks with setInterval, not node-cron schedule() | VERIFIED | Each start* function contains `setInterval(()=>{…}, N)` at lines poller.ts:96, outboxWorker.ts:758, reminderScheduler.ts:210. Zero `schedule(` calls remain in any of the three files. | +| 2 | No worker file imports node-cron | VERIFIED | All remaining `node-cron` text is inside JSDoc block comments (WHY context). `grep -n "import.*node-cron"` returns no matches. Commit d9efbc1 stat confirms only 3 files changed. | +| 3 | runPoll / runOutboxDrain / runReminderCheck callback bodies are unchanged (still .catch-wrapped) | VERIFIED | poller.ts:97 `runPoll().catch(...)`, outboxWorker.ts:759 `runOutboxDrain().catch(...)`, reminderScheduler.ts:211 `runReminderCheck().catch(...)` — identical catch wrappers present. | +| 4 | Interval timings are preserved: poller 5 min, outbox 15 s, reminder 1 min | VERIFIED | poller.ts:100 `5 * 60 * 1000` (300000 ms), outboxWorker.ts:762 `15 * 1000` (15000 ms), reminderScheduler.ts:214 `60 * 1000` (60000 ms). | +| 5 | apps/api typechecks clean and the broker unit tests still pass | VERIFIED | `pnpm --filter @familysync/api typecheck` exited 0 (no output). `pnpm --filter @familysync/api exec vitest run tests/broker/` reported 8 test files passed, 91 tests passed. | + +**Score:** 5/5 truths verified + +### Required Artifacts + +| Artifact | Expected | Status | Details | +|----------|----------|--------|---------| +| `apps/api/src/broker/poller.ts` | startBrokerPoller scheduling runPoll via setInterval(5min) | VERIFIED | setInterval at line 96, `5 * 60 * 1000` at line 100, `runPoll().catch(...)` callback | +| `apps/api/src/broker/outboxWorker.ts` | startOutboxWorker scheduling runOutboxDrain via setInterval(15s) | VERIFIED | setInterval at line 758, `15 * 1000` at line 762, `runOutboxDrain().catch(...)` callback | +| `apps/api/src/broker/reminderScheduler.ts` | startReminderScheduler scheduling runReminderCheck via setInterval(1min) | VERIFIED | setInterval at line 210, `60 * 1000` at line 214, `runReminderCheck().catch(...)` callback | + +### Key Link Verification + +| From | To | Via | Status | Details | +|------|----|-----|--------|---------| +| `apps/api/src/broker/poller.ts` | runPoll | `setInterval(cb, 5 * 60 * 1000)` | VERIFIED | Line 96-100 in startBrokerPoller | +| `apps/api/src/broker/outboxWorker.ts` | runOutboxDrain | `setInterval(cb, 15 * 1000)` | VERIFIED | Line 758-762 in startOutboxWorker | +| `apps/api/src/broker/reminderScheduler.ts` | runReminderCheck | `setInterval(cb, 60 * 1000)` | VERIFIED | Line 210-214 in startReminderScheduler | + +### Behavioral Spot-Checks + +| Behavior | Command | Result | Status | +|----------|---------|--------|--------| +| TypeScript compiles clean | `pnpm --filter @familysync/api typecheck` | exit 0, no output | PASS | +| Broker unit tests pass | `pnpm --filter @familysync/api exec vitest run tests/broker/` | 8 files / 91 tests passed | PASS | + +### Scope Containment + +| Check | Result | +|-------|--------| +| Commit d9efbc1 touches only 3 files | VERIFIED — git show stat: outboxWorker.ts, poller.ts, reminderScheduler.ts only | +| index.ts not modified | VERIFIED — not in commit stat | +| package.json not modified | VERIFIED — not in commit stat | +| pnpm-lock.yaml not modified | VERIFIED — not in commit stat | +| No `.unref()` added | VERIFIED — grep returns no matches in any of the three files | + +### Anti-Patterns Found + +None. All node-cron mentions are in block comments providing WHY context, not imports or calls. + +### Human Verification Required + +None. + +--- + +_Verified: 2026-06-10T17:08:30Z_ +_Verifier: Claude (gsd-verifier)_