@syncular/client 0.15.16 → 0.15.18

package/src/client.ts

@@ -60,6 +60,20 @@ import {
 } from './blob';
 import type { ClientDatabase, SqlRow, SqlValue } from './database';
 import { registerDevtools } from './devtools';
+import {
+  CLIENT_DIAGNOSTICS_VERSION,
+  ClientDiagnosticsEmitter,
+  type ClientDiagnosticsListener,
+  type ClientDiagnosticsRequest,
+  type ClientDiagnosticsSnapshot,
+  type ClientDiagnosticsStorage,
+  type DiagnosticLastChange,
+  type DiagnosticLastRound,
+  type DiagnosticRoundCounters,
+  type DiagnosticSubscription,
+  MAX_DIAGNOSTIC_DOMAINS,
+  MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
+} from './diagnostics';
 import type { EncryptionConfig } from './encryption';
 import { ClientSyncError } from './errors';
 import {
@@ -489,6 +503,18 @@ function emptySummary(pushed: number): MutableSummary {
   };
 }
 
+function isFinalPushResult(frame: PushResultFrame): boolean {
+  return (
+    frame.status !== 'rejected' ||
+    !frame.results.some(
+      (result) =>
+        result.status === 'error' &&
+        result.code === 'sync.idempotency_cache_miss' &&
+        result.retryable,
+    )
+  );
+}
+
 export class SyncClient {
   readonly #config: SyncClientConfig;
   readonly #db: ClientDatabase;
@@ -531,6 +557,11 @@ export class SyncClient {
   readonly #invalidation = new InvalidationEmitter();
   /** §8.6: subscribable presence-change listeners (twin of onPresence). */
   readonly #presenceListeners = new Set<(scopeKey: string) => void>();
+  readonly #diagnostics = new ClientDiagnosticsEmitter();
+  #diagnosticsDeferralDepth = 0;
+  #diagnosticsPending = false;
+  #lastRound: DiagnosticLastRound | undefined;
+  #lastChange: DiagnosticLastChange | undefined;
   /** The batch accumulator; non-undefined only inside `#applyBatch`. */
   #batch: ChangeAccumulator | undefined;
   /**
@@ -669,6 +700,7 @@ export class SyncClient {
       upgrading: async () => this.upgrading,
       onInvalidate: (listener) => this.onInvalidate(listener),
     });
+    this.#emitDiagnostics();
   }
 
   /**
@@ -819,6 +851,7 @@ export class SyncClient {
       this.#config.onSyncNeeded?.('startup');
       this.#config.onSyncIntent?.({ kind: 'interactive' });
     }
+    this.#emitDiagnostics();
   }
 
   // -- accessors ------------------------------------------------------------
@@ -928,16 +961,255 @@ export class SyncClient {
     return this.#changes.on(listener);
   }
 
+  /** Subscribe to complete, privacy-safe diagnostic snapshots. */
+  onDiagnostics(listener: ClientDiagnosticsListener): () => void {
+    return this.#diagnostics.on(listener);
+  }
+
+  /**
+   * One atomic support/product-health view. It never returns scope values,
+   * rows, SQL, paths, auth material, lease ids, keys, or mutation bodies.
+   */
+  diagnosticsSnapshot(
+    request: ClientDiagnosticsRequest = {},
+  ): ClientDiagnosticsSnapshot {
+    this.#requireActive();
+    const expected = request.expectedSubscriptions ?? [];
+    if (expected.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS) {
+      throw new ClientSyncError(
+        'sync.invalid_request',
+        `diagnosticsSnapshot accepts at most ${MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS} expected subscriptions`,
+      );
+    }
+    const registered = loadSubscriptions(this.#db);
+    const subscriptions = new Map<string, DiagnosticSubscription>();
+    for (const sub of registered) {
+      const reset = sub.cursor < 0 && sub.reasonCode === 'sync.cursor_expired';
+      const complete =
+        sub.status === 'active' &&
+        sub.cursor >= 0 &&
+        sub.bootstrapState === undefined;
+      subscriptions.set(sub.id, {
+        id: sub.id,
+        table: sub.table,
+        state:
+          sub.status === 'revoked'
+            ? 'revoked'
+            : sub.status === 'failed'
+              ? 'failed'
+              : reset
+                ? 'reset'
+                : complete
+                  ? 'complete'
+                  : 'bootstrapping',
+        complete,
+        cursor: sub.cursor,
+        ...(sub.reasonCode !== undefined
+          ? { reasonCode: this.#diagnosticCode(sub.reasonCode) }
+          : {}),
+      });
+    }
+    for (const item of expected) {
+      if (
+        typeof item.id !== 'string' ||
+        item.id.length === 0 ||
+        typeof item.table !== 'string' ||
+        item.table.length === 0
+      ) {
+        throw new ClientSyncError(
+          'sync.invalid_request',
+          'diagnosticsSnapshot expected subscriptions require non-empty id and table strings',
+        );
+      }
+      const registeredSubscription = subscriptions.get(item.id);
+      if (
+        registeredSubscription !== undefined &&
+        registeredSubscription.table !== item.table
+      ) {
+        subscriptions.set(item.id, {
+          id: item.id,
+          table: item.table,
+          state: 'failed',
+          complete: false,
+          reasonCode: 'client.subscription_intent_mismatch',
+        });
+      } else if (registeredSubscription === undefined) {
+        subscriptions.set(item.id, {
+          id: item.id,
+          table: item.table,
+          state: 'unregistered',
+          complete: false,
+        });
+      }
+    }
+    const capturedAtMs = this.#now();
+    const leaseState = this.#diagnosticLease(capturedAtMs);
+    const connectivity =
+      this.#lastRound?.status === 'succeeded'
+        ? 'online'
+        : this.#lastRound?.status === 'failed' &&
+            this.#transportFailureCode(this.#lastRound.errorCode)
+          ? 'offline'
+          : 'unknown';
+    const expectedOrder = new Map(
+      expected.map((item, index) => [item.id, index] as const),
+    );
+    const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
+      const aExpected = expectedOrder.get(a.id);
+      const bExpected = expectedOrder.get(b.id);
+      if (aExpected !== undefined || bExpected !== undefined) {
+        return (
+          (aExpected ?? Number.MAX_SAFE_INTEGER) -
+          (bExpected ?? Number.MAX_SAFE_INTEGER)
+        );
+      }
+      return a.id.localeCompare(b.id);
+    });
+    return {
+      version: CLIENT_DIAGNOSTICS_VERSION,
+      capturedAtMs,
+      host: {
+        kind: 'direct',
+        role: 'single',
+        connectivity,
+        realtime:
+          this.#config.realtime === undefined
+            ? 'unsupported'
+            : this.#socket === undefined
+              ? 'disconnected'
+              : 'connected',
+      },
+      securityLifecycle: this.#securityLifecycle,
+      schema: {
+        currentVersion: this.#config.schema.version,
+        upgrading: this.#upgrading,
+        ...(this.#schemaFloor?.requiredSchemaVersion !== undefined
+          ? { requiredVersion: this.#schemaFloor.requiredSchemaVersion }
+          : {}),
+        ...(this.#schemaFloor?.latestSchemaVersion !== undefined
+          ? { latestVersion: this.#schemaFloor.latestSchemaVersion }
+          : {}),
+      },
+      replica: {
+        localRevision: getLocalRevision(this.#db).toString(),
+        syncNeeded: this.#needsPull,
+        pendingOutbox: listOutbox(this.#db).length,
+      },
+      lease: leaseState,
+      subscriptions: allSubscriptions.slice(
+        0,
+        MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
+      ),
+      subscriptionsTruncated:
+        allSubscriptions.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
+      ...(this.#lastRound !== undefined ? { lastRound: this.#lastRound } : {}),
+      ...(this.#lastChange !== undefined
+        ? { lastChange: this.#lastChange }
+        : {}),
+      storage: this.#diagnosticStorage(),
+    };
+  }
+
+  #diagnosticLease(nowMs: number): ClientDiagnosticsSnapshot['lease'] {
+    const lease = this.#leaseState;
+    if (lease?.errorCode !== undefined) {
+      return {
+        state: 'stopped',
+        errorCode: this.#diagnosticCode(lease.errorCode),
+        ...(lease.expiresAtMs !== undefined
+          ? { expiresAtMs: lease.expiresAtMs }
+          : {}),
+      };
+    }
+    if (lease?.expiresAtMs === undefined) return { state: 'none' };
+    return {
+      state: lease.expiresAtMs <= nowMs ? 'expired' : 'active',
+      expiresAtMs: lease.expiresAtMs,
+    };
+  }
+
+  #diagnosticStorage(): ClientDiagnosticsStorage {
+    try {
+      const pageCount = Number(
+        this.#db.query('PRAGMA page_count')[0]?.page_count ?? 0,
+      );
+      const pageSize = Number(
+        this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0,
+      );
+      const outboxBytes = Number(
+        this.#db.query(
+          'SELECT COALESCE(SUM(LENGTH(operations)), 0) AS bytes FROM _syncular_outbox',
+        )[0]?.bytes ?? 0,
+      );
+      const outcome = this.#db.query(
+        `SELECT COUNT(*) AS entries,
+                COALESCE(SUM(LENGTH(results) + COALESCE(LENGTH(operations), 0)), 0) AS bytes
+           FROM _syncular_commit_outcomes`,
+      )[0];
+      const blobBytes = this.#hasBlobs
+        ? Number(
+            this.#db.query(
+              'SELECT COALESCE(SUM(byte_length), 0) AS bytes FROM _syncular_blobs',
+            )[0]?.bytes ?? 0,
+          )
+        : 0;
+      const pressure =
+        this.#config.blobCacheMaxBytes !== undefined &&
+        blobBytes > this.#config.blobCacheMaxBytes;
+      return {
+        status: pressure ? 'pressure' : 'healthy',
+        databaseBytesApprox: Math.max(0, pageCount * pageSize),
+        pendingOutboxBytesApprox: Math.max(0, outboxBytes),
+        retainedOutcomeBytesApprox: Math.max(0, Number(outcome?.bytes ?? 0)),
+        retainedOutcomeEntries: Math.max(0, Number(outcome?.entries ?? 0)),
+        blobCacheBytesApprox: Math.max(0, blobBytes),
+        ...(pressure
+          ? { pressureReasonCode: 'client.blob_cache_over_limit' as const }
+          : {}),
+      };
+    } catch {
+      return { status: 'unreadable' };
+    }
+  }
+
+  #emitDiagnostics(): void {
+    if (
+      !this.#started ||
+      this.#securityLifecycle !== 'active' ||
+      !this.#diagnostics.observed
+    ) {
+      return;
+    }
+    if (this.#diagnosticsDeferralDepth > 0) {
+      this.#diagnosticsPending = true;
+      return;
+    }
+    this.#diagnostics.emit(this.diagnosticsSnapshot());
+  }
+
+  #beginDiagnosticsDeferral(): void {
+    this.#diagnosticsDeferralDepth += 1;
+  }
+
+  #endDiagnosticsDeferral(): void {
+    if (this.#diagnosticsDeferralDepth === 0) return;
+    this.#diagnosticsDeferralDepth -= 1;
+    if (this.#diagnosticsDeferralDepth === 0 && this.#diagnosticsPending) {
+      this.#diagnosticsPending = false;
+      this.#emitDiagnostics();
+    }
+  }
+
   /** One call for the complete status domain used by reactive hosts. */
   statusSnapshot(): SyncStatusSnapshot {
     this.#requireStarted();
     return this.#statusSnapshot();
   }
 
-  #statusSnapshot(): SyncStatusSnapshot {
+  #statusSnapshot(outboxCount?: number): SyncStatusSnapshot {
     return {
       currentSchemaVersion: this.#config.schema.version,
-      outbox: listOutbox(this.#db).length,
+      outbox: outboxCount ?? listOutbox(this.#db).length,
       upgrading: this.#upgrading,
       leaseState: this.#leaseState,
       schemaFloor: this.#schemaFloor,
@@ -951,7 +1223,10 @@ export class SyncClient {
    * Re-entrant calls share the outer batch so a nested apply never
    * double-emits (e.g. purge → blob reconcile → replay inside one round).
    */
-  #applyBatch<T>(fn: (batch: ChangeAccumulator) => T): T {
+  #applyBatch<T>(
+    fn: (batch: ChangeAccumulator) => T,
+    statusSnapshotOverride?: () => SyncStatusSnapshot,
+  ): T {
     if (this.#batch !== undefined) return fn(this.#batch);
     const batch = new ChangeAccumulator();
     let revision: LocalRevision | undefined;
@@ -964,7 +1239,9 @@ export class SyncClient {
           result = fn(batch);
           if (batch.touched) {
             revision = bumpLocalRevision(this.#db);
-            if (batch.statusChanged) status = this.#statusSnapshot();
+            if (batch.statusChanged) {
+              status = statusSnapshotOverride?.() ?? this.#statusSnapshot();
+            }
           }
         } finally {
           this.#batch = undefined;
@@ -976,9 +1253,25 @@ export class SyncClient {
     }
     if (revision !== undefined) {
       const event = batch.finish(revision, status);
+      const tables = [...new Set(event.tables.map((entry) => entry.table))];
+      const windows = [...new Set(event.windows.map((entry) => entry.table))];
+      this.#lastChange = {
+        revision: revision.toString(),
+        recordedAtMs: this.#now(),
+        tables: tables.slice(0, MAX_DIAGNOSTIC_DOMAINS),
+        windows: windows.slice(0, MAX_DIAGNOSTIC_DOMAINS),
+        domainsTruncated:
+          tables.length > MAX_DIAGNOSTIC_DOMAINS ||
+          windows.length > MAX_DIAGNOSTIC_DOMAINS,
+        statusChanged: event.status !== undefined,
+        conflictsChanged: event.conflictsChanged,
+        rejectionsChanged: event.rejectionsChanged,
+        outcomesChanged: event.outcomesChanged,
+      };
       this.#changes.emit(event);
       const legacy = invalidationFromChange(event);
       if (legacy !== undefined) this.#invalidation.emit(legacy);
+      this.#emitDiagnostics();
     }
     return result;
   }
@@ -1452,6 +1745,7 @@ export class SyncClient {
         scopes: input.scopes,
         ...(input.params !== undefined ? { params: input.params } : {}),
       });
+      this.#emitDiagnostics();
       return;
     }
     saveSubscription(this.#db, {
@@ -1462,11 +1756,13 @@ export class SyncClient {
       cursor: -1,
       status: 'active',
     });
+    this.#emitDiagnostics();
   }
 
   unsubscribe(id: string): void {
     this.#requireActive();
     deleteSubscription(this.#db, id);
+    this.#emitDiagnostics();
   }
 
   // -- windowed subscriptions (§4.8) ------------------------------------------
@@ -2092,9 +2388,75 @@ export class SyncClient {
       );
     }
     this.#syncOutstanding = true;
-    return this.#serialize(() => this.#runSync()).finally(() => {
-      this.#syncOutstanding = false;
-    });
+    this.#beginDiagnosticsDeferral();
+    const startedAtMs = this.#now();
+    return this.#serialize(() => this.#runSync())
+      .then(
+        (summary) => {
+          const completedAtMs = this.#now();
+          this.#lastRound = {
+            status: 'succeeded',
+            startedAtMs,
+            completedAtMs,
+            durationMs: Math.max(0, completedAtMs - startedAtMs),
+            counters: this.#diagnosticRoundCounters(summary),
+          };
+          this.#emitDiagnostics();
+          return summary;
+        },
+        (error: unknown) => {
+          const completedAtMs = this.#now();
+          const code = (error as { code?: unknown }).code;
+          this.#lastRound = {
+            status: 'failed',
+            startedAtMs,
+            completedAtMs,
+            durationMs: Math.max(0, completedAtMs - startedAtMs),
+            errorCode:
+              typeof code === 'string'
+                ? this.#diagnosticCode(code)
+                : 'client.unknown_failure',
+          };
+          this.#emitDiagnostics();
+          throw error;
+        },
+      )
+      .finally(() => {
+        this.#syncOutstanding = false;
+        this.#endDiagnosticsDeferral();
+      });
+  }
+
+  #diagnosticRoundCounters(summary: SyncSummary): DiagnosticRoundCounters {
+    return {
+      pushed: summary.pushed,
+      applied: summary.applied.length,
+      rejected: summary.rejected.length,
+      retryable: summary.retryable.length,
+      conflicts: summary.conflicts.length,
+      commitsApplied: summary.commitsApplied,
+      segmentRowsApplied: summary.segmentRowsApplied,
+      bootstrapping: summary.bootstrapping.length,
+      resets: summary.resets.length,
+      revoked: summary.revoked.length,
+      failed: summary.failed.length,
+      deferredCommits: summary.deferredCommits ?? 0,
+    };
+  }
+
+  #transportFailureCode(code: string): boolean {
+    return (
+      code === 'transport.failed' ||
+      code === 'transport.unavailable' ||
+      code === 'sync.transport_failed' ||
+      code === 'client.worker_failed'
+    );
+  }
+
+  #diagnosticCode(code: string): string {
+    return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
+      ? code
+      : 'client.unknown_failure';
   }
 
   async #runSync(): Promise<SyncSummary> {
