FLfloqer
ackDB

Segment change feed (poll)

Segment Sync S1: the change-log rows for a segment since cursor N - who entered / exited / re-entered. The response is ALWAYS a read of the committed append-only log (never an in-memory diff), so a poller that crashes before saving its cursor re-polls the same since and re-reads identical rows. The FIRST call bootstraps the snapshot and returns no rows (seed the initial members via /member-ids, so you never double-count). Runs under a non-blocking advisory lock (a concurrent call → 409). since > maxSeq → a 200 with reconcile:true, reason:cursor_ahead; since behind the prune watermark → 410 CURSOR_EXPIRED - both mean reconcile via /member-ids, never a silent empty-success. Derived segments are supported (their filterHash is the composite own+base - a base-filter edit flips it too); a cross-grain ?grain= request → 400 (save the pivot as a derived segment to sync it); the sync tables not yet provisioned → 503. Poll again with since = nextSince. Delivery is at-least-once (a crash-safe re-poll re-reads the same rows; a /member-ids-seeded member can also reappear as an early enter) - dedup per member id.

post/api/v1/ackdb/observe/segments/{id}/changes

Request

  • Base URL
    http://localhost:3009
  • Auth
    HTTP bearer

Path parameters

idstring required

Query parameters

sinceinteger

Cursor - return rows with seq > since. Omit or 0 to read from the earliest retained row.

Response

A page of change rows (empty after bootstrap, or with a reconcile signal).

segmentIdstring required
filterHashstring nullable required

The membership's version key - changes iff a defining filter changed (detect an edit). Base segment: md5 of its filter. Derived segment: the composite own+base, so a base-filter edit flips it too. Null when edit detection is degraded (pre-migration DB) - null-propagating for derived, never a sentinel that looks like a real hash.

maxSeqinteger required

The segment's current highest seq. You are caught up when your last row's seq === maxSeq.

minRetainedSeqinteger required

Earliest seq still retained (prunedThroughSeq + 1).

hasMoreboolean required

More rows beyond this page - re-poll with since = nextSince.

nextSinceinteger required

The cursor to poll with next (the last returned seq, or since if empty).

bootstrappedboolean

Present + true on the first call (snapshot built, no rows returned; seed via /member-ids).

reconcileboolean

Present + true when the cursor is unusable - re-seed via /member-ids (see reason).

reason'cursor_ahead' | 'cursor_expired'

Changes

No recorded changes to this operation across all 1 revision of this API.