@kubun/store-connector 0.17.0 → 0.17.1

package/lib/api.d.ts

@@ -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;
@@ -33,11 +50,8 @@ export type PendingAuthRecord = {
 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>>;

package/lib/api.js

@@ -1,17 +1,27 @@
 // --- Serialization helpers ---
+// `checkpoint` and `recovery` are JSON columns: ParseJSONResultsPlugin may have
+// already parsed them (Postgres) or left them as strings (SQLite), so handle
+// both. Mirrors the `scopes` handling in `consumePendingAuth`.
+function decodeJSONColumn(value) {
+    if (value == null) return null;
+    return typeof value === 'string' ? JSON.parse(value) : value;
+}
+function encodeJSONColumn(value) {
+    return value != null ? JSON.stringify(value) : null;
+}
 function rowToSyncState(row) {
-    // ParseJSONResultsPlugin may have already parsed the checkpoint value
-    let checkpoint = null;
-    if (row.checkpoint != null) {
-        checkpoint = typeof row.checkpoint === 'string' ? JSON.parse(row.checkpoint) : row.checkpoint;
-    }
     const state = {
-        checkpoint,
+        checkpoint: decodeJSONColumn(row.checkpoint),
         lastSyncedAt: row.last_synced_at,
         entityCount: row.entity_count,
         status: row.status,
-        leaseExpiresAt: row.lease_expires_at
+        leaseExpiresAt: row.lease_expires_at,
+        recovery: decodeJSONColumn(row.recovery),
+        version: row.version
     };
+    if (row.incarnation != null) {
+        state.incarnation = row.incarnation;
+    }
     if (row.error != null) {
         state.error = row.error;
     }
@@ -28,48 +38,86 @@ export function createConnectorStore(db, _adapter) {
         },
         async setSyncState (connectorName, ownerDID, state) {
             // `lease_expires_at` is dead: a fresh INSERT sets it null and a conflicting
-            // update leaves it untouched.
+            // update leaves it untouched. A fresh INSERT seeds version 0 and a random
+            // incarnation; a conflicting update leaves both untouched (this path is not
+            // the CAS write — it does not bump version or churn the incarnation).
+            const checkpoint = encodeJSONColumn(state.checkpoint);
+            const recovery = encodeJSONColumn(state.recovery);
             await db.insertInto('kubun_connector_sync_state').values({
                 connector_name: connectorName,
                 owner_did: ownerDID,
-                checkpoint: state.checkpoint != null ? JSON.stringify(state.checkpoint) : null,
+                checkpoint,
                 last_synced_at: state.lastSyncedAt,
                 entity_count: state.entityCount,
                 status: state.status,
                 error: state.error ?? null,
-                lease_expires_at: null
+                lease_expires_at: null,
+                recovery,
+                version: 0,
+                incarnation: globalThis.crypto.randomUUID()
             }).onConflict((oc)=>oc.columns([
                     'connector_name',
                     'owner_did'
                 ]).doUpdateSet({
-                    checkpoint: state.checkpoint != null ? JSON.stringify(state.checkpoint) : null,
+                    checkpoint,
                     last_synced_at: state.lastSyncedAt,
                     entity_count: state.entityCount,
                     status: state.status,
-                    error: state.error ?? null
+                    error: state.error ?? null,
+                    recovery
                 })).execute();
         },
-        async updateSyncProgress (connectorName, ownerDID, progress) {
-            const checkpoint = progress.checkpoint != null ? JSON.stringify(progress.checkpoint) : null;
-            const error = progress.error ?? null;
-            await db.insertInto('kubun_connector_sync_state').values({
-                connector_name: connectorName,
-                owner_did: ownerDID,
-                checkpoint,
-                last_synced_at: progress.lastSyncedAt,
-                entity_count: progress.entityCount,
-                status: 'idle',
-                error,
-                lease_expires_at: null
-            }).onConflict((oc)=>oc.columns([
-                    'connector_name',
-                    'owner_did'
-                ]).doUpdateSet({
-                    checkpoint,
-                    last_synced_at: progress.lastSyncedAt,
-                    entity_count: progress.entityCount,
-                    error
-                })).execute();
+        async updateSyncProgress (connectorName, ownerDID, recompute, options) {
+            // The caller passes the authoritative MAX_CAS_RETRIES; 5 is a defensive
+            // fallback for direct callers/tests.
+            const maxRetries = options?.maxRetries ?? 5;
+            for(let attempt = 0; attempt <= maxRetries; attempt++){
+                const row = await db.selectFrom('kubun_connector_sync_state').selectAll().where('connector_name', '=', connectorName).where('owner_did', '=', ownerDID).executeTakeFirst();
+                if (row == null) {
+                    // No row yet: INSERT ... ON CONFLICT DO NOTHING so a lost insert race
+                    // (a concurrent writer created the row first) falls through to reload
+                    // and take the update path.
+                    const result = await recompute(null);
+                    const inserted = await db.insertInto('kubun_connector_sync_state').values({
+                        connector_name: connectorName,
+                        owner_did: ownerDID,
+                        checkpoint: encodeJSONColumn(result.checkpoint),
+                        last_synced_at: result.lastSyncedAt,
+                        entity_count: result.entityCount,
+                        status: 'idle',
+                        error: result.error ?? null,
+                        lease_expires_at: null,
+                        recovery: encodeJSONColumn(result.recovery),
+                        version: 0,
+                        incarnation: globalThis.crypto.randomUUID()
+                    }).onConflict((oc)=>oc.columns([
+                            'connector_name',
+                            'owner_did'
+                        ]).doNothing()).executeTakeFirst();
+                    if ((inserted?.numInsertedOrUpdatedRows ?? 0n) > 0n) return;
+                    continue;
+                }
+                const result = await recompute({
+                    checkpoint: decodeJSONColumn(row.checkpoint),
+                    recovery: decodeJSONColumn(row.recovery),
+                    version: row.version,
+                    incarnation: row.incarnation ?? ''
+                });
+                // Single conditional UPDATE guarded on the read version AND incarnation.
+                // `status` is deliberately omitted (workflow owns it). Zero rows means a
+                // concurrent writer won, or the row was delete+recreated (incarnation
+                // differs) ⇒ reload and recompute.
+                const updated = await db.updateTable('kubun_connector_sync_state').set({
+                    checkpoint: encodeJSONColumn(result.checkpoint),
+                    last_synced_at: result.lastSyncedAt,
+                    entity_count: result.entityCount,
+                    error: result.error ?? null,
+                    recovery: encodeJSONColumn(result.recovery),
+                    version: row.version + 1
+                }).where('connector_name', '=', connectorName).where('owner_did', '=', ownerDID).where('version', '=', row.version).where('incarnation', '=', row.incarnation).executeTakeFirst();
+                if ((updated?.numUpdatedRows ?? 0n) > 0n) return;
+            }
+            throw new Error(`updateSyncProgress: CAS failed after ${maxRetries + 1} attempts for ${connectorName}/${ownerDID}`);
         },
         async deleteSyncState (connectorName, ownerDID) {
             await db.deleteFrom('kubun_connector_sync_state').where('connector_name', '=', connectorName).where('owner_did', '=', ownerDID).execute();

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 import type { StoreProvider } from '@kubun/db';
 import type { ConnectorStoreAPI } from './api.js';
-export type { ConnectorStoreAPI, PendingAuthRecord, SyncState, SyncStateEntry, SyncStatus, } from './api.js';
+export type { ConnectorStoreAPI, PendingAuthRecord, SyncProgressCASCurrent, SyncProgressCASResult, SyncProgressRecompute, SyncState, SyncStateEntry, SyncStatus, } from './api.js';
 export { createConnectorStore } from './api.js';
 export { connectorStoreDefinition } from './definition.js';
 export declare const CONNECTOR_STORE: "connector";

package/lib/migrations.js

@@ -7,7 +7,13 @@ export function getConnectorMigrations(ctx) {
             // overflows int32 on Postgres; bigint holds it and the adapter's int8
             // parser reads it back as a JS number. Nullable: a row with no active
             // lease leaves this null.
-            .addColumn('lease_expires_at', t.bigint).addPrimaryKeyConstraint('kubun_connector_sync_state_pkey', [
+            .addColumn('lease_expires_at', t.bigint)// Durable recovery buffer, JSON-encoded (see @kubun/connector `Recovery`).
+            // Nullable: null means an empty buffer.
+            .addColumn('recovery', t.text)// Optimistic-concurrency version, bumped on every atomic checkpoint+
+            // recovery write. Starts at 0.
+            .addColumn('version', 'integer', (col)=>col.notNull().defaultTo(0))// Random id set on insert, part of the CAS predicate so a paused writer
+            // cannot rebase stale recovery onto a delete+recreated row (ABA).
+            .addColumn('incarnation', t.text).addPrimaryKeyConstraint('kubun_connector_sync_state_pkey', [
                 'connector_name',
                 'owner_did'
             ]).execute();

package/lib/tables.d.ts

@@ -8,6 +8,9 @@ export type ConnectorSyncStateTable = {
     status: string;
     error: string | null;
     lease_expires_at: number | null;
+    recovery: string | null;
+    version: number;
+    incarnation: string | null;
 };
 export type ConnectorSyncState = Selectable<ConnectorSyncStateTable>;
 export type ConnectorPendingAuthTable = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-connector",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,