@kairos-es/feed 0.0.0-stage → 0.0.0

package/src/reconcile.ts

@@ -0,0 +1,224 @@
+/**
+ * Reconcile: delete what a sink holds that the feed no longer has.
+ *
+ * ## Why a feed needs it at all
+ *
+ * The steady state deletes through tombstones, and a tombstone lives only until
+ * every sink registered on the feed has passed it. A record can still be left
+ * behind in a sink: a sink restored from a backup, a key written into the index by
+ * hand, or a record deleted before a reset, whose tombstone the reset cleared with
+ * every other row, followed by an in-place resync that, having no atomic swap,
+ * sends only the rows the new generation holds and so never deletes it. Reconcile is the one operation that compares the sink with the feed
+ * rather than replaying the feed into the sink, and so the only one that finds
+ * those orphans.
+ *
+ * ## The order of the two reads, and why it is safe
+ *
+ * The sink's keys are listed FIRST and the feed's live keys read SECOND. A key the
+ * sink lists that has a live row by the time the feed is read is kept, so a record
+ * written while reconcile runs is never deleted by it. A key whose row turns into
+ * a tombstone after the feed is read is kept too, and its tombstone deletes it on
+ * the next pass. And a key whose row comes back to life after the feed is read is
+ * deleted here and re-sent by the next pass, because its new `seq` is above the
+ * cursor. Reconcile runs inside the worker that holds the lease, between batches,
+ * so nothing else is sending to the sink while it does (ADR-0019 §8).
+ *
+ * ## What it costs
+ *
+ * It holds every key the sink lists and every live key of the feed in memory at
+ * once, and reads every live document to find the keys. It is a periodic repair,
+ * not a steady-state path: `reconcileEvery` should be measured in hours.
+ */
+import { Array as Arr, Effect, Option, Stream } from 'effect'
+import type { NonEmptyReadonlyArray } from 'effect/Array'
+import { deliver, type Pending } from './deliver'
+import type {
+  FeedUnreadable,
+  FeedWriteFailed,
+  LeaseHeld,
+  LeaseLost,
+  SinkHalted,
+  SinkRetryable,
+} from './errors'
+import type { FeedSource } from './Feed'
+import { FeedChange, type FeedReconcile, type FeedSink } from './FeedSink'
+import type { FeedLease, FeedSyncStore } from './FeedSyncStore'
+import { FEED_ORIGIN, type FeedKey, type FeedSinkId } from './identifiers'
+import { DEFAULT_FEED_PAGE_SIZE, readLimit } from './tuning'
+
+/** What one reconcile did. */
+export interface ReconcileReport {
+  /** How many keys the sink listed. */
+  readonly listed: number
+  /** The orphans deleted: listed by the sink, with no live row in the feed. */
+  readonly deleted: ReadonlyArray<FeedKey>
+  /** Orphans whose delete the sink refused, with its reason. They stay in the sink. */
+  readonly refused: ReadonlyArray<{
+    readonly key: FeedKey
+    readonly reason: string
+  }>
+}
+
+/** Every key of `source` whose row is live, read page by page from the origin. */
+export const liveKeys = <D>(
+  source: FeedSource<D>,
+  pageSize: number,
+): Effect.Effect<ReadonlySet<FeedKey>, FeedUnreadable> =>
+  Effect.gen(function* () {
+    const live = new Set<FeedKey>()
+    const limit = readLimit(pageSize)
+    let after = FEED_ORIGIN
+    for (;;) {
+      const rows = yield* source.changesAfter(after, limit)
+      for (const row of rows) {
+        if (Option.isSome(row.doc)) {
+          live.add(row.key)
+        } else {
+          live.delete(row.key)
+        }
+      }
+      const last = rows.at(-1)
+      if (last === undefined || rows.length < pageSize) {
+        return live
+      }
+      after = last.seq
+    }
+  })
+
+/**
+ * What `reconcileWith` hands its caller: the report, and which keys are now gone
+ * from the sink for good — not in the feed's live rows, and either deleted by this
+ * reconcile or not listed by the sink at all. Package-internal: the report is the
+ * consumer's, the predicate is for {@link unparkGone}.
+ *
+ * @internal
+ */
+export interface Reconciled {
+  readonly report: ReconcileReport
+  readonly isGone: (key: FeedKey) => boolean
+}
+
+/**
+ * Reconcile under a lease the caller already holds. Package-internal: the driver
+ * calls it between batches and in an in-place resync, and `reconcileFeed` calls it
+ * after taking the lease itself.
+ *
+ * @internal
+ */
+export const reconcileWith = <D, Receipt>(args: {
+  readonly source: FeedSource<D>
+  readonly sink: FeedSink<D, Receipt>
+  readonly reconcile: FeedReconcile
+  readonly lease: FeedLease
+  readonly pageSize: number
+}): Effect.Effect<
+  Reconciled,
+  SinkRetryable | SinkHalted | LeaseLost | FeedUnreadable
+> =>
+  Effect.gen(function* () {
+    const listed = yield* Stream.runCollect(args.reconcile.listKeys)
+    const live = yield* liveKeys(args.source, args.pageSize)
+    const orphans = Array.from(new Set(listed)).filter((key) => !live.has(key))
+    const deleted: Array<FeedKey> = []
+    const refused: Array<{ key: FeedKey; reason: string }> = []
+    for (const chunk of Arr.chunksOf(orphans, args.pageSize)) {
+      const pending: NonEmptyReadonlyArray<Pending<D>> = Arr.map(
+        chunk,
+        (key) => ({ change: FeedChange.Delete({ key }), seq: FEED_ORIGIN }),
+      )
+      const delivered = yield* deliver({
+        send: args.sink.apply,
+        confirm: args.sink.confirm,
+        lease: args.lease,
+        pending,
+      })
+      deleted.push(...delivered.sent)
+      refused.push(
+        ...delivered.parked.map((p) => ({ key: p.key, reason: p.reason })),
+      )
+    }
+    const listedKeys = new Set(listed)
+    const deletedKeys = new Set(deleted)
+    return {
+      report: { listed: listedKeys.size, deleted, refused },
+      isGone: (key) =>
+        !live.has(key) && (deletedKeys.has(key) || !listedKeys.has(key)),
+    }
+  })
+
+/**
+ * Unpark every parked key a reconcile found gone from the sink for good (see
+ * {@link Reconciled}): a park reporting a refusal for such a key — an in-place
+ * rebuild's orphan, or a tombstone whose delete the tail was refused — reports a
+ * record that is not there. `retryParked` unparks a key with no row and re-stamps
+ * one that has a row, which for a tombstone sends every sink one idempotent delete.
+ *
+ * It judges by what the sink holds, not by what this reconcile deleted, so a park
+ * an earlier unpark failed to clear goes on the next reconcile. That is why a
+ * failure here is a warning and not an error: it costs a stale entry in
+ * `inspectFeed` until then, and failing would end a worker's session, or discard
+ * an operator's report, over a record that is already gone.
+ *
+ * @internal
+ */
+export const unparkGone = (
+  store: FeedSyncStore,
+  id: FeedSinkId,
+  isGone: (key: FeedKey) => boolean,
+): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const parked = yield* store.readParked(id)
+    yield* Effect.forEach(
+      parked.filter((p) => isGone(p.key)),
+      (p) => store.retryParked({ ...id, key: p.key }),
+      { discard: true },
+    )
+  }).pipe(
+    Effect.catch((cause) =>
+      Effect.logWarning(
+        'feed reconcile could not unpark a record it found gone; the next reconcile will',
+        { feed: id.feed, sink: id.sink, reason: cause.message },
+      ),
+    ),
+  )
+
+/** Options for {@link reconcileFeed}. */
+export interface ReconcileFeedOptions<D, Receipt> {
+  readonly source: FeedSource<D>
+  readonly sink: FeedSink<D, Receipt> & { readonly reconcile: FeedReconcile }
+  readonly store: FeedSyncStore
+  /** How many rows to read, and deletes to send, at a time. */
+  readonly pageSize?: number
+}
+
+/**
+ * Reconcile `sink` against `source` once, now. It takes the worker lease itself,
+ * so it fails `LeaseHeld` while a sync worker for the same feed and sink runs —
+ * reconcile through that worker's `reconcileEvery` instead, or stop it first.
+ */
+export const reconcileFeed = <D, Receipt>(
+  options: ReconcileFeedOptions<D, Receipt>,
+): Effect.Effect<
+  ReconcileReport,
+  | LeaseHeld
+  | LeaseLost
+  | FeedUnreadable
+  | FeedWriteFailed
+  | SinkRetryable
+  | SinkHalted
+> =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const id = { feed: options.source.feed, sink: options.sink.name }
+      const lease = yield* options.store.acquireLease(id)
+      const { report, isGone } = yield* reconcileWith({
+        source: options.source,
+        sink: options.sink,
+        reconcile: options.sink.reconcile,
+        lease,
+        pageSize: options.pageSize ?? DEFAULT_FEED_PAGE_SIZE,
+      })
+      yield* unparkGone(options.store, id, isGone)
+      return report
+    }),
+  )