@@ -2254,7 +2616,23 @@ export class SyncClient {
    */
   #roundTrip(request: Uint8Array): Promise<Uint8Array> {
     const socket = this.#socket;
-    if (socket === undefined) return this.#config.transport(request);
+    if (socket === undefined) {
+      return Promise.resolve()
+        .then(() => this.#config.transport(request))
+        .catch((error: unknown) => {
+          if (
+            error instanceof ClientSyncError ||
+            typeof (error as { code?: unknown })?.code === 'string'
+          ) {
+            throw error;
+          }
+          throw new ClientSyncError(
+            'sync.transport_failed',
+            `transport round failed: ${error instanceof Error ? error.message : String(error)}`,
+            true,
+          );
+        });
+    }
     return new Promise<Uint8Array>((resolve, reject) => {
       // sync() already enforces one round in flight (§8.7).
       this.#pendingRound = {
@@ -2309,6 +2687,7 @@ export class SyncClient {
         this.#socket = undefined;
         this.#presence.clear(); // §8.6.1: presence is per-connection
         this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
+        this.#emitDiagnostics();
       },
     });
     if (this.#securityLifecycle === 'preflight') {
@@ -2319,6 +2698,7 @@ export class SyncClient {
       );
     }
     this.#socket = socket;
+    this.#emitDiagnostics();
   }
 
   disconnectRealtime(): void {
@@ -2326,6 +2706,7 @@ export class SyncClient {
     this.#socket = undefined;
     this.#presence.clear(); // §8.6.1: presence is per-connection
     this.#abortPendingRound('realtime socket disconnected mid-round (§8.7)');
+    this.#emitDiagnostics();
   }
 
   /**
@@ -2505,12 +2886,20 @@ export class SyncClient {
       string,
       ReadonlyMap<number, RejectionDetails>
     >();
+    let lastFinalPushResult: PushResultFrame | undefined;
     for (const frame of message.frames) {
-      if (frame.type !== 'PUSH_RESULT_DETAILS') continue;
-      rejectionDetailsByCommit.set(
-        frame.clientCommitId,
-        new Map(frame.entries.map((entry) => [entry.opIndex, entry.details])),
-      );
+      if (frame.type === 'PUSH_RESULT_DETAILS') {
+        rejectionDetailsByCommit.set(
+          frame.clientCommitId,
+          new Map(frame.entries.map((entry) => [entry.opIndex, entry.details])),
+        );
+      } else if (
+        frame.type === 'PUSH_RESULT' &&
+        commitsById.has(frame.clientCommitId) &&
+        isFinalPushResult(frame)
+      ) {
+        lastFinalPushResult = frame;
+      }
     }
 
     const header = message.frames[0];
@@ -2542,9 +2931,11 @@ export class SyncClient {
     let section: OpenSection | undefined;
     let errorFrame: ClientSyncError | undefined;
     let deltaCursor = -1;
+    let responseOutboxCount: number | undefined;
 
     // Each durable observer transaction emits its own revisioned batch.
     // Async decrypt/download work happens outside SQLite transactions.
+    this.#beginDiagnosticsDeferral();
     try {
       for (const frame of message.frames.slice(1)) {
         switch (frame.type) {
@@ -2558,17 +2949,26 @@ export class SyncClient {
               expiresAtMs: frame.expiresAtMs,
             });
             break;
-          case 'PUSH_RESULT':
-            this.#applyBatch((batch) =>
-              this.#handlePushResult(
-                frame,
-                commitsById,
-                summary,
-                batch,
-                rejectionDetailsByCommit.get(frame.clientCommitId),
-              ),
+          case 'PUSH_RESULT': {
+            let outboxCount =
+              responseOutboxCount ?? listOutbox(this.#db).length;
+            this.#applyBatch(
+              (batch) => {
+                const drained = this.#handlePushResult(
+                  frame,
+                  commitsById,
+                  summary,
+                  batch,
+                  rejectionDetailsByCommit.get(frame.clientCommitId),
+                  frame === lastFinalPushResult,
+                );
+                if (drained) outboxCount -= 1;
+              },
+              () => this.#statusSnapshot(outboxCount),
             );
+            responseOutboxCount = outboxCount;
             break;
+          }
           case 'PUSH_RESULT_DETAILS':
             // Pre-indexed above so companion ordering remains wire-additive.
             break;
@@ -2766,10 +3166,14 @@ export class SyncClient {
         if (errorFrame !== undefined) break;
       }
     } finally {
-      // §7.1: local reads see outbox state applied optimistically — replay
-      // the still-pending commits on top of the freshly applied server state.
-      this.#replayOutbox();
-      this.#reconcileBlobs(false);
+      try {
+        // §7.1: local reads see outbox state applied optimistically — replay
+        // the still-pending commits on top of the freshly applied server state.
+        this.#replayOutbox();
+        this.#reconcileBlobs(false);
+      } finally {
+        this.#endDiagnosticsDeferral();
+      }
     }
 
     if (errorFrame !== undefined) throw errorFrame;
@@ -2799,9 +3203,10 @@ export class SyncClient {
     summary: MutableSummary,
     batch: ChangeAccumulator,
     rejectionDetails: ReadonlyMap<number, RejectionDetails> | undefined,
-  ): void {
+    pruneOutcomes: boolean,
+  ): boolean {
     const commit = commitsById.get(frame.clientCommitId);
-    if (commit === undefined) return;
+    if (commit === undefined) return false;
     if (frame.status === 'applied' || frame.status === 'cached') {
       // §6.3: applied and cached both drain the outbox — cached means
       // "already applied, you may have missed the ack".
@@ -2815,11 +3220,13 @@ export class SyncClient {
         })),
       });
       deleteOutboxCommit(this.#db, frame.clientCommitId);
-      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+      if (pruneOutcomes) {
+        pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+      }
       batch.status();
       batch.outcomes();
       summary.applied.push(frame.clientCommitId);
-      return;
+      return true;
     }
     // rejected
     const cacheMiss = frame.results.some(
@@ -2832,7 +3239,7 @@ export class SyncClient {
       // §6.3: a serving failure, not the commit's outcome — keep the
       // commit queued and retry the identical push later.
       summary.retryable.push(frame.clientCommitId);
-      return;
+      return false;
     }
     const outcomeResults: CommitOperationOutcome[] = [];
     for (const result of frame.results) {
@@ -2881,7 +3288,9 @@ export class SyncClient {
       results: outcomeResults,
       operations: commit.operations,
     });
-    pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+    if (pruneOutcomes) {
+      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+    }
     batch.outcomes();
     // §7.2: remove the rejected optimistic layer. Before-images restore
     // validator-rejected updates even when the server emitted no new COMMIT;
@@ -2891,6 +3300,7 @@ export class SyncClient {
     });
     batch.status();
     summary.rejected.push(frame.clientCommitId);
+    return true;
   }
 
   #decodeServerRow(