@kubun/store-connector 0.17.0 → 0.17.2

package/lib/api.d.ts

@@ -1,4 +1,4 @@
-import type { Adapter } from '@kubun/db-adapter';
+import { type Adapter } from '@kubun/db-adapter';
 import type { Kysely } from 'kysely';
 import type { ConnectorTables } from './tables.js';
 export type SyncStatus = 'idle' | 'syncing' | 'error';
@@ -9,11 +9,28 @@ export type SyncState = {
     status: SyncStatus;
     error?: string;
     leaseExpiresAt?: number | null;
+    recovery?: unknown;
+    version?: number;
+    incarnation?: string;
 };
 export type SyncStateEntry = SyncState & {
     connectorName: string;
     ownerDID: string;
 };
+export type SyncProgressCASCurrent = {
+    checkpoint: unknown;
+    recovery: unknown;
+    version: number;
+    incarnation: string;
+};
+export type SyncProgressCASResult = {
+    checkpoint: unknown;
+    recovery: unknown;
+    lastSyncedAt: string;
+    entityCount: number;
+    error?: string | null;
+};
+export type SyncProgressRecompute = (current: SyncProgressCASCurrent | null) => SyncProgressCASResult | Promise<SyncProgressCASResult>;
 export type PendingAuthRecord = {
     state: string;
     codeVerifier: string;
@@ -30,19 +47,282 @@ export type PendingAuthRecord = {
     scopes: Array<string>;
     expiresAt: number;
 };
+export type ConnectorOperationOp = 'create' | 'update';
+export type ConnectorOperationState = 'attempted' | 'committed' | 'reconcile_only' | 'dead';
+export type ClaimOperationInput = {
+    callerDID: string;
+    operationID: string;
+    ownerDID: string;
+    connectorName: string;
+    model: string;
+    op: ConnectorOperationOp;
+    accountKey: string;
+    target: string;
+    sourceID: string | null;
+    deterministicEventID: string;
+    payloadHash: string;
+    reissueIntent: unknown;
+    /**
+     * The provider's conditional-write token (e.g. an ETag) of the state the
+     * write is based on, pinned for every attempt of the operation. Captured
+     * state rather than part of the envelope: a replay never compares it.
+     */
+    providerEtag?: string | null;
+    /**
+     * The document the operation writes, when it is known before any provider
+     * I/O (an update's target, a create whose provider id is predetermined).
+     * Recorded on the first claim only; like `providerEtag`, a replay never
+     * compares it. Finalize records the document the write actually projected
+     * into, which takes precedence.
+     */
+    documentID?: string | null;
+    leaseToken: string;
+    leaseExpiresAt: number;
+};
+export type RecordOperationInput = {
+    callerDID: string;
+    operationID: string;
+    fromState: ConnectorOperationState;
+    toState: Exclude<ConnectorOperationState, 'committed'>;
+    version: number;
+    leaseToken: string;
+    providerEtag?: string | null;
+    nextAttemptAt?: number | null;
+    kind?: string | null;
+    httpStatus?: number | null;
+    /**
+     * Whether this transition consumes a recovery attempt (default `true`).
+     * `false` records a failure's classification against an attempt already
+     * consumed earlier in the same recovery pass.
+     */
+    countAttempt?: boolean;
+    /**
+     * Gives back the attempt this recovery pass consumed (`attempts - 1`), for a
+     * pass that turned out never to reach the provider. Takes precedence over
+     * `countAttempt`.
+     */
+    refundAttempt?: boolean;
+    /**
+     * Marks the `nextAttemptAt` this records as a deferral that lapses on its
+     * own (see `DeferReason`). Omitted clears any earlier mark.
+     */
+    deferReason?: DeferReason;
+    /**
+     * With `refundAttempt`: the marker of the run asking (see
+     * `markSendStarted`). The refund is refused when a different run started
+     * a provider write in this attempt, including when this run marked too.
+     */
+    sendMarker?: string;
+};
+/**
+ * A deferral that lapses on its own: `'offline'` — the device was offline,
+ * made due again on reconnect (`resumeOfflineDeferred`); `'auth'` — the
+ * owner's credential could not authorize the write (none stored, or refused by
+ * the provider), made due again once the owner authorizes
+ * (`resumeAuthDeferred`).
+ */
+export type DeferReason = 'offline' | 'auth';
+export type FinalizeOperationInput = {
+    key: {
+        callerDID: string;
+        operationID: string;
+    };
+    version: number;
+    leaseToken: string;
+    documentID: string;
+    resultEntity: unknown;
+    watchIdentity: ProjectionWatchIdentity;
+    currentWinnerDigest: string | null;
+};
+export type ConnectorOperation = {
+    callerDID: string;
+    operationID: string;
+    /**
+     * Opaque random key assigned when the operation was first claimed: its
+     * public identity, unlike `operationID`, which is the caller's idempotency
+     * key.
+     */
+    nodeKey: string;
+    ownerDID: string;
+    connectorName: string;
+    model: string;
+    op: ConnectorOperationOp;
+    accountKey: string;
+    target: string;
+    sourceID: string | null;
+    deterministicEventID: string;
+    payloadHash: string;
+    reissueIntent: unknown;
+    providerEtag: string | null;
+    documentID: string | null;
+    resultEntity: unknown;
+    state: ConnectorOperationState;
+    attempts: number;
+    nextAttemptAt: number | null;
+    lastKind: string | null;
+    lastHTTPStatus: number | null;
+    version: number;
+    incarnation: string | null;
+    leaseToken: string | null;
+    leaseExpiresAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+};
+export type ProjectionWatchIdentity = {
+    ownerDID: string;
+    connectorName: string;
+    model: string;
+    accountKey: string;
+    sourceID: string;
+};
+export type ProjectionWatchVerificationStatus = 'pending_verification' | 'verified' | 'repair_failed';
+export type ProjectionWatch = {
+    ownerDID: string;
+    connectorName: string;
+    model: string;
+    accountKey: string;
+    sourceID: string;
+    documentID: string;
+    verifiedStateDigest: string | null;
+    observedWinnerDigest: string | null;
+    verificationStatus: ProjectionWatchVerificationStatus;
+    verificationAttempts: number;
+    repairGeneration: number;
+    nextAttemptAt: number | null;
+    version: number;
+    createdAt: number;
+    updatedAt: number;
+};
+/**
+ * Filters for `listTrackedOperations`, all optional and combined with AND. An
+ * empty `states` or `documentIDs` list matches nothing.
+ */
+export type TrackedOperationFilter = {
+    nodeKey?: string;
+    callerDID?: string;
+    operationID?: string;
+    /** Operations the DID claimed as caller, or owns as credential owner. */
+    visibleTo?: string;
+    connectorName?: string;
+    states?: Array<ConnectorOperationState>;
+    /** Operations linked to one of these documents. */
+    documentIDs?: Array<string>;
+};
+export type ArmWatchReason = 'finalize' | 'ingress' | 'manual';
+export type ArmWatchOutcome = 'opened' | 'coalesced' | 'noop';
+export type ArmWatchOptions = {
+    triggeringWinner?: string;
+    dueAt: number;
+};
+export type RecordVerificationInput = {
+    fetchedDigest: string | null;
+    generation: number;
+    maxAttempts: number;
+    dueAt: number;
+    claimedUntil?: number;
+};
+export type RecordVerificationOutcome = 'verified' | 'pending' | 'repair_failed' | 'stale-generation' | 'stale-claim';
+/**
+ * Reads a document's current winner state digest (`W`) INSIDE the caller's
+ * transaction — wraps `readWinnerStateDigest(tx, documentID)`
+ * (exported from `@kubun/store-graph`). Graph and connector tables share one
+ * DB/connection via the KubunDB coordinator, so the wired implementation
+ * must be invoked with the `tx` handed to this callback, never a top-level
+ * `db` — passing the top-level db would nest a transaction and, on SQLite's
+ * single connection, deadlock.
+ */
+export type ReadWinner = (documentID: string, tx: Kysely<ConnectorTables>) => Promise<string>;
+export type ConnectorStoreDeps = {
+    /**
+     * Required by `armWatch`'s `'ingress'`/`'manual'` reasons and by
+     * `recordVerification`; a caller that reaches either without it gets a clear
+     * throw rather than a silent no-op. The connector plugin passes one over
+     * `readWinnerStateDigest`; tests pass a scripted fake so the CAS interleaves
+     * are deterministic.
+     */
+    readWinner?: ReadWinner;
+    /**
+     * The source of every random id the store mints: an operation's node key and
+     * a sync state's incarnation. The connector plugin passes its runtime's
+     * `getRandomID`.
+     */
+    getRandomID: () => string;
+};
 export type ConnectorStoreAPI = {
     getSyncState(connectorName: string, ownerDID: string): Promise<SyncState | null>;
     setSyncState(connectorName: string, ownerDID: string, state: SyncState): Promise<void>;
-    updateSyncProgress(connectorName: string, ownerDID: string, progress: {
-        checkpoint: unknown;
-        lastSyncedAt: string;
-        entityCount: number;
-        error?: string | null;
+    updateSyncProgress(connectorName: string, ownerDID: string, recompute: SyncProgressRecompute, options?: {
+        maxRetries?: number;
     }): Promise<void>;
     deleteSyncState(connectorName: string, ownerDID: string): Promise<void>;
     listSyncStatesForConnector(connectorName: string): Promise<Array<SyncStateEntry>>;
     createPendingAuth(record: PendingAuthRecord): Promise<void>;
     consumePendingAuth(state: string): Promise<PendingAuthRecord | null>;
     deleteExpiredPendingAuth(cutoffMs: number): Promise<void>;
+    claimOperation(input: ClaimOperationInput): Promise<{
+        status: 'claimed';
+        record: ConnectorOperation;
+    } | {
+        status: 'exists';
+        record: ConnectorOperation;
+    } | {
+        status: 'conflict';
+    }>;
+    acquireLease(callerDID: string, operationID: string, token: string, expiresAt: number): Promise<boolean>;
+    renewLease(callerDID: string, operationID: string, token: string, expiresAt: number): Promise<boolean>;
+    releaseLease(callerDID: string, operationID: string, token: string): Promise<boolean>;
+    getOperation(callerDID: string, operationID: string): Promise<ConnectorOperation | null>;
+    listTrackedOperations(filter: TrackedOperationFilter): Promise<Array<ConnectorOperation>>;
+    hasNewerOperationOnDocument(callerDID: string, operationID: string): Promise<boolean>;
+    markSendStarted(params: {
+        callerDID: string;
+        operationID: string;
+        leaseToken: string;
+        marker: string;
+    }): Promise<boolean>;
+    deferOperation(params: {
+        callerDID: string;
+        operationID: string;
+        nextAttemptAt: number;
+        leaseToken?: string;
+        reason?: DeferReason;
+    }): Promise<boolean>;
+    recordOperation(input: RecordOperationInput): Promise<boolean>;
+    finalizeOperationAndArmWatch(input: FinalizeOperationInput): Promise<boolean>;
+    getWatch(identity: ProjectionWatchIdentity): Promise<ProjectionWatch | null>;
+    getWatchByDocument(documentID: string): Promise<ProjectionWatch | null>;
+    listWatchesByDocuments(documentIDs: Array<string>): Promise<Array<ProjectionWatch>>;
+    armWatch(identity: ProjectionWatchIdentity, reason: ArmWatchReason, opts: ArmWatchOptions): Promise<ArmWatchOutcome>;
+    deferWatch(identity: ProjectionWatchIdentity, opts: {
+        generation: number;
+        nextAttemptAt: number;
+        reason?: DeferReason;
+        claimedUntil: number;
+    }): Promise<boolean>;
+    resumeOfflineDeferred(now: number): Promise<void>;
+    resumeAuthDeferred(params: {
+        now: number;
+        ownerDID: string;
+        connectorNames: Array<string>;
+    }): Promise<void>;
+    claimWatchAttempt(identity: ProjectionWatchIdentity, opts: {
+        generation: number;
+        now: number;
+        until: number;
+    }): Promise<boolean>;
+    recordVerification(identity: ProjectionWatchIdentity, input: RecordVerificationInput): Promise<RecordVerificationOutcome>;
+    requestRepull(identity: ProjectionWatchIdentity, opts: {
+        dueAt: number;
+    }): Promise<void>;
+    listDueOperations(now: number, opts: {
+        readWinner: ReadWinner;
+    }): Promise<{
+        operations: Array<ConnectorOperation>;
+        watches: Array<ProjectionWatch>;
+    }>;
+    collectFinishedOperations(params: {
+        before: number;
+        limit: number;
+    }): Promise<number>;
 };
-export declare function createConnectorStore(db: Kysely<ConnectorTables>, _adapter: Adapter): ConnectorStoreAPI;
+export declare function createConnectorStore(db: Kysely<ConnectorTables>, adapter: Adapter, deps: ConnectorStoreDeps): ConnectorStoreAPI;