@loams/client 0.1.0 → 0.1.1

package/dist/runtime/call.js

@@ -11,7 +11,8 @@
 // - turns whatever is thrown into the typed `LoamsError` hierarchy, so a
 //   caller branches on `reason` and never on a message.
 import { Code, createClient, } from '@connectrpc/connect';
-import { LoamsError, TokenExpiredError, toLoamsError } from './errors.js';
+import { DeadlineExceededError, InvalidArgumentError, LoamsError, TokenExpiredError, toLoamsError, } from './errors.js';
+import { TOKEN_PREFIX } from './consistency.js';
 import { DEFAULT_MAX_RETRIES, backoffMs, shouldRetry, sleep } from './retry.js';
 import { uuidv7 } from './uuidv7.js';
 /**
@@ -39,7 +40,8 @@ export async function callWithRetry(request, send, plan, rpc) {
                 attempt -= 1;
                 continue;
             }
-            if (!shouldRetry(error, plan.retrySafe, attempt, plan.maxRetries)) {
+            if (plan.expired?.() === true ||
+                !shouldRetry(error, plan.retrySafe, attempt, plan.maxRetries)) {
                 throw error;
             }
             await sleep(backoffMs(attempt), plan.signal);
@@ -97,10 +99,61 @@ const IDEMPOTENCY_KEY = 'idempotencyKey';
  */
 function resolveSession(options, clientSession) {
     const session = options?.session;
-    if (session === undefined || session === false) {
+    if (session === false) {
         return undefined;
     }
-    return session === true ? clientSession : session;
+    if (session === undefined || session === true) {
+        return clientSession;
+    }
+    return session;
+}
+/** Whether a response string is something other than a consistency token. */
+function isForeignToken(value) {
+    return !value.startsWith(TOKEN_PREFIX);
+}
+/** The unary deadline when neither the client nor the call sets one (R12). */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** The response fields a consistency token is read from (R4, SDKP §2.1). */
+const TOKEN_FIELDS = ['consistencyToken', 'token', 'readToken'];
+/** The response header a consistency token is read from (R4). */
+export const CONSISTENCY_TOKEN_HEADER = 'loams-consistency-token';
+/**
+ * The packages whose `namespace` field is a Loams namespace (R11) and whose
+ * `consistency` field reads at a consistency token (R4). Other packages have
+ * fields of the same name that mean something else: `loams.live.v1`'s
+ * `CreateAppRequest.namespace` is free text naming an app's environment, and
+ * must never be filled from, or refused for lack of, the client's default.
+ */
+export const APP_PACKAGES = new Set([
+    'loams.collection.v1',
+    'loams.graph.v1',
+    'loams.sql.v1',
+    'loams.stream.v1',
+]);
+/**
+ * The packages whose reads take the session's token as `at_least` (R4,
+ * SDKP-17): collections and SQL. A graph's token names one graph's stream and
+ * a Graph read refuses any other, so graph reads never take the session's.
+ */
+export const SESSION_PACKAGES = new Set(['loams.collection.v1', 'loams.sql.v1']);
+/** How a request's `consistency` message spells "at least this token". Both
+ * shapes in the protos are covered: a plain `at_least` field
+ * (`loams.collection.v1.Consistency`) and an `at_least` arm of a oneof
+ * (`loams.graph.v1.Consistency`). */
+function atLeastOf(input) {
+    const field = input.field.consistency;
+    if (field === undefined || field.fieldKind !== 'message') {
+        return undefined;
+    }
+    const atLeast = field.message.field.atLeast;
+    if (atLeast === undefined || atLeast.fieldKind !== 'scalar') {
+        return undefined;
+    }
+    const oneof = atLeast.oneof;
+    if (oneof === undefined) {
+        return (token) => ({ atLeast: token });
+    }
+    return (token) => ({ [oneof.localName]: { case: 'atLeast', value: token } });
 }
 /**
  * The client's call path: a generated `CallBinding` plus a request becomes a
@@ -113,13 +166,19 @@ export class CallInvoker {
     consistency;
     clients = new Map();
     descriptors = new Map();
-    /** Whether a call's request schema declares `idempotency_key`, per RPC. */
-    keyed = new Map();
-    constructor(transport, tokenSource, maxRetries, consistency) {
+    /** What each RPC's request schema declares, per RPC. */
+    shapes = new Map();
+    defaults;
+    constructor(transport, tokenSource, maxRetries, consistency, defaults = {}) {
         this.transport = transport;
         this.tokenSource = tokenSource;
         this.maxRetries = maxRetries;
         this.consistency = consistency;
+        this.defaults = defaults;
+    }
+    /** The client's default namespace, if it has one (R11). */
+    get namespace() {
+        return this.defaults.namespace;
     }
     /**
      * A module's Connect client, built once from the service descriptor
@@ -137,18 +196,79 @@ export class CallInvoker {
             // from the object a caller happened to build. A caller who omits an
             // `optional` field still gets a key, and `MutateRequest` (which has one)
             // is never confused with `DeployRequest` (which does not).
-            this.keyed.set(`${service}/${method.name}`, method.input.field[IDEMPOTENCY_KEY] !== undefined);
+            const namespace = method.input.field.namespace;
+            const pkg = descriptor.file.proto.package ?? '';
+            const app = APP_PACKAGES.has(pkg);
+            this.shapes.set(`${service}/${method.name}`, {
+                keyed: method.input.field[IDEMPOTENCY_KEY] !== undefined,
+                namespaced: app &&
+                    namespace !== undefined &&
+                    namespace.fieldKind === 'scalar' &&
+                    namespace.oneof === undefined,
+                atLeast: SESSION_PACKAGES.has(pkg) ? atLeastOf(method.input) : undefined,
+            });
         }
         this.clients.set(service, createClient(descriptor, this.transport));
     }
+    /** What this call's request message declares. */
+    shape(binding) {
+        return (this.shapes.get(`${binding.service}/${binding.method}`) ?? {
+            keyed: false,
+            namespaced: false,
+            atLeast: undefined,
+        });
+    }
     /** Whether this call's request message declares an `idempotency_key`. */
     takesIdempotencyKey(binding) {
-        return this.keyed.get(`${binding.service}/${binding.method}`) ?? false;
+        return this.shape(binding).keyed;
+    }
+    /**
+     * The request as it goes out: the default namespace filled in (R11) and the
+     * session's token set as `consistency.at_least` when the caller left
+     * `consistency` unset (R4). A request the caller set either on is left as
+     * written: an explicit argument always wins.
+     */
+    prepare(binding, request, consistency) {
+        if (typeof request !== 'object' || request === null) {
+            return request;
+        }
+        const shape = this.shape(binding);
+        let message = request;
+        if (shape.namespaced) {
+            const given = message.namespace;
+            if (typeof given !== 'string' || given === '') {
+                const fallback = this.defaults.namespace;
+                if (fallback === undefined || fallback === '') {
+                    throw new InvalidArgumentError(`${binding.rpc} needs a namespace: pass one, or give the client a default namespace`, {
+                        code: Code.InvalidArgument,
+                        reason: 'namespace_required',
+                        rpc: binding.rpc,
+                        metadata: { field: 'namespace' },
+                    });
+                }
+                message = { ...message, namespace: fallback };
+            }
+        }
+        if (consistency !== undefined && shape.atLeast !== undefined && message.consistency === undefined) {
+            message = { ...message, consistency: shape.atLeast(consistency) };
+        }
+        return message;
+    }
+    /** The deadline a unary call runs under, in milliseconds, or undefined. */
+    unaryTimeout(options) {
+        const ms = options.timeoutMs ?? this.defaults.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        return ms > 0 ? ms : undefined;
     }
     /** The connect-es method a binding names, or a clear internal error. */
     method(binding) {
         const client = this.clients.get(binding.service);
-        const method = client?.[binding.name];
+        // The connect-es client is keyed by the RPC's own local name
+        // (`createNamespace`), not by the facade name (`create`): the two differ
+        // whenever `FacadeOptions.name` renames a call, which every app module does.
+        const descriptor = this.descriptors.get(binding.service);
+        const local = descriptor?.methods.find((candidate) => candidate.name === binding.method)?.localName ??
+            binding.name;
+        const method = client?.[local];
         if (typeof method !== 'function') {
             throw new LoamsError(`the generated client for ${binding.service} has no method ${binding.name}`, { code: Code.Internal, rpc: binding.rpc });
         }
@@ -156,35 +276,97 @@ export class CallInvoker {
     }
     /** One unary call: the whole runtime contract, applied to one binding. */
     async unary(binding, request, options = {}) {
-        const { request: keyed, keyed: hasKey } = withIdempotencyKey(request, options.idempotencyKey, this.takesIdempotencyKey(binding));
+        const session = resolveSession(options.consistency, this.consistency);
+        // An explicit token wins; otherwise the session's, which is what makes a
+        // session read-your-writes rather than record it and never send it (R4).
+        // R4 (SDKP-17): one token per proto package, so a collection write's token
+        // never becomes a graph read's `at_least`.
+        const consistency = options.consistency?.token ?? session?.current(binding.package);
+        const prepared = this.prepare(binding, request, consistency);
+        const { request: keyed, keyed: hasKey } = withIdempotencyKey(prepared, options.idempotencyKey, this.takesIdempotencyKey(binding));
         const maxRetries = options.maxRetries ?? this.maxRetries;
         // D610: a `safe` call always retries; a mutation retries once it carries an
         // idempotency key, which `withIdempotencyKey` has just decided.
         const retrySafe = options.retrySafe ?? (binding.retry === 'safe' || hasKey);
-        const session = resolveSession(options.consistency, this.consistency);
-        // An explicit token wins; otherwise the session's, which is what makes
-        // `consistency: { session: true }` read-your-writes rather than record it
-        // and never send it (R4).
-        const consistency = options.consistency?.token ?? session?.current();
         const method = this.method(binding);
-        const result = (await callWithRetry(keyed, async () => method(keyed, { ...options, headers: await this.headers(options, consistency) }), {
-            retrySafe,
-            maxRetries,
-            signal: options.signal,
-            onRefresh: this.tokenSource?.refresh?.bind(this.tokenSource),
-        }, binding.rpc));
-        this.recordConsistency(session, result);
-        return result;
+        // R12: one budget for the whole call, retries included. The SDK runs its
+        // own timer rather than trusting the transport's, so the budget holds over
+        // every transport, and so "the client ran out" is told apart from a
+        // server's `deadline_exceeded`, which may be retried.
+        const timeoutMs = this.unaryTimeout(options);
+        const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+        const controller = new AbortController();
+        let expired = false;
+        const onCallerAbort = () => controller.abort(options.signal?.reason);
+        if (options.signal?.aborted === true) {
+            controller.abort(options.signal.reason);
+        }
+        else {
+            options.signal?.addEventListener('abort', onCallerAbort, { once: true });
+        }
+        const timer = timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                expired = true;
+                controller.abort(new Error('client deadline exceeded'));
+            }, timeoutMs);
+        let headerToken;
+        const onHeader = (headers) => {
+            // A stub transport may answer without headers at all.
+            headerToken = headers?.get?.(CONSISTENCY_TOKEN_HEADER) ?? undefined;
+            if (headers !== undefined) {
+                options.onHeader?.(headers);
+            }
+        };
+        try {
+            const result = (await callWithRetry(keyed, async () => method(keyed, {
+                ...options,
+                signal: controller.signal,
+                ...(deadline === undefined
+                    ? {}
+                    : { timeoutMs: Math.max(1, deadline - Date.now()) }),
+                onHeader,
+                headers: await this.headers(options, consistency, this.shape(binding).atLeast === undefined),
+            }), {
+                retrySafe,
+                maxRetries,
+                signal: controller.signal,
+                onRefresh: this.tokenSource?.refresh?.bind(this.tokenSource),
+                expired: () => expired,
+            }, binding.rpc));
+            this.recordConsistency(session, result, headerToken, binding.package);
+            return result;
+        }
+        catch (thrown) {
+            if (expired) {
+                throw new DeadlineExceededError(`${binding.rpc} did not answer within the client's ${timeoutMs} ms deadline`, {
+                    code: Code.DeadlineExceeded,
+                    reason: 'client_deadline_exceeded',
+                    rpc: binding.rpc,
+                    metadata: { timeout_ms: String(timeoutMs) },
+                    cause: thrown,
+                });
+            }
+            throw toLoamsError(thrown, binding.rpc);
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            options.signal?.removeEventListener('abort', onCallerAbort);
+        }
     }
     /** The headers a call carries: the caller's, plus the bearer and the
      * consistency token the runtime owns. */
-    async headers(options, consistency) {
+    async headers(options, consistency, asHeader = true) {
         const headers = { ...options.headers };
         const bearer = await this.tokenSource?.token();
         if (bearer !== undefined) {
             headers.authorization = `Bearer ${bearer}`;
         }
-        if (consistency !== undefined) {
+        // A request with a `consistency` field carries the token there (R4); one
+        // without carries it as a header, which is all such an RPC can read.
+        if (consistency !== undefined && asHeader) {
             headers['loams-consistency'] = consistency;
         }
         return headers;
@@ -200,7 +382,9 @@ export class CallInvoker {
     stream(binding, request, options = {}) {
         const method = this.method(binding);
         const session = resolveSession(options.consistency, this.consistency);
-        const consistency = options.consistency?.token ?? session?.current();
+        const consistency = options.consistency?.token ?? session?.current(binding.package);
+        const prepared = this.prepare(binding, request, consistency);
+        const asHeader = this.shape(binding).atLeast === undefined;
         const self = this;
         const refresh = this.tokenSource?.refresh?.bind(this.tokenSource);
         // Synchronous, because `loams.live.watch(...)` has to hand back an
@@ -211,8 +395,8 @@ export class CallInvoker {
             let refreshed = false;
             let yielded = false;
             for (;;) {
-                const headers = await self.headers(options, consistency);
-                const source = self.mapped(streamOf(method(request, { ...options, headers })), binding.rpc);
+                const headers = await self.headers(options, consistency, asHeader);
+                const source = self.mapped(streamOf(method(prepared, { ...options, headers })), binding.rpc);
                 try {
                     for await (const message of source) {
                         yielded = true;
@@ -253,21 +437,39 @@ export class CallInvoker {
         };
         return invoke();
     }
-    /** Merges the consistency token a write answered with into the session. */
-    recordConsistency(session, result) {
-        if (session === undefined || result === undefined) {
+    /** Merges every consistency token a response carried into the session:
+     * `consistency_token`, `token` and `read_token`, and the
+     * `loams-consistency-token` header (R4, SDKP §2.1). */
+    recordConsistency(session, result, headerToken, scope) {
+        if (session === undefined) {
             return;
         }
-        const token = result.consistencyToken;
-        try {
-            session.record(typeof token === 'string' && token !== '' ? token : undefined);
+        const tokens = [];
+        for (const field of TOKEN_FIELDS) {
+            const value = result?.[field];
+            if (typeof value === 'string' && value !== '') {
+                tokens.push(value);
+            }
+        }
+        if (headerToken !== undefined && headerToken !== '') {
+            tokens.push(headerToken);
         }
-        catch {
-            // The RPC already succeeded. A token the session cannot merge — the
-            // encoding is still opaque, see `ConsistencySession` — must not turn a
-            // committed write into a thrown error, because a caller that retries on
-            // that error performs the write twice. `ConsistencySession.conflicts`
-            // counts it instead.
+        for (const token of tokens) {
+            // `token` is a common field name; only a `v1:` string is a consistency
+            // token, and anything else (a page token, a bearer) is not the
+            // session's business.
+            if (isForeignToken(token)) {
+                continue;
+            }
+            try {
+                session.record(token, scope);
+            }
+            catch {
+                // The RPC already succeeded. A token the session cannot parse must not
+                // turn a committed write into a thrown error, because a caller that
+                // retries on that error performs the write twice. The session counts
+                // it (`ConsistencySession.rejected`) instead.
+            }
         }
     }
 }

package/dist/runtime/consistency.d.ts

@@ -1,22 +1,76 @@
 /** The prefix every token carries (§44 §7.4). */
 export declare const TOKEN_PREFIX = "v1:";
-/** Whether a string looks like a consistency token. */
+/** Whether a string looks like a consistency token (the prefix only). */
 export declare function isConsistencyToken(value: string): boolean;
+/** One item of a token: the next offset after a write, for one partition. */
+export interface TokenPosition {
+    readonly stream: bigint;
+    readonly partition: number;
+    readonly offset: bigint;
+}
+/**
+ * A parsed consistency token: `parse`, `toString`, `merge`, `equals`.
+ *
+ * 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 declare class ConsistencyToken {
+    readonly positions: readonly TokenPosition[];
+    private constructor();
+    /** The token that names nothing: `v1:`. */
+    static empty(): ConsistencyToken;
+    /** A token from its items, in the order given. */
+    static of(positions: readonly TokenPosition[]): ConsistencyToken;
+    /** 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: string): ConsistencyToken;
+    /** Whether `text` parses. */
+    static isValid(text: string): boolean;
+    /** Sorted by `(stream, partition)`, one item per pair, the max offset kept. */
+    normalized(): ConsistencyToken;
+    /** Both tokens' offsets; a pair both name keeps the larger. Normalised. */
+    merge(other: ConsistencyToken | string): ConsistencyToken;
+    /** The offset for `(stream, partition)`, the max if listed twice. */
+    offset(stream: bigint | number, partition: number): bigint | undefined;
+    /** Whether the two tokens name the same positions (after normalising). */
+    equals(other: ConsistencyToken | string): boolean;
+    /** Whether the token names nothing. */
+    get isEmpty(): boolean;
+    /** The text form, `v1:` plus the items joined by `,`, in this token's order. */
+    toString(): string;
+    toJSON(): string;
+}
 /**
- * A session's consistency token.
+ * 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.
  *
- * 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.
+ * `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 declare class ConsistencySession {
     #private;
-    /** The token to attach to the next read. */
-    current(): string | undefined;
-    /** Folds a token the server returned in. */
-    record(token: string | undefined): void;
-    /** How many unmergeable pairs the session has seen. */
+    /** The token to attach to the next read in `scope`, or undefined. */
+    current(scope?: string): string | undefined;
+    /** The merged token of `scope`, parsed. */
+    token(scope?: string): ConsistencyToken | undefined;
+    /** The scopes the session holds a token for. */
+    scopes(): string[];
+    /** Folds a token the server returned, in `scope`, in. Throws
+     * `InvalidArgumentError` on a malformed token, after counting it. */
+    record(token: string | ConsistencyToken | undefined, scope?: string): void;
+    /** How many tokens the session could not parse. */
+    get rejected(): number;
+    /** @deprecated The old name of `rejected`, from before tokens merged. */
     get conflicts(): number;
-    /** 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(): void;
 }