@kairos-es/feed-algolia 0.0.0-stage → 0.0.0

package/dist/dts-cjs/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @kairos-es/feed-algolia — a `FeedSink` onto an Algolia index, with both of the
+ * port's optional parts: a `FeedResync` that rebuilds into a fresh index and moves
+ * it over the served one, and a `FeedReconcile` that lists the served index's ids.
+ *
+ * It talks to Algolia's REST API through `effect`'s own `HttpClient`, so it peers
+ * `effect` and `@kairos-es/feed` and nothing else, and the application chooses the
+ * HTTP transport by providing the client — `FetchHttpClient.layer` from
+ * `effect/http`, say.
+ *
+ * Where each part's argument lives:
+ *
+ * - `makeAlgoliaSink` (`sink.ts`): the steady state, resync and reconcile, and how
+ *   `confirm` waits.
+ * - Encoding and the size pre-check (`records.ts`): why only full-record writes,
+ *   and why oversized records are refused before they are sent.
+ * - Error classification (`classify.ts`): which Algolia answers are retryable,
+ *   which refuse one record, and which stop the worker.
+ * - The REST calls (`rest.ts`): why no SDK, the host failover kept from it, and
+ *   how the admin key is kept out of anything printed.
+ *
+ * Wiring:
+ *
+ * ```ts
+ * const sink = yield* makeAlgoliaSink({
+ *   name: SinkName.make('search'),
+ *   appId: AlgoliaAppId.make(config.appId),
+ *   adminKey: config.adminKey, // a Redacted<string>, from the application's config
+ *   index: AlgoliaIndexName.make('courses'),
+ *   doc: CourseDoc,
+ * }).pipe(Effect.provide(FetchHttpClient.layer))
+ * yield* Effect.forkScoped(runFeedSync({ source, sink, store }))
+ * ```
+ */
+export { AlgoliaAppId, AlgoliaIndexName, AlgoliaTaskId, } from './identifiers.js';
+export { DEFAULT_MAX_RECORD_BYTES } from './records.js';
+export type { AlgoliaConnection, AlgoliaTimeouts } from './rest.js';
+export { type AlgoliaReceipt, type AlgoliaSinkOptions, type AlgoliaTaskPolling, makeAlgoliaSink, } from './sink.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/dts-cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,GACd,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACpD,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AAChE,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,eAAe,GAChB,MAAM,QAAQ,CAAA"}

package/dist/dts-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/dts-cjs/records.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Turning a batch of feed changes into Algolia batch operations, and refusing the
+ * records Algolia would refuse BEFORE they are sent.
+ *
+ * ## Full-record replace, and nothing partial
+ *
+ * An upsert is `addObject` with the record's `objectID` set to the feed key, which
+ * replaces whatever Algolia held under that id; a delete is `deleteObject`. Both
+ * leave the index the same however many times they are sent, which is the
+ * idempotence the driver relies on when it resends a batch it could not confirm.
+ * Algolia's partial operations (`partialUpdateObject`, the built-in `Increment`
+ * and its kin) do not: applied twice they apply twice. They are never used.
+ *
+ * The key is written LAST, over the encoded document, so a document that carries an
+ * `objectID` field of its own cannot point a record at another key.
+ *
+ * ## Why oversized records are refused here
+ *
+ * Algolia refuses a whole `batch` when one record in it is over the plan's record
+ * size limit. Its answer does name the record, and `classify.ts` turns that into a
+ * rejection of that one key — but only after a round trip that wrote nothing, and
+ * only for the first oversized record the batch held. Checking every record's size
+ * up front rejects all of them at once, so the driver's resend of the rest goes
+ * through first time. The 400 path stays as the backstop for a limit configured
+ * higher than the plan's.
+ *
+ * The size is the record's JSON in UTF-8 bytes, `objectID` included, which is how
+ * Algolia measures it. The default limit is the smallest Algolia plan's (10 KB);
+ * an application on a larger plan raises it.
+ *
+ * ## A document that does not encode
+ *
+ * The document schema is the read model's, and a document it cannot encode — or one
+ * that encodes to something other than a JSON object, which is all an Algolia
+ * record can be — is a defect in the read model, not a record the sink refuses. It
+ * dies, loudly, rather than being parked where nobody looks.
+ */
+import { type FeedChange, type FeedKey, SinkRejected } from '@kairos-es/feed';
+import { Effect, Schema } from 'effect';
+import type { NonEmptyReadonlyArray } from 'effect/Array';
+import type { BatchOperation } from './rest.js';
+/** The smallest Algolia plan's record size limit, in bytes. */
+export declare const DEFAULT_MAX_RECORD_BYTES = 10000;
+/** A record's size as Algolia measures it: its JSON, in UTF-8 bytes. */
+export declare const recordBytes: (record: Readonly<Record<string, unknown>>) => number;
+/** A batch ready to send: its operations, and the keys it carries. */
+export interface EncodedBatch {
+    readonly operations: ReadonlyArray<BatchOperation>;
+    readonly keys: ReadonlySet<FeedKey>;
+}
+/**
+ * Encode a batch, failing `SinkRejected` with EVERY oversized key when there is
+ * one; see the module doc.
+ */
+export declare const encodeBatch: <D, I>(doc: Schema.Codec<D, I>, maxRecordBytes: number, batch: NonEmptyReadonlyArray<FeedChange<D>>) => Effect.Effect<EncodedBatch, SinkRejected>;
+//# sourceMappingURL=records.d.ts.map

