Lucas Berger
982438dc10
Mechanical reformat — no logic changes. 398 files changed, 19125 insertions(+), 16457 deletions(-). Prettier 3.8.4 with .prettierrc (singleQuote:true, semi:true, tabWidth:2, trailingComma:all, printWidth:100). Isolated per D-13-08 for reviewability.
10 KiB
10 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, user_setup, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | user_setup | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 03-event-write-back-pwa-install | 04 | tdd | 3 |
|
|
true |
|
|
Purpose: this closes the create/edit/delete loop end-to-end — after this plan a queued write actually reaches Fastmail and the cache becomes authoritative. Built TDD because the state machine (backoff, dead-letter, 412 routing, edit-as-move ordering) is the highest-risk logic in the phase.
Output: outboxWorker.ts GREEN against Plan 01's state-machine tests; worker started at boot.
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/phases/03-event-write-back-pwa-install/03-RESEARCH.md @.planning/phases/03-event-write-back-pwa-install/03-PATTERNS.md @apps/api/src/broker/poller.ts @apps/api/src/broker/sync.ts @apps/api/src/index.ts Task 1: GREEN — outbox drain state machine (outboxWorker.ts) apps/api/src/broker/outboxWorker.ts, apps/api/tests/broker/outboxWorker.test.ts - apps/api/tests/broker/outboxWorker.test.ts (RED state-machine stubs from Plan 01 — the contract) - .planning/phases/03-event-write-back-pwa-install/03-RESEARCH.md (§Pattern 4 — full runOutboxDrain reference; status classification sets; §Pitfall 5 edit-as-move; §Pitfall 7 DAVCalendar fetch for re-sync; §Pitfall 4 etag re-fetch) - apps/api/src/broker/poller.ts (analog — runX/startX pair, node-cron schedule, per-item error isolation, decrypt-then-client pattern, Drizzle select/where/limit) - apps/api/src/broker/sync.ts (syncCalendar signature: client, davCal, userId) - apps/api/src/broker/write.ts (create/update/deleteCalendarEvent — from Plan 02) - apps/api/src/broker/vevent.ts (buildVeventString — from Plan 02) - .planning/phases/03-event-write-back-pwa-install/03-PATTERNS.md (§outboxWorker.ts — exact poller-derived patterns) RED → GREEN. With mocked db, write.ts, sync.ts, and Fastmail client, tests assert: - pending row + mock create response 204/201 → status='done' AND triggerTargetedResync called for that calendarUrl (D-06). - mock response 412 → status='failed', re-sync triggered, NO retry, NO overwrite (D-08 conflict flow). - mock response 500 (transient) → status stays 'pending', attemptCount incremented, nextAttemptAt advanced by the backoff schedule (D-07). - transient failures repeated until attemptCount === MAX_ATTEMPTS → status='dead'. - mock response 401/403/400 (hard) → status='failed' immediately, no retry (D-07). - edit-as-move pair (shared groupId): the 'create' row is dispatched before the linked 'delete' row; if create fails, the delete is NOT executed (D-04 — duplicate is recoverable, lost event is not). Implement `runOutboxDrain()` and `startOutboxWorker()` per RESEARCH.md Pattern 4. Constants: `MAX_ATTEMPTS=5`, `BACKOFF_SECONDS=[15,60,300,600,1800]`, `TRANSIENT_STATUSES={408,429,500,502,503,504}`, `HARD_FAIL_STATUSES={400,401,403}`, `CONFLICT_STATUS=412`. Select `WHERE status='pending' AND next_attempt_at <= NOW()` limit 10. For each row: load the owning member's credential+client (decrypt via crypto.js + createFastmailClient like poller.ts), build the VEVENT via `buildVeventString` from the row payload for create/update, call the matching write.ts function, classify the Response status. On success or 412 call `triggerTargetedResync(calendarUrl, userId)` which fetches calendars via `client.fetchCalendars()`, finds the DAVCalendar by url (Pitfall 7), and calls `syncCalendar` — this captures the fresh etag/objectUrl (Pitfall 4). Update outbox status with the Drizzle update pattern. Order edit-as-move: process rows ordered so a row with `operation='create'` and a groupId runs before its sibling `operation='delete'`; on create failure skip the linked delete. Per-row try/catch logs without crashing the loop; never log decrypted passwords (T-03-04). `startOutboxWorker` schedules `runOutboxDrain` every 15s (node-cron `*/15 * * * * *` or setInterval), mirroring `startBrokerPoller`. cd /home/luc/Projects/familysync && pnpm --filter @familysync/api test -- broker/outboxWorker && pnpm --filter @familysync/api exec tsc --noEmit - outboxWorker.test.ts GREEN for all six behaviors (done, 412-conflict, backoff, dead, hard-fail, edit-as-move order). - `grep -q "syncCalendar" apps/api/src/broker/outboxWorker.ts` (D-06 re-sync). - `grep -Eq "412|CONFLICT_STATUS" apps/api/src/broker/outboxWorker.ts` (D-08). - tsc --noEmit passes. The outbox worker drains, writes, classifies, re-syncs, and handles backoff/dead/conflict/edit-as-move exactly per D-04/06/07/08; tests GREEN. Task 2: Wire startOutboxWorker into index.ts beside the ctag poller apps/api/src/index.ts - apps/api/src/index.ts (existing — startBrokerPoller() is called near the bottom; mirror placement/import style) - apps/api/src/broker/outboxWorker.ts (from Task 1 — exports startOutboxWorker) Add `import { startOutboxWorker } from './broker/outboxWorker.js'` next to the existing poller import. Call `startOutboxWorker()` immediately after the existing `startBrokerPoller()` call, with a one-line comment noting it drains the D-05 outbox every 15s. Do not move or alter the poller, route mounts, OIDC guard, or server-start guard. cd /home/luc/Projects/familysync && grep -q "startOutboxWorker()" apps/api/src/index.ts && pnpm --filter @familysync/api exec tsc --noEmit && pnpm --filter @familysync/api test - `grep -c "startOutboxWorker()" apps/api/src/index.ts` ≥1. - Full API test suite GREEN; tsc --noEmit passes. The outbox worker starts at API boot alongside the poller; full API suite green.<threat_model>
Trust Boundaries
| Boundary | Description |
|---|---|
| worker → Fastmail | The worker is the only component that drains the outbox to Fastmail |
| stored payload → VEVENT | Member-supplied payload is reconstructed into an ICS PUT |
STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|---|---|---|---|---|
| T-03-11 | Repudiation | silent last-write-wins on concurrent edit | mitigate | 412 If-Match conflict routes to conflict flow (re-sync + warn), never overwrites (D-08) |
| T-03-12 | Denial of Service | a poison row retrying forever | mitigate | MAX_ATTEMPTS=5 then dead-letter; bounded backoff window (~30 min) per D-07 |
| T-03-13 | Information Disclosure | logging decrypted app password during dispatch | mitigate | Per-item catch logs err.message only; never the credential (poller T-03-04 pattern) |
| T-03-14 | Tampering | partial-failure data loss on edit-as-move | mitigate | create-before-delete ordering; create-fail aborts delete; delete-fail surfaces "remove manually" (D-04) |
</threat_model>
- `pnpm --filter @familysync/api test` full suite GREEN (includes outboxWorker + routes/events from Plan 03). - `grep -c "startOutboxWorker()" apps/api/src/index.ts` ≥1. - No tsdav import outside broker/: worker uses write.ts/client.ts only.<success_criteria>
- End-to-end backend write loop closed: endpoint → outbox → worker → Fastmail → re-sync → cache authoritative.
- D-04/D-06/D-07/D-08 all enforced and tested. </success_criteria>