@eleven-am/golem-client 0.0.0-stage → 0.1.1

package/dist/merge.js

@@ -0,0 +1,62 @@
+import { GolemProtocolError } from './errors.js';
+export const EMPTY_MERGE_STATE = { markers: [], changes: [] };
+const DIGITS = /^[0-9]+$/;
+export function parseVersion(raw) {
+    if (!DIGITS.test(raw)) {
+        throw new GolemProtocolError(`row version is not an unsigned integer: ${JSON.stringify(raw)}`);
+    }
+    return BigInt(raw);
+}
+export function decideUpdate(cached, event) {
+    if (cached === undefined) {
+        return 'invalidate';
+    }
+    return event > cached ? 'patch' : 'ignore';
+}
+export function noteChange(state, key, receivedAt) {
+    return { markers: state.markers, changes: [...state.changes, { key, receivedAt }] };
+}
+export function applyRemoval(state, removal, cached) {
+    const marker = { key: removal.key, version: removal.version, receivedAt: removal.receivedAt };
+    return {
+        remove: cached !== undefined && cached <= removal.version,
+        state: { markers: [...state.markers, marker], changes: state.changes },
+    };
+}
+export function resolveResponse(state, response) {
+    const rows = new Map();
+    for (const [key, version] of response.rows) {
+        rows.set(key, decideRow(state, response, key, version));
+    }
+    return {
+        rows,
+        refetch: droppedChangedKey(state, response),
+        state: {
+            markers: state.markers.filter((marker) => marker.receivedAt >= response.issuedAt),
+            changes: state.changes.filter((change) => change.receivedAt >= response.issuedAt),
+        },
+    };
+}
+function decideRow(state, response, key, version) {
+    for (const marker of state.markers) {
+        if (marker.key === key && marker.receivedAt >= response.issuedAt && version <= marker.version) {
+            return 'drop';
+        }
+    }
+    const cached = response.cached.get(key);
+    return cached !== undefined && cached > version ? 'keep-cached' : 'apply';
+}
+function droppedChangedKey(state, response) {
+    for (const change of state.changes) {
+        if (change.receivedAt < response.issuedAt || response.rows.has(change.key)) {
+            continue;
+        }
+        if (!removalExplains(state, change)) {
+            return true;
+        }
+    }
+    return false;
+}
+function removalExplains(state, change) {
+    return state.markers.some((marker) => marker.key === change.key && marker.receivedAt >= change.receivedAt);
+}

package/dist/mutations.d.ts

@@ -0,0 +1,20 @@
+import type { DocumentNode } from 'graphql';
+import type { QueryClient } from '@tanstack/query-core';
+import type { ClientManifest } from './manifest.js';
+import type { ExecuteRequest } from './transport.js';
+export interface MutationTransport {
+    execute<T = unknown>(request: ExecuteRequest): Promise<T>;
+}
+export interface MutationsOptions {
+    readonly queryClient: QueryClient;
+    readonly transport: MutationTransport;
+    readonly manifest: ClientManifest;
+}
+export declare class Mutations {
+    private readonly client;
+    private readonly transport;
+    private readonly manifest;
+    constructor(options: MutationsOptions);
+    execute<T = unknown>(document: DocumentNode | string, variables?: Readonly<Record<string, unknown>>, signal?: AbortSignal): Promise<T>;
+    private invalidateCommitted;
+}

package/dist/mutations.js

