feat(api): server-authoritative change feed (spec 065 PR-A) #1352
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/sync-change-feed"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Implements spec 065 increment PR-A — server change feed per ADR 0117 Option D. Additive and read-only: nothing consumes the feed yet (no Android, no intents, no existing-endpoint behavior change).
Scope (S1–S3 server side only)
media_items.change_seq BIGINT NOT NULL, one-time backfill in per-ownercreated_atorder (updated_atonly as deterministic tiebreaker — it is NOT the cursor going forward), single-row globalsync_seqcounter table, per-ownermedia_owner_profiles.sync_epoch(starts at 1), keyset index(owner_id, change_seq).GET /api/sync/changes?cursor=&limit=(S2): owner-scoped keyset pagination (WHERE change_seq > cursor ORDER BY change_seq ASC LIMIT), envelope{epoch, changes[], nextCursor, hasMore}, per-change payload exactly the S2 fields (changeSeq, mediaItemId, lifecycleState, contentHash, originalFilename, byteSize, mediaType, capturedAt, updatedAt), state-feed semantics (the row's LATEST entry is the truth — trash/purge are lifecycle transitions on permanent rows, replay-from-0 always possible), first sync = cursor 0 (no bootstrap endpoint), default/max limit 200/1000, negative cursor → RFC 9457 ProblemDetail 400. Auth identical to sibling owner-scoped endpoints (/api/**authenticated +media:readAPI-credential scope, owner from session).sync_epochin the same transaction as the hard DELETE (the only signal that feed history was truncated). DB restore = operator adds 1 (ADR 0117).SyncChangesPage/SyncChangeschemas added tospecs/001-v1-baseline/contracts/core-api.openapi.yamlfollowing the file's existing style.How commit-ordered seq allocation is guaranteed (ADR 0117 risk #1)
ONE coherent mechanism (documented in the migration header): a
BEFORE INSERT OR UPDATE OF <sync-visible columns>trigger onmedia_itemsallocateschange_seqfrom the single-rowsync_seqcounter via an atomicINSERT … ON CONFLICT DO UPDATE … RETURNING. The counter row lock is held to commit, so allocation order == commit order — the reason a plain PostgresSEQUENCEwas rejected (non-transactionalnextval()can commit out of order and burn gaps, which would make a client's> cursorkeyset skip a committed change forever). The trigger deliberately covers INSERT too (an update-only trigger would never fire for new rows), so every writer goes through one code path. Explicit seq assignments (the backfill) pass through via anIS DISTINCT FROM OLDguard — a bareIS NOT NULLcheck would silently swallow every UPDATE becauseNEW.change_seqcarries the row's previous value. The allocator self-heals an empty counter (DB restore) instead of failing with a not-null violation.Writer inventory (verified exhaustively; every writer hits the trigger)
apps/api/src/main/java/dev/memories/api/upload/UploadCommitService.java:280apps/api/src/main/java/dev/memories/api/media/TrashService.java:48apps/api/src/main/java/dev/memories/api/media/TrashService.java:68apps/api/src/main/java/dev/memories/api/media/TrashService.java:92apps/api/src/main/java/dev/memories/api/media/TrashService.java:134apps/api/src/main/java/dev/memories/api/worker/WorkerResultService.java:807(acceptMetadataCandidate)apps/api/src/main/java/dev/memories/api/media/MediaMaintenanceService.java:1378(delete) /:1397(epoch)Grep sweep over
apps/api(allUPDATE|INSERT INTO|DELETE FROM media_itemsoccurrences incl. multi-line text blocks) andapps/worker-media(no direct DB writes) found no other writer. Non-sync-visible UPDATEs (none exist today besides maintenance deletes) would not fire the trigger by design — the watched-column list matches the S2 payload;updated_atis watched, so any future service write that touches a sync field viaupdated_atis covered as a safety net.Tests (SyncChangeFeedIntegrationTest — real Flyway chain, Testcontainers Postgres, TrashServiceTest-style harness)
COUNT(*)=1after purge).Validation
rtk ./gradlew :apps:api:test: BUILD SUCCESSFUL — 2269 tests, 0 failures, 0 errors, 9 skipped (pre-existing conditional skips).PersonRelationServicePostgresTest.theChosenRepresentativeWinsOverTheLatestOccurrence; reproduced identically on a pristine checkout of basee774b693→ pre-existing flake, already tracked as ISSUE-169; passes in isolation.Not done (per increment plan)
No Android changes, no
POST /api/sync/intents(PR-C), no event-log table, no per-device server state, no changes to existing endpoints. KNOWN_ISSUES.md untouched (no user-visible behavior ships).