package/dist/dts-cjs/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC7E,OAAO,EAAgB,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAE5C,+DAA+D;AAC/D,eAAO,MAAM,wBAAwB,QAAS,CAAA;AAI9C,wEAAwE;AACxE,eAAO,MAAM,WAAW,GACtB,QAAQ,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KACxC,MAAoD,CAAA;AAEvD,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;IAClD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;CACpC;AAKD;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,CAAC,EAC9B,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EACvB,gBAAgB,MAAM,EACtB,OAAO,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAC1C,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,CAuCvC,CAAA"}

package/dist/dts-cjs/rest.d.ts

@@ -0,0 +1,215 @@
+/**
+ * The slice of Algolia's REST API this sink speaks, over `effect`'s own
+ * `HttpClient`.
+ *
+ * ## Why no SDK
+ *
+ * The surface the sink needs is eight calls — `batch`, `getTask`, `operationIndex`
+ * (copy and move), `deleteIndex`, `browse`, `listIndices`, and a settings read and
+ * write, which is how a resync target is made to exist and marked as its attempt's
+ * own — and each is one JSON request. Peering `algoliasearch` would bring a large
+ * non-Effect dependency for that, and its retries would sit underneath the feed
+ * driver's own supervision, which already owns retrying. Over `HttpClient` the
+ * sink is Effect-native, adds no peer beyond `effect`, and is faked in tests by a
+ * stub client with no network at all.
+ *
+ * ## Host failover
+ *
+ * The one piece of the SDK's transport kept here is the part the driver cannot do
+ * for itself: trying ANOTHER HOST. Algolia serves an application from
+ * `<appId>.algolia.net` and documents three fallbacks on separate infrastructure,
+ * `<appId>-1.algolianet.com` to `<appId>-3.algolianet.com`, to be tried when the
+ * first does not answer. A request that gets no answer (a transport failure, or no
+ * answer within its timeout), a 5xx, or a 1xx or 3xx — a status no call here
+ * expects, on which the official JavaScript client tries the next host too — is
+ * sent again at once to the next host, and only when every host it tried has
+ * failed is the call `SinkRetryable`, carrying the last host's failure. Without
+ * it, one unreachable host would hold the feed in the driver's back-off for as
+ * long as the host stayed down, with three healthy hosts unasked.
+ *
+ * - Hosts are STATEFUL, one state per client and so per sink, in the shape the
+ *   official JavaScript client gives them. A host that failed in one of those ways
+ *   is marked DOWN for two minutes, by `Clock`, and skipped by every call while it
+ *   is down; a host that answers is marked up again. Without that memory a primary
+ *   that drops packets would cost a whole timeout on EVERY call, each `getTask`
+ *   poll included, so a single wait for a task could spend its whole
+ *   `taskPolling.timeout` on the dead host. When every host is down, every host is
+ *   tried again, in order, rather than none.
+ * - The fallbacks are SHUFFLED, once, when the client is built, from Effect's
+ *   `Random`, so many workers do not all fail over onto the same host; the primary
+ *   goes first whenever it is up.
+ * - Each hand-off to the next host is logged at DEBUG level, with the call, the
+ *   host that failed, the host tried next and why. A call that lands after a
+ *   failover looks like any other, so that line is the only trace one leaves.
+ *   Hosts carry the application id, which is not a secret; the key travels in a
+ *   header and reaches no log.
+ * - Three timeouts, as the official client has: `connect`, `read` and `write`,
+ *   defaulting to its 2, 5 and 30 seconds. A read is a `GET` or a `browse`, and
+ *   every other call is a write. `HttpClient` does not show this module the moment
+ *   a connection is made, so one request's budget on one host is `connect` plus
+ *   `read`, or `connect` plus `write`, over the whole exchange. A transport that
+ *   enforces a connect timeout of its own fails sooner, and that failure fails
+ *   over the same way.
+ * - Every call uses the same list, reads included. The SDK sends reads to
+ *   `<appId>-dsn.algolia.net` first, which is the search-serving network; every
+ *   read here is an admin read (a task's status, a listing, a settings read, a
+ *   browse for reconcile) that wants the cluster the writes went to.
+ * - A 429 is NOT retried on another host: it is the application's rate limit or
+ *   quota, not a host's health (`classify.ts` owns which). Nor is any other 4xx,
+ *   which another host would answer the same.
+ * - A request can be sent more than once this way, and that is safe for the
+ *   reason every resend here is (`classify.ts`): every write is a full-record
+ *   replace, a delete, an index operation or a settings write, each of which
+ *   leaves the application the same however often it lands.
+ * - The worst case for one call is therefore its budget times the number of hosts
+ *   that are up when it starts.
+ * - An explicit `host` turns failover OFF: the caller has named the one place to
+ *   talk to (a proxy, a test double), and there are no fallbacks of it to guess.
+ *   That one host is never skipped, since every host being down tries it again.
+ *
+ * ## The admin key
+ *
+ * It is held as `Redacted` and unwrapped only into the request header, at the
+ * moment the request is built. Two things keep it out of anything printed: no
+ * failure this module produces carries the request or its headers — only the
+ * method, the path and Algolia's own message (`classify.ts`) — and every request
+ * runs with Algolia's key header added to the names `effect`'s `Headers` redact,
+ * so a request that is logged or traced by something further down shows the
+ * header as redacted.
+ *
+ * ## Not found
+ *
+ * Three of the calls meet a missing index as an ordinary outcome rather than a
+ * failure — dropping a leftover resync index that is not there, browsing an index
+ * that does not exist yet, reading the settings of an index that does not exist —
+ * so they answer a 404 as `Option.none()` instead of a `SinkHalted`. Every other
+ * call halts on a 404, with Algolia's own message in the reason. An index
+ * operation is one of those: Algolia documents a copy of a missing source as
+ * creating an empty destination, and a move of one as ignored without an error,
+ * so neither is a 404 (the sink's `publish` owns what that costs). A 404 is never
+ * failed over: another host would answer the same.
+ */
+import type { FeedKey } from '@kairos-es/feed';
+import { Duration, Effect, Option, Redacted } from 'effect';
+import { HttpClient, type HttpMethod } from 'effect/http';
+import { type AlgoliaFailure } from './classify.js';
+import { type AlgoliaAppId, type AlgoliaIndexName, AlgoliaTaskId } from './identifiers.js';
+/** Where and as whom the sink talks to Algolia. */
+export interface AlgoliaConnection {
+    readonly appId: AlgoliaAppId;
+    /** The admin API key. Never logged; see the module doc. */
+    readonly adminKey: Redacted.Redacted<string>;
+    /**
+     * ONE base URL to send every call to, with no failover. Leave it unset to talk
+     * to Algolia itself: `https://<appId>.algolia.net`, failing over to the three
+     * documented fallback hosts (see the module doc). Set it for a proxy or a test
+     * double, whose fallbacks there is no way to know.
+     */
+    readonly host?: string;
+    /**
+     * How long one request to one host may take before it counts as unanswered,
+     * that host is marked down, and the next is tried; see the module doc.
+     */
+    readonly timeouts?: AlgoliaTimeouts;
+}
+/**
+ * The three per-host timeouts, with the official JavaScript client's defaults. A
+ * request's budget on one host is `connect` plus `read` for a read, or `connect`
+ * plus `write` for a write; see the module doc for why they are added.
+ */
+export interface AlgoliaTimeouts {
+    /** Default 2 seconds. */
+    readonly connect?: Duration.Input;
+    /** For a `GET` or a `browse`. Default 5 seconds. */
+    readonly read?: Duration.Input;
+    /** For every other call. Default 30 seconds. */
+    readonly write?: Duration.Input;
+}
+/** One batch operation, as Algolia's `batch` takes it. Full-record writes only. */
+export type BatchOperation = {
+    readonly action: 'addObject';
+    readonly body: Readonly<Record<string, unknown>>;
+} | {
+    readonly action: 'deleteObject';
+    readonly body: {
+        readonly objectID: string;
+    };
+};
+/** What an index-level `operationIndex` call asks for. */
+export interface IndexOperation {
+    readonly operation: 'copy' | 'move';
+    readonly destination: AlgoliaIndexName;
+    readonly scope?: ReadonlyArray<'settings' | 'synonyms' | 'rules'>;
+}
+/** One page of a `browse`: the ids on it, and the cursor to the next, if any. */
+export interface BrowsePage {
+    readonly objectIDs: ReadonlyArray<string>;
+    readonly cursor: Option.Option<string>;
+}
+/** One page of `listIndices`: the index names on it, and whether more follow. */
+export interface IndexListPage {
+    readonly names: ReadonlyArray<string>;
+    readonly more: boolean;
+}
+/** One raw call: everything the typed calls below are built from. */
+export interface AlgoliaCall {
+    readonly method: HttpMethod.HttpMethod;
+    /** The path, already encoded: `/1/indexes/<name>/...`. */
+    readonly path: string;
+    readonly body?: unknown;
+    /** The keys the request carries, so a 400 naming one can be a rejection. */
+    readonly batchKeys?: ReadonlySet<FeedKey>;
+    /**
+     * A read whose method is not `GET` (a `browse`), so it gets the read timeout.
+     * Every `GET` is a read already.
+     */
+    readonly read?: true;
+}
+/**
+ * Where a task stands, as a caller that tolerates a missing index sees it: still
+ * running, published, or unanswerable because its index does not exist.
+ */
+export type AlgoliaTaskState = 'pending' | 'published' | 'indexMissing';
+/** The Algolia calls the sink makes. Every failure is already classified. */
+export interface AlgoliaRest {
+    /** A raw call; `Option.none()` on a 404. Exposed for the package's own tests. */
+    readonly call: (call: AlgoliaCall) => Effect.Effect<Option.Option<unknown>, AlgoliaFailure>;
+    readonly batch: (index: AlgoliaIndexName, operations: ReadonlyArray<BatchOperation>, batchKeys: ReadonlySet<FeedKey>) => Effect.Effect<AlgoliaTaskId, AlgoliaFailure>;
+    readonly taskPublished: (index: AlgoliaIndexName, taskID: AlgoliaTaskId) => Effect.Effect<boolean, AlgoliaFailure>;
+    /**
+     * `taskPublished`, as a state, with a 404 — Algolia's answer to `getTask` on an
+     * index that does not exist — as `'indexMissing'` rather than a halt, for a
+     * caller that has another way to learn what the task did.
+     */
+    readonly taskStateUnlessIndexMissing: (index: AlgoliaIndexName, taskID: AlgoliaTaskId) => Effect.Effect<AlgoliaTaskState, AlgoliaFailure>;
+    /**
+     * A copy or a move. Algolia answers a missing source with a task too: a copy
+     * creates an empty destination, and a move does nothing (see the module doc).
+     */
+    readonly operation: (source: AlgoliaIndexName, operation: IndexOperation) => Effect.Effect<AlgoliaTaskId, AlgoliaFailure>;
+    /** `Option.none()` when the index does not exist. */
+    readonly deleteIndex: (index: AlgoliaIndexName) => Effect.Effect<Option.Option<AlgoliaTaskId>, AlgoliaFailure>;
+    /** An index's settings; `Option.none()` when the index does not exist. */
+    readonly readSettings: (index: AlgoliaIndexName) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, AlgoliaFailure>;
+    /**
+     * A settings write of the settings named, and only those; a `null` resets one
+     * to its default. Algolia creates an index on a settings write, so this is also
+     * how an index is made to exist without a record.
+     */
+    readonly writeSettings: (index: AlgoliaIndexName, settings: Readonly<Record<string, unknown>>) => Effect.Effect<AlgoliaTaskId, AlgoliaFailure>;
+    /**
+     * One page of the application's index names, `page` counting from 0. Every
+     * index the key may see is listed, so a caller filters by name.
+     */
+    readonly listIndexNames: (page: number, hitsPerPage: number) => Effect.Effect<IndexListPage, AlgoliaFailure>;
+    /** A missing index browses as one empty last page. */
+    readonly browseObjectIds: (index: AlgoliaIndexName, cursor: Option.Option<string>, hitsPerPage: number) => Effect.Effect<BrowsePage, AlgoliaFailure>;
+}
+/** The path of an index, or of something under it. */
+export declare const indexPath: (index: AlgoliaIndexName, rest?: string) => string;
+/**
+ * Build the REST client over the `HttpClient` in context. The client is captured
+ * here, so every call the sink makes later needs nothing from its caller.
+ */
+export declare const makeAlgoliaRest: (connection: AlgoliaConnection) => Effect.Effect<AlgoliaRest, never, HttpClient.HttpClient>;
+//# sourceMappingURL=rest.d.ts.map