@@ -0,0 +1,42 @@
+import { analyzeMutation } from './analysis.js';
+import { GolemCommitUnknownError, GolemPartialCommitError } from './errors.js';
+import { readMeta } from './live.js';
+export class Mutations {
+    client;
+    transport;
+    manifest;
+    constructor(options) {
+        this.client = options.queryClient;
+        this.transport = options.transport;
+        this.manifest = options.manifest;
+    }
+    async execute(document, variables, signal) {
+        const analysis = analyzeMutation(document, this.manifest);
+        let data;
+        try {
+            data = await this.transport.execute({ query: analysis.query, variables, signal });
+        }
+        catch (error) {
+            if (error instanceof GolemPartialCommitError || error instanceof GolemCommitUnknownError) {
+                this.invalidateCommitted(analysis);
+            }
+            throw error;
+        }
+        this.invalidateCommitted(analysis);
+        return data;
+    }
+    invalidateCommitted(analysis) {
+        const unscoped = analysis.roots.some((root) => root.models.length === 0);
+        if (unscoped) {
+            void this.client.invalidateQueries({ predicate: (query) => readMeta(query) !== undefined });
+            return;
+        }
+        const models = analysis.roots.flatMap((root) => root.models);
+        if (models.length === 0) {
+            return;
+        }
+        void this.client.invalidateQueries({
+            predicate: (query) => readMeta(query)?.analysis.streams.some((stream) => models.includes(stream.model)) === true,
+        });
+    }
+}

package/dist/pagination.d.ts

@@ -0,0 +1,32 @@
+import { type DocumentAnalysis } from './analysis.js';
+import type { ClientManifest } from './manifest.js';
+export type Cursor = Readonly<Record<string, unknown>>;
+export type TakeSource = {
+    readonly variable: string;
+    readonly fallback?: number;
+} | {
+    readonly literal: number;
+};
+export interface PageSpec {
+    readonly root: string;
+    readonly model: string;
+    readonly selector: string;
+    readonly primaryKey: ReadonlyArray<string>;
+    readonly take: TakeSource;
+    readonly continuation: string;
+}
+export interface InfiniteQueryPlan {
+    readonly spec: PageSpec;
+    readonly take: number;
+    readonly initialPageParam: Cursor | null;
+    getNextPageParam(lastPage: unknown): Cursor | undefined;
+    requestFor(pageParam: Cursor | null): {
+        readonly query: string;
+        readonly variables: Readonly<Record<string, unknown>>;
+    };
+}
+export declare const CURSOR_VARIABLE = "golemCursor";
+export declare const SKIP_VARIABLE = "golemSkip";
+export declare function pageSpec(analysis: DocumentAnalysis, manifest: ClientManifest): PageSpec;
+export declare function cursorOf(spec: PageSpec, row: Readonly<Record<string, unknown>>): Cursor;
+export declare function golemInfiniteQuery(analysis: DocumentAnalysis, variables: Readonly<Record<string, unknown>>, manifest: ClientManifest): InfiniteQueryPlan;

package/dist/pagination.js

