@loams/client 0.1.0 → 0.1.1

package/dist/runtime/consistency.js

@@ -1,68 +1,234 @@
-// Consistency tokens (design §44 §7.4, D609; runtime contract R4).
+// Consistency tokens (design §44 §7.4, D609; runtime contract R4 as amended
+// by SDKP §2.1).
 //
-// A write answers with a `consistency_token`; a read accepts one, so a caller
-// that just wrote can read its own write. Threading those by hand is the
-// caller's job today. The session store is the alternative §44 §7.4 asks for:
-// off by default, and when a call opts in, every response's token is merged
-// into the session and attached to later reads.
+// A write answers with a token; a read accepts one, so a caller that just
+// wrote can read its own write. The encoding is the server's
+// (`crates/loams-collection/src/token.rs`):
 //
-// **The token's encoding is not in the protos yet.** §05 §5 defines the
-// semantics (offsets per stream and partition, `STRONG` as the default,
-// `EVENTUAL`, `AT_LEAST{token}`) and API1's write paths carry it as an opaque
-// `v1:` string; §44 §7.4 says it merges by "max offset per stream and
-// partition", which needs the encoding to be parsed. Until that lands this
-// store keeps the token it was given, refuses to merge two different tokens
-// into a wrong one, and says so — a silently-wrong consistency token reads
-// stale data, which is worse than an error.
-import { LoamsError } from './errors.js';
+//   v1:s<stream>/p<partition>@<offset>,s<stream>/p<partition>@<offset>,…
+//
+// Each item is "the next offset after the write" for one `(stream, partition)`.
+// Merging two tokens keeps, per pair, the larger offset: a read held to the
+// merge waits for both writes. Every number is canonical decimal (no sign, no
+// leading zeros), so a token has exactly one spelling, and a malformed token is
+// `invalid_argument` here, before any network call.
+//
+// The session store is off by default. With `sessionConsistency: true` every
+// token a response carries is merged into it, and every read whose request has
+// a `consistency` field is sent `at_least = session` when the caller left the
+// field unset.
+//
+// Offsets are `bigint`: an offset is a `u64` on the server, and a `number`
+// silently rounds above 2^53, which would make a read wait for the wrong
+// position.
 import { Code } from '@connectrpc/connect';
+import { InvalidArgumentError } from './errors.js';
 /** The prefix every token carries (§44 §7.4). */
 export const TOKEN_PREFIX = 'v1:';