package/dist/dts-cjs/rest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.d.ts","sourceRoot":"","sources":["../../src/rest.ts"],"names":[],"mappings":"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"}

package/dist/dts-cjs/sink.d.ts

@@ -0,0 +1,220 @@
+/**
+ * `makeAlgoliaSink` — a `FeedSink` onto one served Algolia index, with both optional
+ * parts: a `FeedResync` built on Algolia's index copy and move, and a
+ * `FeedReconcile` built on `browse`.
+ *
+ * ## The steady state
+ *
+ * `apply` is ONE `batch` to the served index (`records.ts` owns what goes in it and
+ * which records are refused before it is sent), and its receipt is the index and
+ * the task Algolia returned. `confirm` polls `getTask` on that index until the task
+ * is `published`, which is the moment Algolia serves the batch — the moment the
+ * port's `confirm` promises. The poll runs on an Effect `Schedule`: it backs off
+ * from `taskPolling.initialDelay`, doubling to `taskPolling.maxDelay`, and no poll
+ * STARTS after `taskPolling.timeout` has passed since the wait began — the last
+ * wait is cut short to land on that deadline rather than overrun it by up to
+ * `maxDelay`. A task still unpublished then is a `SinkRetryable`: the driver
+ * resends the batch, which is safe, rather than waiting on a task without bound.
+ * A poll that has started can still outlast the deadline by its own request
+ * timeout (`rest.ts`). A `Schedule` rather than a hand-written loop because the
+ * curve is then one declared value, run under the `Clock`, so a test's
+ * `TestClock` drives it like any other wait.
+ *
+ * ## Resync: a fresh index, swapped in whole
+ *
+ * Algolia's `operationIndex` move replaces the destination index atomically, which
+ * is exactly the swap `FeedResync` asks for. So:
+ *
+ * - `begin(generation)` names the target `<served>__kairos_g<generation>_<attempt>`,
+ *   where `<attempt>` is drawn from Effect's `Random` afresh on every call, and
+ *   then COPIES the served index into it with `scope` limited to settings, synonyms
+ *   and rules. The fresh index then ranks and matches exactly as the served one does,
+ *   and holds none of its records. A served index that has never been written has no
+ *   scope to copy, and that is not an error: `begin` reads the served index's
+ *   settings first and makes no copy when it does not exist. Algolia would copy a
+ *   missing source as an empty index, but the copy's task is polled on the served
+ *   index, and `getTask` on an index that does not exist answers 404, so skipping
+ *   the copy is what keeps that wait off a missing index. The name is the ATTEMPT's, not the
+ *   generation's, because two workers can be resyncing one generation at once —
+ *   one of them having lost its lease without knowing it yet — and a target they
+ *   shared is one either could publish half-built; `runFeedSync.ts` owns the
+ *   argument. Random rather than the lease holder's id, because the port hands a
+ *   sink no lease, and a draw needs none.
+ * - `begin` then MARKS the target as its attempt's own: it writes the target's
+ *   `userData` setting as whatever the copy brought from the served index, plus one
+ *   key, `kairosResyncAttempt`, holding the attempt. Algolia creates an index on a
+ *   settings write, so this is also what makes the target EXIST whatever the copy
+ *   did — over a served index never written, and for a rebuild that loads nothing.
+ *   The mark is what `publish` checks, below. It goes in `userData` because that
+ *   is the one setting Algolia keeps for the application's own data and reads
+ *   nothing from, so the mark changes nothing about how the target ranks or
+ *   matches.
+ * - `begin` first drops every OTHER resync index of this served index it can list,
+ *   whatever its generation, settings snapshots included. Each was left by an attempt that will never publish
+ *   it now — one that crashed, one abandoned because the generation moved, or one
+ *   a worker that lost its lease is still loading — and every such index holds
+ *   records against the application's quota; an ephemeral feed, whose generation
+ *   is new on every boot, would otherwise leave one behind per interrupted boot.
+ *   Dropping the one a stale worker is loading is also what makes that worker's
+ *   `publish` fail rather than land. Listing needs the key to carry Algolia's
+ *   `listIndexes` ACL, and the sink REQUIRES it rather than skipping the drop when
+ *   it is missing: without the drop, a stale worker's `publish` could land and
+ *   abandoned targets would pile up. A key without it is refused like any other
+ *   4xx, a `SinkHalted` at the start of the resync, before the copy, so nothing is
+ *   created.
+ * - `load` is `apply`, against the target. It does not check the mark: that would
+ *   cost a settings read per page and still race the drop, and `publish` is where
+ *   a target is served, so `publish` is where the check has to hold.
+ * - `publish` reads the target's settings and refuses, `SinkRetryable`, a target
+ *   that is missing or does not carry this attempt's mark; only then does it move
+ *   the target over the served index and wait on the move's task. Then it reads the
+ *   SERVED index's settings and reports success only if the served index now
+ *   carries this attempt's mark, which only this move could have put there;
+ *   otherwise it fails `SinkRetryable`. That read is the authority, and the
+ *   move's own answer is not: Algolia ignores a move of a missing index "without
+ *   returning an error", so a target dropped after the check gets a task back, the
+ *   task publishes, and the served index still holds the old copy. Taking that for
+ *   success would let the driver save its cursor at the new generation over an
+ *   index that never got it. For the same
+ *   reason a 404 on the move's task poll — `getTask` on an index that no longer
+ *   exists — ends the wait rather than halting, and the read decides. An empty rebuild
+ *   is a move like any other, of a target that holds no records, and it leaves the
+ *   served index empty. A target can go missing before its publish in two ways: a
+ *   newer `begin` dropped it, or something moved it over the served index first.
+ *   Only the second could ever land a half-built target, and the per-attempt name
+ *   is what rules it out: the one `publish` that names this target is this
+ *   attempt's own, so no other worker's can move it. What is left is the first,
+ *   and it has a second form, which is why the mark exists: a worker that lost its
+ *   lease without knowing it goes on LOADING into its dropped target, and Algolia
+ *   creates an index on a batch write, so the target comes back holding the stale
+ *   worker's later pages alone. A name alone cannot tell that index from the one
+ *   `begin` made; the missing mark can, since only `begin` writes it. Either way
+ *   `publish` fails `SinkRetryable` and the resync starts again. It never touches
+ *   the served index on that account, since the worker that finds its target gone
+ *   is the one most likely to have lost the lease. An index a stale load brought
+ *   back is left where it is, and the next `begin` drops it with the rest.
+ * - Before it marks the target, `begin` takes a SNAPSHOT of the served index's
+ *   settings into `<target>__settings`, a settings-scoped copy, or an empty
+ *   settings write when the served index does not exist. After the move has landed,
+ *   `publish` takes the mark back off the served index by copying the snapshot's
+ *   settings over it, scoped to settings, then drops the snapshot. The drop is a
+ *   best effort of its own, and runs whether or not the restore landed. A copy is
+ *   the one write that REMOVES a setting: Algolia stores a `null` written to `userData` as
+ *   the value `null`, and `{}` or `resetToDefault` leave an empty object, so a
+ *   rebuild of an index that had no `userData` would otherwise leave one behind.
+ *   The snapshot is a second copy of the same served index's settings, made just
+ *   after the target's, so the restore changes nothing else unless those settings
+ *   changed between the two copies, when it applies the later ones. Its scope is
+ *   SETTINGS ONLY, and must stay so: the snapshot holds no synonyms or rules, so a
+ *   wider restore would wipe the served index's. Records are untouched, and so are the
+ *   served index's replicas (see below). A mark an earlier failed restore left on the
+ *   served index is taken off the snapshot as it is made, so it cannot come
+ *   back; when it was all the `userData` there was, a settings write is the only
+ *   way to take it off, and the `null` Algolia stores for it is what remains.
+ *   The move and the restore are two steps, so a search index briefly carries the
+ *   key, which nothing reads. The restore is BEST-EFFORT: the swap has
+ *   already landed, and failing `publish` now would tell the driver it had not. A
+ *   snapshot that is gone (a newer `begin` dropped it) is not copied, since a copy
+ *   from a missing index changes nothing and its task never publishes; the mark
+ *   then stays until the next rebuild's restore, and a warning says so. One that
+ *   goes between that check and the copy is reported the same way, once the wait
+ *   on the copy's task ends: at the first poll, if `getTask` on the missing index
+ *   answers 404 as above, and at `pollTimeout` if it does not. The swap has landed
+ *   by then, so the worst cost is a `publish` that returns late, not a wrong one.
+ *
+ * Check-then-move leaves no gap a stale load can use: the only worker that loads
+ * into this target is the one publishing it, and its loads have finished. A drop
+ * between the check and the move makes the move a no-op, which the read of the
+ * served index after it turns into a `SinkRetryable`, as above. Taking the mark
+ * off the TARGET before the move would open one: a drop between that write and
+ * the move, and the write itself would bring back an empty target for the move to
+ * land.
+ *
+ * Replicas are the one thing this does not settle by construction: a copy with
+ * `scope` is not documented to carry a primary's replicas to the target, nor a
+ * move over a primary, or the restore's settings-scoped copy over it, to keep
+ * them. Measured against a real application, all three leave them where they
+ * were, and the package's live test checks it after `publish` when credentials
+ * are present.
+ *
+ * ## Reconcile
+ *
+ * `listKeys` browses the served index page by page, retrieving `objectID` and nothing
+ * else, so listing a large index costs the ids and not the records.
+ *
+ * ## The key's ACLs
+ *
+ * A scoped key needs `addObject` (record writes, and the copy and the move),
+ * `deleteObject`, `deleteIndex` (the drop), `settings` (the mark check),
+ * `editSettings` (writing and removing the mark), `browse` (reconcile) and
+ * `listIndexes` (the drop's listing), on the served index and its resync indices.
+ * The README states the same set, ACL by ACL, for a consumer.
+ *
+ * ## What the sink holds
+ *
+ * Nothing between calls but its options and the captured `HttpClient`: no queue, no
+ * cursor, no buffered batch. Every piece of progress is the driver's, which is what
+ * lets a resent batch and a restarted resync be safe.
+ */
+import { type FeedSink, type Generation, type SinkName } from '@kairos-es/feed';
+import { Duration, Effect, type Schema } from 'effect';
+import type { HttpClient } from 'effect/http';
+import { AlgoliaIndexName, type AlgoliaTaskId } from './identifiers.js';
+import { type AlgoliaConnection } from './rest.js';
+/** What `apply` and `load` return: the index the batch went to, and its task. */
+export interface AlgoliaReceipt {
+    readonly index: AlgoliaIndexName;
+    readonly taskID: AlgoliaTaskId;
+}
+/** How `confirm`, and every wait on an index operation, polls `getTask`. */
+export interface AlgoliaTaskPolling {
+    /** The first wait between polls. Default 100 ms. */
+    readonly initialDelay?: Duration.Input;
+    /** The cap the wait doubles up to. Default 2 seconds. */
+    readonly maxDelay?: Duration.Input;
+    /** How long to poll before giving up, retryably. Default 60 seconds. */
+    readonly timeout?: Duration.Input;
+}
+/** Options for {@link makeAlgoliaSink}. */
+export interface AlgoliaSinkOptions<D, I> extends AlgoliaConnection {
+    /** The sink's name: one cursor per feed and sink. */
+    readonly name: SinkName;
+    /** The SERVED index: the one search reads. */
+    readonly index: AlgoliaIndexName;
+    /** The document's schema; a record is its encoded form plus `objectID`. */
+    readonly doc: Schema.Codec<D, I>;
+    /**
+     * Records larger than this, in bytes of their JSON with `objectID`, are refused
+     * (parked) before sending. Default 10 000 bytes — {@link DEFAULT_MAX_RECORD_BYTES}
+     * — which is the record size limit of Algolia's smallest plan, so the default
+     * refuses nothing Algolia would take on any plan.
+     *
+     * On a plan with a larger limit, raise this to that limit (100 000 for a plan
+     * whose records may be 100 KB, say); records between the two are then sent
+     * rather than parked. Set it no higher than the plan's own limit: a record over
+     * the plan's limit that passes this check costs a round trip, which Algolia
+     * refuses whole, before it is parked by the answer naming it.
+     */
+    readonly maxRecordBytes?: number;
+    readonly taskPolling?: AlgoliaTaskPolling;
+    /** Ids per `browse` page when listing keys. Default 1 000, Algolia's maximum. */
+    readonly browsePageSize?: number;
+}
+/**
+ * The resync target's name for one attempt at `generation`. PACKAGE-INTERNAL, and
+ * kept off the entry point deliberately: `attempt` is what `begin` draws for each
+ * call, so a real target's name is the one `begin` returns, and a consumer has no
+ * use for composing one.
+ *
+ * It does not check `attempt`. Every caller here passes lower-case base-36
+ * digits, which `begin` draws and the tests write by hand, and that shape is all
+ * `resyncGenerationOf` below recognises: a suffix of any other shape would name an
+ * index that `begin` never drops and `publish` never accepts.
+ */
+export declare const resyncIndexName: (served: AlgoliaIndexName, generation: Generation, attempt: string) => AlgoliaIndexName;
+/**
+ * Build an Algolia sink over the `HttpClient` in context; see the module doc.
+ * Dies at once on options out of range.
+ */
+export declare const makeAlgoliaSink: <D, I>(options: AlgoliaSinkOptions<D, I>) => Effect.Effect<FeedSink<D, AlgoliaReceipt>, never, HttpClient.HttpClient>;
+//# sourceMappingURL=sink.d.ts.map

package/dist/dts-cjs/sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../../src/sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6JG;AACH,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,UAAU,EAGf,KAAK,QAAQ,EAEd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAEL,QAAQ,EACR,MAAM,EAIN,KAAK,MAAM,EAEZ,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AAEpE,OAAO,EAAE,KAAK,iBAAiB,EAAmB,MAAM,QAAQ,CAAA;AAEhE,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAC/B;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAA;IACtC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAA;IAClC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAA;CAClC;AAED,2CAA2C;AAC3C,MAAM,WAAW,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,iBAAiB;IACjE,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;IACzC,iFAAiF;IACjF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,gBAAgB,EACxB,YAAY,UAAU,EACtB,SAAS,MAAM,KACd,gBACmE,CAAA;AA2JtE;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,EAClC,SAAS,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,KAChC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAwUtE,CAAA"}