@@ -0,0 +1,133 @@
+import { Kind, OperationTypeNode, print } from 'graphql';
+import { operationOf } from './analysis.js';
+import { GolemConfigurationError, GolemDocumentError, GolemProtocolError } from './errors.js';
+const SKIP_PAST_CURSOR = 1;
+function variableOf(field, name) {
+    const value = field.arguments?.find((candidate) => candidate.name.value === name)?.value;
+    return value?.kind === Kind.VARIABLE ? value.name.value : undefined;
+}
+function takeOf(field, operation) {
+    const value = field.arguments?.find((candidate) => candidate.name.value === 'take')?.value;
+    if (value?.kind === Kind.VARIABLE) {
+        const name = value.name.value;
+        const fallback = operation.variableDefinitions?.find((definition) => definition.variable.name.value === name)?.defaultValue;
+        return fallback?.kind === Kind.INT ? { variable: name, fallback: Number(fallback.value) } : { variable: name };
+    }
+    if (value?.kind === Kind.INT) {
+        return { literal: Number(value.value) };
+    }
+    return undefined;
+}
+export const CURSOR_VARIABLE = 'golemCursor';
+export const SKIP_VARIABLE = 'golemSkip';
+const nameNode = (value) => ({ kind: Kind.NAME, value });
+function continuationOf(document, operation, field, uniqueInput) {
+    const taken = operation.variableDefinitions?.find((definition) => definition.variable.name.value === CURSOR_VARIABLE || definition.variable.name.value === SKIP_VARIABLE);
+    if (taken !== undefined) {
+        throw new GolemDocumentError(`the variable ${taken.variable.name.value} belongs to the client; an infinite query adds it to every page after the first`);
+    }
+    const paged = {
+        ...field,
+        arguments: [
+            ...(field.arguments ?? []),
+            { kind: Kind.ARGUMENT, name: nameNode('cursor'), value: { kind: Kind.VARIABLE, name: nameNode(CURSOR_VARIABLE) } },
+            { kind: Kind.ARGUMENT, name: nameNode('skip'), value: { kind: Kind.VARIABLE, name: nameNode(SKIP_VARIABLE) } },
+        ],
+    };
+    const widened = {
+        ...operation,
+        variableDefinitions: [
+            ...(operation.variableDefinitions ?? []),
+            { kind: Kind.VARIABLE_DEFINITION, variable: { kind: Kind.VARIABLE, name: nameNode(CURSOR_VARIABLE) }, type: { kind: Kind.NAMED_TYPE, name: nameNode(uniqueInput) } },
+            { kind: Kind.VARIABLE_DEFINITION, variable: { kind: Kind.VARIABLE, name: nameNode(SKIP_VARIABLE) }, type: { kind: Kind.NAMED_TYPE, name: nameNode('Int') } },
+        ],
+        selectionSet: { ...operation.selectionSet, selections: operation.selectionSet.selections.map((selection) => (selection === field ? paged : selection)) },
+    };
+    return print({ ...document, definitions: document.definitions.map((definition) => (definition === operation ? widened : definition)) });
+}
+export function pageSpec(analysis, manifest) {
+    const operation = operationOf(analysis.document, OperationTypeNode.QUERY);
+    const named = (field, name) => field.arguments?.some((candidate) => candidate.name.value === name) === true;
+    for (const selection of operation.selectionSet.selections) {
+        if (selection.kind === Kind.FIELD && (named(selection, 'cursor') || named(selection, 'skip'))) {
+            throw new GolemDocumentError(`${selection.name.value} sets cursor or skip itself; an infinite query builds both from the last row of the previous page`);
+        }
+    }
+    const roots = operation.selectionSet.selections.filter((selection) => selection.kind === Kind.FIELD && named(selection, 'take'));
+    const [field] = roots;
+    if (field === undefined || roots.length !== 1) {
+        throw new GolemDocumentError(`an infinite query needs exactly one root field with a take argument; found ${roots.length}`);
+    }
+    const name = field.name.value;
+    const root = manifest.roots[name];
+    const modelName = root?.models[0];
+    const model = modelName === undefined ? undefined : manifest.models[modelName];
+    if (root === undefined || root.kind !== 'generated' || root.shape !== 'rows' || modelName === undefined || model === undefined) {
+        throw new GolemDocumentError(`${name} cannot be paged: only a generated list root has a cursor`);
+    }
+    if (model.uniqueInput === null) {
+        throw new GolemDocumentError(`${name} cannot be paged: the manifest names no unique input for ${modelName}`);
+    }
+    const take = takeOf(field, operation);
+    if (take === undefined) {
+        throw new GolemDocumentError(`${name} must give take a variable or an integer`);
+    }
+    return {
+        root: (field.alias ?? field.name).value,
+        model: modelName,
+        selector: model.cursorSelector,
+        primaryKey: model.primaryKey,
+        take,
+        continuation: continuationOf(analysis.document, operation, field, model.uniqueInput),
+    };
+}
+export function cursorOf(spec, row) {
+    const parts = {};
+    for (const field of spec.primaryKey) {
+        const value = row[field];
+        if (value === undefined || value === null) {
+            throw new GolemProtocolError(`a ${spec.model} row on the page lacks ${field}, so no cursor can be built from it`);
+        }
+        parts[field] = value;
+    }
+    const [only] = spec.primaryKey;
+    return { [spec.selector]: spec.primaryKey.length === 1 && only !== undefined ? parts[only] : parts };
+}
+function pageRows(spec, page) {
+    const rows = typeof page === 'object' && page !== null ? page[spec.root] : undefined;
+    if (!Array.isArray(rows)) {
+        throw new GolemProtocolError(`a page carried no ${spec.root} list`);
+    }
+    return rows;
+}
+function takeValue(spec, variables) {
+    const value = 'literal' in spec.take ? spec.take.literal : (variables[spec.take.variable] ?? spec.take.fallback);
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        throw new GolemConfigurationError(`an infinite query needs a positive integer take; got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+export function golemInfiniteQuery(analysis, variables, manifest) {
+    const spec = pageSpec(analysis, manifest);
+    for (const owned of [CURSOR_VARIABLE, SKIP_VARIABLE]) {
+        if (owned in variables) {
+            throw new GolemConfigurationError(`the variable ${owned} belongs to the client; an infinite query builds it from the last row of the previous page`);
+        }
+    }
+    const take = takeValue(spec, variables);
+    return {
+        spec,
+        take,
+        initialPageParam: null,
+        getNextPageParam(lastPage) {
+            const rows = pageRows(spec, lastPage);
+            const last = rows.at(-1);
+            return rows.length < take || last === undefined ? undefined : cursorOf(spec, last);
+        },
+        requestFor(pageParam) {
+            return pageParam === null
+                ? { query: analysis.query, variables }
+                : { query: spec.continuation, variables: { ...variables, [CURSOR_VARIABLE]: pageParam, [SKIP_VARIABLE]: SKIP_PAST_CURSOR } };
+        },
+    };
+}

package/dist/patcher.d.ts

@@ -0,0 +1,26 @@
+import type { ClientManifest } from './manifest.js';
+import { type Version } from './merge.js';
+export type RowKey = string;
+export type Occurrences = ReadonlyArray<string>;
+export type EventIdentity = string | number | Readonly<Record<string, unknown>>;
+export interface Eviction {
+    readonly data: unknown;
+    readonly held: ReadonlySet<RowKey>;
+    readonly evicted: boolean;
+}
+export declare class Patcher {
+    private readonly manifest;
+    constructor(manifest: ClientManifest);
+    keyOf(typename: string, source: Readonly<Record<string, unknown>>): RowKey | undefined;
+    eventKey(model: string, id: EventIdentity, entity: Readonly<Record<string, unknown>> | null): RowKey;
+    versions(data: unknown, within?: Occurrences): Map<RowKey, Version>;
+    patch(data: unknown, key: RowKey, entity: Readonly<Record<string, unknown>>, within?: Occurrences): unknown;
+    remove(data: unknown, keys: ReadonlySet<RowKey>, nullableRoots: ReadonlySet<string>, within?: Occurrences): Eviction;
+    private overlay;
+    private holdsRows;
+    private identify;
+    private each;
+    private nullableSlot;
+    private vacate;
+    private rewrite;
+}

package/dist/patcher.js

@@ -0,0 +1,186 @@
+import { GolemProtocolError } from './errors.js';
+import { parseVersion } from './merge.js';
+const REMOVED = Symbol('removed');
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const childPath = (path, name) => (path === '' ? name : `${path}.${name}`);
+export class Patcher {
+    manifest;
+    constructor(manifest) {
+        this.manifest = manifest;
+    }
+    keyOf(typename, source) {
+        const model = this.manifest.models[typename];
+        if (model === undefined) {
+            return undefined;
+        }
+        const parts = [];
+        for (const field of model.primaryKey) {
+            const value = source[field];
+            if (typeof value !== 'string' && typeof value !== 'number') {
+                return undefined;
+            }
+            parts.push(String(value));
+        }
+        return `${typename}:${parts.join('\u0001')}`;
+    }
+    eventKey(model, id, entity) {
+        const described = this.manifest.models[model];
+        if (described === undefined) {
+            throw new GolemProtocolError(`an event named the unknown model ${model}`);
+        }
+        if (entity !== null) {
+            const key = this.keyOf(model, entity);
+            if (key !== undefined) {
+                return key;
+            }
+        }
+        const [field] = described.primaryKey;
+        const source = typeof id === 'string' || typeof id === 'number' ? (described.primaryKey.length === 1 && field !== undefined ? { [field]: id } : undefined) : id;
+        const key = source === undefined ? undefined : this.keyOf(model, source);
+        if (key === undefined) {
+            throw new GolemProtocolError(`an event for ${model} carries an identity that does not hold ${described.primaryKey.join(', ')}`);
+        }
+        return key;
+    }
+    versions(data, within) {
+        const found = new Map();
+        this.each(data, within, (key, row) => {
+            const raw = row._version;
+            if (typeof raw !== 'string') {
+                return;
+            }
+            const version = parseVersion(raw);
+            const known = found.get(key);
+            if (known === undefined || version > known) {
+                found.set(key, version);
+            }
+        });
+        return found;
+    }
+    patch(data, key, entity, within) {
+        return this.rewrite(data, within, (candidate, candidateKey) => {
+            if (candidateKey !== key) {
+                return candidate;
+            }
+            return this.overlay(candidate, entity);
+        });
+    }
+    remove(data, keys, nullableRoots, within) {
+        const slots = { nullableRoots, held: new Set(), evicted: false };
+        const next = this.rewrite(data, within, (candidate, candidateKey) => (keys.has(candidateKey) ? REMOVED : candidate), slots);
+        return { data: next, held: slots.held, evicted: slots.evicted };
+    }
+    overlay(row, source) {
+        const typename = row.__typename;
+        const relations = typeof typename === 'string' ? this.manifest.models[typename]?.relations ?? {} : {};
+        const computed = typeof typename === 'string' ? this.manifest.models[typename]?.computed ?? {} : {};
+        const complete = Object.keys(row).every((name) => name in source || name === '__typename' || name in relations || (computed[name]?.length ?? 0) > 0 || this.holdsRows(row[name]));
+        let next;
+        for (const [name, value] of Object.entries(source)) {
+            if (name === '_version' && !complete) {
+                continue;
+            }
+            if (name === '__typename' || !(name in row) || name in relations || row[name] === value) {
+                continue;
+            }
+            if (this.holdsRows(value) || this.holdsRows(row[name])) {
+                continue;
+            }
+            next ??= { ...row };
+            next[name] = value;
+        }
+        return next ?? row;
+    }
+    holdsRows(value) {
+        if (Array.isArray(value)) {
+            return value.some((item) => this.identify(item) !== undefined);
+        }
+        return this.identify(value) !== undefined;
+    }
+    identify(value) {
+        if (!isPlainObject(value) || typeof value.__typename !== 'string') {
+            return undefined;
+        }
+        return this.keyOf(value.__typename, value);
+    }
+    each(value, within, visit, path = '') {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                this.each(item, within, visit, path);
+            }
+            return;
+        }
+        if (!isPlainObject(value)) {
+            return;
+        }
+        const key = this.identify(value);
+        if (key !== undefined && (within === undefined || within.includes(path))) {
+            visit(key, value);
+        }
+        for (const [name, child] of Object.entries(value)) {
+            this.each(child, within, visit, childPath(path, name));
+        }
+    }
+    nullableSlot(parent, name, depth, slots) {
+        if (depth === 0) {
+            return slots.nullableRoots.has(name);
+        }
+        const typename = parent.__typename;
+        const relation = typeof typename === 'string' ? this.manifest.models[typename]?.relations[name] : undefined;
+        return relation !== undefined && !relation.list && relation.nullable;
+    }
+    vacate(child, name, depth, slots, parent) {
+        if (slots !== undefined) {
+            slots.evicted = true;
+        }
+        if (slots !== undefined && this.nullableSlot(parent, name, depth, slots)) {
+            return null;
+        }
+        const key = this.identify(child);
+        if (slots !== undefined && key !== undefined) {
+            slots.held.add(key);
+        }
+        return child;
+    }
+    rewrite(value, within, transform, slots, depth = 0, path = '') {
+        if (Array.isArray(value)) {
+            let changed = false;
+            const next = [];
+            for (const item of value) {
+                const rewritten = this.rewrite(item, within, transform, slots, depth + 1, path);
+                if (rewritten === REMOVED) {
+                    changed = true;
+                    if (slots !== undefined) {
+                        slots.evicted = true;
+                    }
+                    continue;
+                }
+                if (rewritten !== item) {
+                    changed = true;
+                }
+                next.push(rewritten);
+            }
+            return changed ? next : value;
+        }
+        if (!isPlainObject(value)) {
+            return value;
+        }
+        let copy;
+        for (const [name, child] of Object.entries(value)) {
+            const rewritten = this.rewrite(child, within, transform, slots, depth + 1, childPath(path, name));
+            const replacement = rewritten === REMOVED ? this.vacate(child, name, depth, slots, value) : rewritten;
+            if (replacement !== child) {
+                copy ??= { ...value };
+                copy[name] = replacement;
+            }
+        }
+        const current = copy ?? value;
+        const key = this.identify(current);
+        if (key === undefined || (within !== undefined && !within.includes(path))) {
+            return current;
+        }
+        return transform(current, key);
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,56 @@
+import { type GolemError, GolemProtocolError, type GraphQLResponseBody } from './errors.js';
+export declare const PROTOCOL_VERSION = 1;
+export interface GolemBlock {
+    readonly protocol: number;
+    readonly contract: string;
+}
+export interface ContractManifest {
+    readonly contract: string;
+}
+export declare function golemBlock(manifest: ContractManifest): GolemBlock;
+export declare const CloseCode: {
+    readonly BadRequest: 4400;
+    readonly Unauthorized: 4401;
+    readonly Forbidden: 4403;
+    readonly InitTimeout: 4408;
+    readonly SubscriberExists: 4409;
+    readonly HandshakeRefused: 4426;
+    readonly TooManyInits: 4429;
+};
+export type SessionStatus = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'unauthenticated' | 'forbidden' | 'invalid' | 'protocol-mismatch' | 'contract-mismatch' | 'deadline-required';
+export type CloseDisposition = {
+    readonly action: 'retry';
+} | {
+    readonly action: 'reauthenticate';
+} | {
+    readonly action: 'fatal';
+    readonly status: SessionStatus;
+    readonly error: GolemError | GolemProtocolError;
+};
+export declare function handshakeRefusal(reason: string): CloseDisposition & {
+    readonly action: 'fatal';
+};
+export declare function classifyClose(code: number, reason: string, acknowledged: boolean): CloseDisposition;
+export declare const BACKOFF_BASE_MS = 250;
+export declare const BACKOFF_CAP_MS = 30000;
+export declare function backoffCeiling(attempt: number): number;
+export declare function backoffDelay(attempt: number, random?: () => number): number;
+export declare function isFatalHandshakeStatus(status: SessionStatus): boolean;
+export type AckOutcome = {
+    readonly kind: 'ack';
+} | {
+    readonly kind: 'event';
+    readonly body: GraphQLResponseBody;
+} | {
+    readonly kind: 'error';
+    readonly errors: GolemError[];
+} | {
+    readonly kind: 'violation';
+    readonly error: GolemProtocolError;
+};
+export declare class AckTracker {
+    private acknowledged;
+    get live(): boolean;
+    reset(): void;
+    accept(body: GraphQLResponseBody): AckOutcome;
+}

package/dist/protocol.js

@@ -0,0 +1,109 @@
+import { GolemContractMismatchError, GolemDeadlineRequiredError, GolemProtocolError, GolemProtocolMismatchError, GolemUnauthenticatedError, GolemError as GolemErrorClass, CODE_CONTRACT_MISMATCH, CODE_DEADLINE_REQUIRED, CODE_PROTOCOL_MISMATCH, errorsOf } from './errors.js';
+export const PROTOCOL_VERSION = 1;
+export function golemBlock(manifest) {
+    return { protocol: PROTOCOL_VERSION, contract: manifest.contract };
+}
+export const CloseCode = {
+    BadRequest: 4400,
+    Unauthorized: 4401,
+    Forbidden: 4403,
+    InitTimeout: 4408,
+    SubscriberExists: 4409,
+    HandshakeRefused: 4426,
+    TooManyInits: 4429,
+};
+const REFUSAL_PREFIX = 'golem:';
+function refusalShape(message, code) {
+    return { message, extensions: { code } };
+}
+export function handshakeRefusal(reason) {
+    const detail = reason.startsWith(REFUSAL_PREFIX) ? reason.slice(REFUSAL_PREFIX.length) : reason;
+    switch (detail) {
+        case 'protocol':
+            return {
+                action: 'fatal',
+                status: 'protocol-mismatch',
+                error: new GolemProtocolMismatchError(refusalShape('the server refused the live protocol version this client speaks', CODE_PROTOCOL_MISMATCH)),
+            };
+        case 'contract':
+            return {
+                action: 'fatal',
+                status: 'contract-mismatch',
+                error: new GolemContractMismatchError(refusalShape('the client was generated from a different contract than this server; regenerate the client', CODE_CONTRACT_MISMATCH)),
+            };
+        case CODE_DEADLINE_REQUIRED:
+            return {
+                action: 'fatal',
+                status: 'deadline-required',
+                error: new GolemDeadlineRequiredError(refusalShape('the server refused the socket because the principal has no credential expiry', CODE_DEADLINE_REQUIRED)),
+            };
+        default:
+            return {
+                action: 'fatal',
+                status: 'protocol-mismatch',
+                error: new GolemProtocolError(`the server refused the handshake with an unrecognised reason ${JSON.stringify(reason)}`),
+            };
+    }
+}
+export function classifyClose(code, reason, acknowledged) {
+    switch (code) {
+        case CloseCode.HandshakeRefused:
+            return handshakeRefusal(reason);
+        case CloseCode.Unauthorized:
+            if (acknowledged) {
+                return { action: 'reauthenticate' };
+            }
+            return {
+                action: 'fatal',
+                status: 'unauthenticated',
+                error: new GolemUnauthenticatedError('the server closed the socket with 4401 before the connection was acknowledged: the credentials were rejected'),
+            };
+        case CloseCode.Forbidden:
+            return { action: 'fatal', status: 'forbidden', error: new GolemErrorClass({ message: 'the server refused connection initialisation (4403)', extensions: { code: 'GOLEM_FORBIDDEN' } }, false) };
+        case CloseCode.BadRequest:
+        case CloseCode.SubscriberExists:
+        case CloseCode.TooManyInits:
+            return { action: 'fatal', status: 'invalid', error: new GolemProtocolError(`the server closed the socket with ${code}: the client broke the protocol`) };
+        default:
+            return { action: 'retry' };
+    }
+}
+export const BACKOFF_BASE_MS = 250;
+export const BACKOFF_CAP_MS = 30_000;
+export function backoffCeiling(attempt) {
+    return Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** Math.max(0, attempt));
+}
+export function backoffDelay(attempt, random = Math.random) {
+    return Math.floor(random() * backoffCeiling(attempt));
+}
+export function isFatalHandshakeStatus(status) {
+    return status === 'protocol-mismatch' || status === 'contract-mismatch';
+}
+export class AckTracker {
+    acknowledged = false;
+    get live() {
+        return this.acknowledged;
+    }
+    reset() {
+        this.acknowledged = false;
+    }
+    accept(body) {
+        if (body.extensions?.golem?.live === true) {
+            if (this.acknowledged) {
+                return { kind: 'violation', error: new GolemProtocolError('a second live acknowledgement arrived for one operation') };
+            }
+            if (body.data !== null || (body.errors?.length ?? 0) !== 0) {
+                return { kind: 'violation', error: new GolemProtocolError('the live acknowledgement carried data or errors') };
+            }
+            this.acknowledged = true;
+            return { kind: 'ack' };
+        }
+        if ((body.errors?.length ?? 0) !== 0) {
+            return { kind: 'error', errors: errorsOf(body) };
+        }
+        if (!this.acknowledged) {
+            return { kind: 'violation', error: new GolemProtocolError('an event arrived before the live acknowledgement') };
+        }
+        return { kind: 'event', body };
+    }
+}