-/** Whether a string looks like a consistency token. */
+/** Whether a string looks like a consistency token (the prefix only). */
 export function isConsistencyToken(value) {
-    return value.startsWith(TOKEN_PREFIX) && value.length > TOKEN_PREFIX.length;
+    return value.startsWith(TOKEN_PREFIX);
+}
+const U32_MAX = 0xffffffffn;
+const U64_MAX = 0xffffffffffffffffn;
+/** A decimal `u64` with no sign and no leading zeros (except `"0"`). */
+function canonical(text, max) {
+    if (text === '' || !/^[0-9]+$/.test(text) || (text.length > 1 && text.startsWith('0'))) {
+        return undefined;
+    }
+    const value = BigInt(text);
+    return value <= max ? value : undefined;
+}
+/** `s<stream>/p<partition>@<offset>`. */
+function parseItem(item) {
+    const match = /^s([^/]*)\/p([^@]*)@(.*)$/.exec(item);
+    if (match === null) {
+        return undefined;
+    }
+    const stream = canonical(match[1], U64_MAX);
+    const partition = canonical(match[2], U32_MAX);
+    const offset = canonical(match[3], U64_MAX);
+    if (stream === undefined || partition === undefined || offset === undefined) {
+        return undefined;
+    }
+    return { stream, partition: Number(partition), offset };
+}
+function compare(a, b) {
+    if (a.stream !== b.stream) {
+        return a.stream < b.stream ? -1 : 1;
+    }
+    if (a.partition !== b.partition) {
+        return a.partition - b.partition;
+    }
+    if (a.offset !== b.offset) {
+        return a.offset < b.offset ? -1 : 1;
+    }
+    return 0;
 }
 /**
- * A session's consistency token.
+ * A parsed consistency token: `parse`, `toString`, `merge`, `equals`.
  *
- * Merging is deliberately conservative while the encoding is opaque: the store
- * keeps what it has, and a second, different token is a conflict the caller has
- * to resolve, not something to merge blindly.
+ * Immutable. `merge` returns a new token, normalised (sorted by stream and
+ * partition, one item per pair, the max offset kept), which is exactly what
+ * `ConsistencyToken::merge` on the server produces, so the two print the same.
+ */
+export class ConsistencyToken {
+    positions;
+    constructor(positions) {
+        this.positions = positions;
+    }
+    /** The token that names nothing: `v1:`. */
+    static empty() {
+        return new ConsistencyToken([]);
+    }
+    /** A token from its items, in the order given. */
+    static of(positions) {
+        return new ConsistencyToken([...positions]);
+    }
+    /** Parses the text form, or throws `InvalidArgumentError`. The items are
+     * kept in the order given, as the server's parser keeps them. */
+    static parse(text) {
+        const invalid = () => new InvalidArgumentError(`invalid consistency token ${JSON.stringify(text)}`, {
+            code: Code.InvalidArgument,
+            reason: 'invalid_consistency_token',
+            metadata: { field: 'consistency_token' },
+        });
+        if (!text.startsWith(TOKEN_PREFIX)) {
+            throw invalid();
+        }
+        const body = text.slice(TOKEN_PREFIX.length);
+        if (body === '') {
+            return ConsistencyToken.empty();
+        }
+        const positions = [];
+        for (const item of body.split(',')) {
+            const position = parseItem(item);
+            if (position === undefined) {
+                throw invalid();
+            }
+            positions.push(position);
+        }
+        return new ConsistencyToken(positions);
+    }
+    /** Whether `text` parses. */
+    static isValid(text) {
+        try {
+            ConsistencyToken.parse(text);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Sorted by `(stream, partition)`, one item per pair, the max offset kept. */
+    normalized() {
+        const sorted = [...this.positions].sort(compare);
+        const items = [];
+        for (const item of sorted) {
+            const last = items[items.length - 1];
+            if (last !== undefined && last.stream === item.stream && last.partition === item.partition) {
+                items[items.length - 1] = item;
+            }
+            else {
+                items.push(item);
+            }
+        }
+        return new ConsistencyToken(items);
+    }
+    /** Both tokens' offsets; a pair both name keeps the larger. Normalised. */
+    merge(other) {
+        const right = typeof other === 'string' ? ConsistencyToken.parse(other) : other;
+        return new ConsistencyToken([...this.positions, ...right.positions]).normalized();
+    }
+    /** The offset for `(stream, partition)`, the max if listed twice. */
+    offset(stream, partition) {
+        const s = BigInt(stream);
+        let found;
+        for (const item of this.positions) {
+            if (item.stream === s && item.partition === partition) {
+                found = found === undefined || item.offset > found ? item.offset : found;
+            }
+        }
+        return found;
+    }
+    /** Whether the two tokens name the same positions (after normalising). */
+    equals(other) {
+        const right = typeof other === 'string' ? ConsistencyToken.parse(other) : other;
+        return this.normalized().toString() === right.normalized().toString();
+    }
+    /** Whether the token names nothing. */
+    get isEmpty() {
+        return this.positions.length === 0;
+    }
+    /** The text form, `v1:` plus the items joined by `,`, in this token's order. */
+    toString() {
+        return (TOKEN_PREFIX +
+            this.positions
+                .map((item) => `s${item.stream}/p${item.partition}@${item.offset}`)
+                .join(','));
+    }
+    toJSON() {
+        return this.toString();
+    }
+}
+/**
+ * A session's consistency tokens: every token a response carried, merged, kept
+ * **per proto package** (R4, SDKP-17).
+ *
+ * A Graph read refuses a token naming another package's stream, so a
+ * collection write's token must never become a graph read's `at_least`: the
+ * session holds one merged token per scope, and the call path passes the
+ * call's package as the scope. A caller using the store directly may leave the
+ * scope out, which is one shared scope.
+ *
+ * `record` folds a token in; `current` is the scope's merge, as text. A token
+ * that does not parse is counted in `rejected` and otherwise ignored: the write
+ * that answered with it has already happened, and turning a committed write
+ * into a thrown error invites a caller to retry it.
  */
 export class ConsistencySession {
-    #token;
-    /** How many times two different tokens met. Surfaced so the limitation is
-     * visible rather than silent. */
-    #conflicts = 0;
-    /** The token to attach to the next read. */
-    current() {
-        return this.#token;
-    }
-    /** Folds a token the server returned in. */
-    record(token) {
+    #tokens = new Map();
+    #rejected = 0;
+    /** The token to attach to the next read in `scope`, or undefined. */
+    current(scope = '') {
+        return this.#tokens.get(scope)?.toString();
+    }
+    /** The merged token of `scope`, parsed. */
+    token(scope = '') {
+        return this.#tokens.get(scope);
+    }
+    /** The scopes the session holds a token for. */
+    scopes() {
+        return [...this.#tokens.keys()];
+    }
+    /** Folds a token the server returned, in `scope`, in. Throws
+     * `InvalidArgumentError` on a malformed token, after counting it. */
+    record(token, scope = '') {
         if (token === undefined || token === '') {
             return;
         }
-        if (!isConsistencyToken(token)) {
-            this.#conflicts += 1;
-            throw new LoamsError(`not a consistency token: ${token}`, { code: Code.Internal });
+        let parsed;
+        try {
+            parsed = typeof token === 'string' ? ConsistencyToken.parse(token) : token;
         }
-        if (this.#token === undefined || this.#token === token) {
-            this.#token = token;
-            return;
+        catch (error) {
+            this.#rejected += 1;
+            throw error;
         }
-        this.#conflicts += 1;
-        throw new LoamsError('two different consistency tokens met and the encoding cannot merge them yet; ' +
-            'the session keeps the first. Merging by stream and partition offset arrives with ' +
-            'the write paths that carry offsets (§44 §7.4, D609).', { code: Code.FailedPrecondition });
+        const held = this.#tokens.get(scope);
+        this.#tokens.set(scope, held === undefined ? parsed.normalized() : held.merge(parsed));
+    }
+    /** How many tokens the session could not parse. */
+    get rejected() {
+        return this.#rejected;
     }
-    /** How many unmergeable pairs the session has seen. */
+    /** @deprecated The old name of `rejected`, from before tokens merged. */
     get conflicts() {
-        return this.#conflicts;
+        return this.#rejected;
     }
-    /** Forgets the token, so the next read is not held to it. */
+    /** Forgets every token, so the next read is not held to one. */
     clear() {
-        this.#token = undefined;
-        this.#conflicts = 0;
+        this.#tokens.clear();
+        this.#rejected = 0;
     }
 }

package/dist/runtime/errors.d.ts

@@ -1,5 +1,13 @@
 import { Code, ConnectError } from '@connectrpc/connect';
 import { type Reason } from '../gen/facade.js';
+/**
+ * Reasons the SDK raises itself, without a server answer (SDKP §2.1, R12 and
+ * R13). They are registered in `docs/api/reasons.md` as client-side, and are
+ * kept here as well so the SDK does not depend on when that registry lands.
+ */
+export declare const CLIENT_REASONS: readonly ["client_deadline_exceeded", "batch_partially_applied"];
+/** A reason the SDK raises itself. */
+export type ClientReason = (typeof CLIENT_REASONS)[number];
 /** What every Loams failure carries. */
 export declare class LoamsError extends Error {
     /** The Connect code, the canonical classification. */
@@ -7,7 +15,7 @@ export declare class LoamsError extends Error {
     /** The stable cause, when the server sent an `ErrorInfo`. Undefined means
      * the failure came from below the API (a socket, a timeout, a CORS
      * rejection), not from a Loams service. */
-    readonly reason: Reason | undefined;
+    readonly reason: Reason | ClientReason | undefined;
     /** Structured context the server sent. Never secrets. */
     readonly metadata: Readonly<Record<string, string>>;
     /** A short next step in the caller's locale, when the server sent one. */
@@ -19,7 +27,7 @@ export declare class LoamsError extends Error {
     readonly unknownReason: string | undefined;
     constructor(message: string, init: {
         code: Code;
-        reason?: Reason;
+        reason?: Reason | ClientReason;
         unknownReason?: string;
         metadata?: Record<string, string>;
         hint?: string;
@@ -69,6 +77,25 @@ export declare class FeatureNotInVariantError extends UnimplementedError {
         variant?: string;
     });
 }
+/**
+ * A `documents.writeBatch` that stopped at a failed chunk (runtime contract
+ * R13). The chunks before it are applied and stay applied; `token` is their
+ * merged consistency token, so a caller can read what did land, and `cause` is
+ * the failed chunk's own error.
+ */
+export declare class BatchError extends LoamsError {
+    /** How many chunks were applied before the failure. */
+    readonly chunksApplied: number;
+    /** How many documents those chunks carried. */
+    readonly rowsApplied: number;
+    /** The merged token of the applied chunks, if any carried one. */
+    readonly token: string | undefined;
+    constructor(message: string, init: ConstructorParameters<typeof LoamsError>[1] & {
+        chunksApplied: number;
+        rowsApplied: number;
+        token?: string;
+    });
+}
 /** A token the server rejected as expired: `unauthenticated` with reason
  * `token_expired`. The runtime refreshes once and retries once (D608, R1). */
 export declare class TokenExpiredError extends UnauthenticatedError {

package/dist/runtime/errors.js

@@ -13,6 +13,12 @@ import { REASONS } from '../gen/facade.js';
  * union does not have is a server newer than this SDK, and is surfaced rather
  * than dropped. */
 const KNOWN_REASONS = new Set(REASONS);
+/**
+ * Reasons the SDK raises itself, without a server answer (SDKP §2.1, R12 and
+ * R13). They are registered in `docs/api/reasons.md` as client-side, and are
+ * kept here as well so the SDK does not depend on when that registry lands.
+ */
+export const CLIENT_REASONS = ['client_deadline_exceeded', 'batch_partially_applied'];
 /** What every Loams failure carries. */
 export class LoamsError extends Error {
     /** The Connect code, the canonical classification. */
@@ -84,6 +90,26 @@ export class FeatureNotInVariantError extends UnimplementedError {
         this.variant = init.variant;
     }
 }
+/**
+ * A `documents.writeBatch` that stopped at a failed chunk (runtime contract
+ * R13). The chunks before it are applied and stay applied; `token` is their
+ * merged consistency token, so a caller can read what did land, and `cause` is
+ * the failed chunk's own error.
+ */
+export class BatchError extends LoamsError {
+    /** How many chunks were applied before the failure. */
+    chunksApplied;
+    /** How many documents those chunks carried. */
+    rowsApplied;
+    /** The merged token of the applied chunks, if any carried one. */
+    token;
+    constructor(message, init) {
+        super(message, init);
+        this.chunksApplied = init.chunksApplied;
+        this.rowsApplied = init.rowsApplied;
+        this.token = init.token;
+    }
+}
 /** A token the server rejected as expired: `unauthenticated` with reason
  * `token_expired`. The runtime refreshes once and retries once (D608, R1). */
 export class TokenExpiredError extends UnauthenticatedError {

package/dist/runtime/pagination.js

@@ -25,13 +25,15 @@ export async function* paginate(binding, fetch, request, options = {}) {
             ...request,
             ...(pageToken === undefined ? {} : { [pageTokenField]: pageToken }),
         }, options));
-        const items = page[pagination.items];
+        // The binding spells the field as the proto does (`service_accounts`);
+        // a decoded message has it in TypeScript case (`serviceAccounts`).
+        const items = page[pagination.items] ?? page[camelCase(pagination.items)];
         if (Array.isArray(items)) {
             for (const item of items) {
                 yield item;
             }
         }
-        const next = page[pagination.nextPageToken];
+        const next = page[pagination.nextPageToken] ?? page[camelCase(pagination.nextPageToken)];
         if (typeof next !== 'string' || next === '') {
             return;
         }
@@ -45,3 +47,7 @@ export function pageFields(binding) {
     }
     return { pageSizeField: 'pageSize', pageTokenField: 'pageToken' };
 }
+/** `snake_case` to `lowerCamelCase`, as protobuf-es names a field. */
+function camelCase(name) {
+    return name.replace(/_([a-z0-9])/g, (_match, letter) => letter.toUpperCase());
+}

package/dist/runtime/subscribe.d.ts

@@ -0,0 +1,37 @@
+/** The first and the largest pause after an empty fetch. */
+export declare const SUBSCRIBE_MIN_BACKOFF_MS = 100;
+export declare const SUBSCRIBE_MAX_BACKOFF_MS = 1000;
+/** Where a subscription starts and how much each fetch asks for. */
+export interface SubscribeRequest {
+    namespace?: string;
+    stream: string;
+    partition?: number;
+    /** The first offset to read; default 0. */
+    fromOffset?: bigint | number;
+    maxRecords?: number;
+    maxBytes?: number;
+    /** A server long poll per fetch, when the server offers it (P0c). */
+    maxWaitMs?: number;
+}
+/** One record, as far as the loop needs to know it. */
+export interface OffsetRecord {
+    readonly offset: bigint | number | string;
+}
+/** One `Fetch`. */
+export type RecordFetcher<R extends OffsetRecord> = (request: Record<string, unknown>, options?: {
+    signal?: AbortSignal;
+}) => Promise<{
+    records?: readonly R[];
+} | undefined>;
+/** A running subscription: an async iterable that knows where it is. */
+export interface Subscription<R> extends AsyncIterableIterator<R> {
+    /** The next offset to read. */
+    readonly offset: bigint;
+    /** Stops the loop; the same as `return()`. */
+    cancel(): void;
+}
+/** Starts a subscription over `fetch`. Nothing is sent until the first
+ * `next()`. */
+export declare function subscribe<R extends OffsetRecord>(fetch: RecordFetcher<R>, request: SubscribeRequest, options?: {
+    signal?: AbortSignal;
+}): Subscription<R>;

package/dist/runtime/subscribe.js

@@ -0,0 +1,128 @@
+// `streams.subscribe` (runtime contract R14, SDKP §2.5 and SDKP-2).
+//
+//   const sub = loams.streams.subscribe({ stream: 'events', partition: 0, fromOffset: 1n });
+//   for await (const record of sub) {
+//     handle(record);
+//     if (done) break;            // cancels the loop
+//   }
+//   resumeLater(sub.offset);       // the next offset to read
+//
+// A client loop over unary `Fetch` rather than a server stream, so it works on
+// every transport (Connect-unary included) and through every proxy:
+//
+// - The next offset is the last record's offset + 1.
+// - An empty fetch backs off 100 ms, doubling, up to 1 s, and the backoff
+//   resets when a record arrives. When the caller passes `maxWaitMs`, the
+//   server long-polls instead and the backoff only applies when it answers
+//   empty at its deadline.
+// - `offset` is always the next offset to read, so a caller can stop and
+//   resume without losing or repeating a record.
+// - Breaking out of `for await`, calling `return()`, or aborting `signal`
+//   stops the loop; no further fetch is sent.
+//
+// A fetch that fails is retried by the call path as any `safe` call is; a
+// failure that outlasts the retries ends the iteration with that error, and
+// `offset` still says where to resume.
+import { sleep } from './retry.js';
+/** The first and the largest pause after an empty fetch. */
+export const SUBSCRIBE_MIN_BACKOFF_MS = 100;
+export const SUBSCRIBE_MAX_BACKOFF_MS = 1_000;
+function asBigInt(value) {
+    if (value === undefined) {
+        return 0n;
+    }
+    return typeof value === 'bigint' ? value : BigInt(value);
+}
+/** Starts a subscription over `fetch`. Nothing is sent until the first
+ * `next()`. */
+export function subscribe(fetch, request, options = {}) {
+    let offset = asBigInt(request.fromOffset);
+    let buffer = [];
+    let backoff = SUBSCRIBE_MIN_BACKOFF_MS;
+    let done = false;
+    const controller = new AbortController();
+    const onAbort = () => {
+        done = true;
+        controller.abort(options.signal?.reason);
+    };
+    if (options.signal?.aborted === true) {
+        onAbort();
+    }
+    else {
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+    }
+    const finish = () => {
+        done = true;
+        options.signal?.removeEventListener('abort', onAbort);
+        if (!controller.signal.aborted) {
+            controller.abort();
+        }
+        return { done: true, value: undefined };
+    };
+    const fetchRequest = () => {
+        const out = {
+            stream: request.stream,
+            partition: request.partition ?? 0,
+            offset,
+        };
+        for (const key of ['namespace', 'maxRecords', 'maxBytes', 'maxWaitMs']) {
+            if (request[key] !== undefined) {
+                out[key] = request[key];
+            }
+        }
+        return out;
+    };
+    const subscription = {
+        get offset() {
+            return offset;
+        },
+        cancel() {
+            finish();
+        },
+        async next() {
+            while (!done) {
+                const record = buffer.shift();
+                if (record !== undefined) {
+                    offset = asBigInt(record.offset) + 1n;
+                    return { done: false, value: record };
+                }
+                let answer;
+                try {
+                    answer = await fetch(fetchRequest(), { signal: controller.signal });
+                }
+                catch (error) {
+                    if (done) {
+                        return finish();
+                    }
+                    finish();
+                    throw error;
+                }
+                if (done) {
+                    return finish();
+                }
+                // A record below the next offset is one already yielded (a server that
+                // answers from a segment start); skipping it keeps resume exact.
+                buffer = (answer?.records ?? []).filter((r) => asBigInt(r.offset) >= offset);
+                if (buffer.length > 0) {
+                    backoff = SUBSCRIBE_MIN_BACKOFF_MS;
+                    continue;
+                }
+                try {
+                    await sleep(backoff, controller.signal);
+                }
+                catch {
+                    return finish();
+                }
+                backoff = Math.min(backoff * 2, SUBSCRIBE_MAX_BACKOFF_MS);
+            }
+            return finish();
+        },
+        return() {
+            return Promise.resolve(finish());
+        },
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+    return subscription;
+}

package/dist/vendor/proto/collection-v1.d.ts

@@ -0,0 +1,3 @@
+export * from './gen/loams/collection/v1/collection_pb.js';
+export * from './gen/loams/collection/v1/document_pb.js';
+export * from './gen/loams/collection/v1/query_pb.js';

package/dist/vendor/proto/collection-v1.js

@@ -0,0 +1,7 @@
+// `loams.collection.v1` as one module: the package spans three proto files
+// (`collection`, `document`, `query`), and the SDK facade imports a package's
+// types from one specifier (`@loams/proto/collection-v1`), as `./admin.ts`
+// does for `loams.admin.v1`. Each file stays importable on its own path too.
+export * from './gen/loams/collection/v1/collection_pb.js';
+export * from './gen/loams/collection/v1/document_pb.js';
+export * from './gen/loams/collection/v1/query_pb.js';