@syncular/client 0.25.1 → 0.26.0

package/src/errors.ts

@@ -1,3 +1,5 @@
+import type { RealtimeState } from './diagnostics';
+
 /** A persistent local store is temporarily owned by another live engine. */
 export const STORAGE_BUSY_CODE = 'client.storage_busy';
 
@@ -10,13 +12,19 @@ export const STORAGE_CORRUPT_CODE = 'client.storage_corrupt';
 /** A local read hit SQLITE_IOERR (SPEC §7.5). */
 export const STORAGE_IO_CODE = 'client.storage_io';
 
+/** SPEC §8.8: a round under `realtimePolicy: 'required'` found no socket. */
+export const REALTIME_UNAVAILABLE_CODE = 'sync.realtime_unavailable';
+
+/** SPEC §8.8: a connected socket ended without a deliberate disconnect. */
+export const REALTIME_LOST_CODE = 'client.realtime_lost';
+
 /**
  * Client-side errors. Protocol codes from the SPEC.md §10 catalog are surfaced
  * unchanged. Host/runtime-only conditions may use the separate `client.*`
  * namespace and never travel on the wire.
  */
 export class ClientSyncError extends Error {
-  override readonly name = 'ClientSyncError';
+  override readonly name: string = 'ClientSyncError';
   readonly code: string;
   readonly retryable: boolean;
 
@@ -27,6 +35,35 @@ export class ClientSyncError extends Error {
   }
 }
 
+/**
+ * SPEC §8.8: the `required` realtime policy refused a round because the
+ * socket is not connected. `state` is the availability state that refused
+ * (`connecting`, `lost`, `refused`, or `disconnected`), `reasonCode` is the
+ * stable code behind a `lost` or `refused` state, and `retryDelayMs` is the
+ * delay of the background retry intent the client scheduled with this throw.
+ */
+export class RealtimeUnavailableError extends ClientSyncError {
+  override readonly name = 'RealtimeUnavailableError';
+  readonly state: RealtimeState;
+  readonly reasonCode: string | undefined;
+  readonly retryDelayMs: number;
+
+  constructor(
+    state: RealtimeState,
+    reasonCode: string | undefined,
+    retryDelayMs: number,
+  ) {
+    super(
+      REALTIME_UNAVAILABLE_CODE,
+      'realtime is required and the realtime socket is not connected',
+      true,
+    );
+    this.state = state;
+    this.reasonCode = reasonCode;
+    this.retryDelayMs = retryDelayMs;
+  }
+}
+
 /**
  * SPEC §7.5: classify a local SQLite read failure by the numeric result code
  * the driver exposes (bun:sqlite `errno`, node:sqlite `errcode`, sqlite-wasm

package/src/http.ts

@@ -35,10 +35,24 @@ async function throwHttpError(response: Response): Promise<never> {
 }
 
 export interface HttpTransportOptions {
-  readonly headers?: Readonly<Record<string, string>>;
+  /**
+   * Host auth headers. A function is read on every request, so a rotated
+   * token applies from the next request on. Signed-URL fetches never
+   * carry them (§5.4, §5.9.5).
+   */
+  readonly headers?:
+    | Readonly<Record<string, string>>
+    | (() => Readonly<Record<string, string>>);
   readonly fetch?: typeof fetch;
 }
 
+function hostHeaders(
+  options: HttpTransportOptions | undefined,
+): Readonly<Record<string, string>> | undefined {
+  const headers = options?.headers;
+  return typeof headers === 'function' ? headers() : headers;
+}
+
 /** POST `<mount>/sync` with SSP2 bodies (§1.1). */
 export function httpSyncTransport(
   syncUrl: string,
@@ -50,7 +64,7 @@ export function httpSyncTransport(
       method: 'POST',
       headers: {
         'Content-Type': SSP2_CONTENT_TYPE,
-        ...options?.headers,
+        ...hostHeaders(options),
       },
       body: request.slice().buffer as ArrayBuffer,
     });
@@ -70,7 +84,7 @@ export function httpRemoteOperationTransport(
       method: 'POST',
       headers: {
         'Content-Type': 'application/vnd.syncular.operations.v1+json',
-        ...options?.headers,
+        ...hostHeaders(options),
       },
       body: request.slice().buffer as ArrayBuffer,
     });
@@ -188,7 +202,7 @@ export function httpSegmentDownloader(
       {
         headers: {
           'X-Syncular-Scopes': request.requestedScopesJson,
-          ...options?.headers,
+          ...hostHeaders(options),
         },
       },
     );
@@ -232,7 +246,7 @@ export function httpBlobTransport(
         method: 'PUT',
         headers: {
           'Content-Type': mediaType ?? 'application/octet-stream',
-          ...options?.headers,
+          ...hostHeaders(options),
         },
         body: bytes.slice().buffer as ArrayBuffer,
       });
@@ -240,7 +254,7 @@ export function httpBlobTransport(
     },
     download: async (blobId) => {
       const response = await doFetch(blobUrl(blobId), {
-        headers: { ...options?.headers },
+        headers: { ...hostHeaders(options) },
       });
       if (!response.ok) await throwHttpError(response);
       // §5.9.5 always-issue: a JSON body with `url` means presigned delivery;
@@ -284,7 +298,7 @@ export function httpBlobTransport(
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
-          ...options?.headers,
+          ...hostHeaders(options),
         },
         body: JSON.stringify({
           byteLength,

package/src/reactive-store.ts

@@ -360,17 +360,38 @@ class ObservationCache {
   }
 }
 
+const EMPTY_ROWS: readonly never[] = Object.freeze([]);
+const unreadQuerySnapshots = new Map<string, LiveQueryResult<never>>();
+
+/** One frozen snapshot per phase and availability for entries that have no
+ * successful read, so switching between unread entries keeps the snapshot and
+ * `rows` identity. */
+function unreadQuerySnapshot(
+  phase: LiveQueryPhase,
+  availability: SyncAvailability,
+): LiveQueryResult<never> {
+  const key = canonicalValue([phase, availability]);
+  let snapshot = unreadQuerySnapshots.get(key);
+  if (snapshot === undefined) {
+    snapshot = Object.freeze({
+      rows: EMPTY_ROWS,
+      phase,
+      revision: undefined,
+      error: undefined,
+      isRefreshing: false,
+      availability,
+    });
+    unreadQuerySnapshots.set(key, snapshot);
+  }
+  return snapshot;
+}
+
 class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
   readonly #owner = Symbol('query-window-claim');
   readonly #listeners = new Set<() => void>();
-  #state: LiveQueryResult<Row> = {
-    rows: [],
-    phase: 'loading',
-    revision: undefined,
-    error: undefined,
-    isRefreshing: false,
-    availability: { state: 'ready' },
-  };
+  #state: LiveQueryResult<Row> = unreadQuerySnapshot('loading', {
+    state: 'ready',
+  });
   #delegate: QueryEntry<Row> | undefined;
   #generation = 0;
   #scheduled = false;
@@ -476,14 +497,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     this.#desiredRevision = 0n;
     this.#claimError = undefined;
     this.#claimPending = false;
-    this.#state = {
-      rows: [],
-      phase: 'loading',
-      revision: undefined,
-      error: undefined,
-      isRefreshing: false,
-      availability: { state: 'ready' },
-    };
+    this.#state = unreadQuerySnapshot('loading', { state: 'ready' });
   }
 
   dispose(): void {
@@ -513,7 +527,13 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     ) {
       return;
     }
-    this.#state = next;
+    this.#state =
+      next.revision === undefined &&
+      next.rows.length === 0 &&
+      next.error === undefined &&
+      !next.isRefreshing
+        ? unreadQuerySnapshot(next.phase, next.availability)
+        : next;
     for (const listener of this.#listeners) listener();
   }
 

package/src/realtime-supervisor.ts

@@ -529,7 +529,10 @@ export class RealtimeSupervisor {
     if (this.#stopped) return;
     this.#diagnosticConnectivity = snapshot.host.connectivity;
     this.#diagnosticSecurity = snapshot.securityLifecycle;
-    if (snapshot.host.realtime === 'unsupported') {
+    if (
+      snapshot.host.realtime === 'unsupported' ||
+      snapshot.host.realtime === 'disabled'
+    ) {
       const disconnect =
         this.#connected || this.#transportConnected || this.#connecting;
       this.#realtimeSupported = false;
@@ -563,7 +566,18 @@ export class RealtimeSupervisor {
       void this.#adoptConnectedTransport();
       return;
     }
-    if (snapshot.host.realtime === 'disconnected') {
+    if (snapshot.host.realtime === 'connecting') {
+      // An attempt is already in flight; the supervisor's own #connect (or
+      // the host's direct call) owns the outcome.
+      this.#transportConnected = false;
+      this.#connected = false;
+      return;
+    }
+    if (
+      snapshot.host.realtime === 'disconnected' ||
+      snapshot.host.realtime === 'lost' ||
+      snapshot.host.realtime === 'refused'
+    ) {
       this.#transportConnected = false;
       this.#connected = false;
       if (this.#connecting) return;

package/src/worker-entry.ts

@@ -57,9 +57,14 @@ export interface SyncWorkerOverrides {
   readonly createSegments?: (
     config: WorkerInitConfig,
   ) => SegmentDownloader | undefined;
+  /**
+   * Custom realtime connector, e.g. one that mints a fresh ticket per
+   * connection attempt. `headers` reads the current host auth set.
+   */
   readonly createRealtime?: (
     config: WorkerInitConfig,
     clientId: string,
+    headers: () => Readonly<Record<string, string>>,
   ) => RealtimeConnector | undefined;
 }
 
@@ -129,6 +134,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
   let client: SyncClient | undefined;
   let database: ClientDatabase | undefined;
   let offline = false;
+  let headers: Readonly<Record<string, string>> = {};
   let closed = false;
 
   // -- one sync loop: RPC-driven and auto-driven rounds serialize ----------
@@ -266,6 +272,8 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       );
     }
     autoSync = config.autoSync ?? true;
+    headers = config.headers ?? {};
+    const http = { headers: () => headers };
 
     for (let attempt = 0; ; attempt++) {
       try {
@@ -297,18 +305,18 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     const transport = gateOffline(
       overrides.createTransport !== undefined
         ? overrides.createTransport(config)
-        : httpSyncTransport(config.endpoints.syncUrl),
+        : httpSyncTransport(config.endpoints.syncUrl, http),
     );
     const segments =
       overrides.createSegments !== undefined
         ? overrides.createSegments(config)
         : config.endpoints.segmentsUrl !== undefined
-          ? httpSegmentDownloader(config.endpoints.segmentsUrl)
+          ? httpSegmentDownloader(config.endpoints.segmentsUrl, http)
           : undefined;
     // §5.9 blob transport: only when a blobs URL is configured.
     const blobs =
       config.endpoints.blobsUrl !== undefined
-        ? httpBlobTransport(config.endpoints.blobsUrl)
+        ? httpBlobTransport(config.endpoints.blobsUrl, http)
         : undefined;
 
     // Realtime needs the (possibly persisted) clientId for the
@@ -341,6 +349,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       },
       ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
       ...(config.limits !== undefined ? { limits: config.limits } : {}),
+      ...(config.realtimePolicy !== undefined
+        ? { realtimePolicy: config.realtimePolicy }
+        : {}),
       ...(config.encryption !== undefined
         ? { encryption: encryptionConfigFromKeyring(config.encryption) }
         : {}),
@@ -392,7 +403,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     await started.start();
     realtimeConnector =
       overrides.createRealtime !== undefined
-        ? overrides.createRealtime(config, started.clientId)
+        ? overrides.createRealtime(config, started.clientId, http.headers)
         : config.endpoints.realtimeUrl !== undefined
           ? webSocketRealtimeConnector(
               config.endpoints.realtimeUrl.replace(
@@ -490,6 +501,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     presence: (scopeKey) => requireClient().presence(scopeKey),
     uploadBlob: (bytes, options) => requireClient().uploadBlob(bytes, options),
     fetchBlob: (blobIdOrRef) => requireClient().fetchBlob(blobIdOrRef),
+    setHeaders: (next) => {
+      headers = next;
+    },
     setOffline: (value) => {
       offline = value;
       if (offline) client?.disconnectRealtime();

package/src/worker-host.ts

@@ -50,6 +50,7 @@ import {
   type ClientDiagnosticsListener,
   type ClientDiagnosticsRequest,
   type ClientDiagnosticsSnapshot,
+  type RealtimePolicy,
   withClientDiagnosticsHost,
 } from './diagnostics';
 import type { EncryptionKeyringConfig } from './encryption';
@@ -180,12 +181,23 @@ export interface SyncClientHandleConfig {
   readonly schema: ClientSchema;
   readonly database: WorkerDatabaseInit;
   readonly endpoints: WorkerEndpoints;
+  /**
+   * Host auth headers for sync, segment, and blob requests (e.g.
+   * `Authorization`). Rotate with `setHeaders`. Realtime authenticates
+   * through `realtimeUrl`, because WebSockets cannot carry headers.
+   */
+  readonly headers?: Readonly<Record<string, string>>;
   /** Structured-clone-safe E2EE keyring installed only in the leader worker. */
   readonly encryption?: EncryptionKeyringConfig;
   /** Open the worker-owned replica behind the fail-closed security gate. */
   readonly securityPreflight?: boolean;
   readonly clientId?: string;
   readonly limits?: SyncClientLimits;
+  /**
+   * SPEC §8.8 realtime policy for the worker-owned core, forwarded into
+   * `WorkerInitConfig`. Absent ⇒ `optional`.
+   */
+  readonly realtimePolicy?: RealtimePolicy;
   /**
    * RFC 0005 previous-version context, forwarded into the worker's
    * `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
@@ -689,6 +701,19 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
     return this.#call('fetchBlob', [blobIdOrRef]);
   }
 
+  /**
+   * Replace the full host auth header set. The next HTTP request uses it;
+   * a live realtime socket keeps its handshake credentials. A follower
+   * forwards to the leader and keeps the set for its own promotion.
+   */
+  setHeaders(headers: Readonly<Record<string, string>>): Promise<void> {
+    this.__headers = headers;
+    return this.#call('setHeaders', [headers]);
+  }
+
+  /** @internal — the latest `setHeaders` set, carried into a promotion. */
+  __headers: Readonly<Record<string, string>> | undefined;
+
   /** Sever/restore transport + realtime inside the worker (demos). */
   setOffline(offline: boolean): Promise<void> {
     return this.#call('setOffline', [offline]);
@@ -839,11 +864,15 @@ async function startWorkerCore(options: {
   }
 }
 
-function buildInitConfig(config: SyncClientHandleConfig): WorkerInitConfig {
+function buildInitConfig(
+  config: SyncClientHandleConfig,
+  headers = config.headers,
+): WorkerInitConfig {
   return {
     schema: config.schema,
     database: config.database,
     endpoints: config.endpoints,
+    ...(headers !== undefined ? { headers } : {}),
     ...(config.encryption !== undefined
       ? { encryption: config.encryption }
       : {}),
@@ -852,6 +881,9 @@ function buildInitConfig(config: SyncClientHandleConfig): WorkerInitConfig {
       : {}),
     ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
     ...(config.limits !== undefined ? { limits: config.limits } : {}),
+    ...(config.realtimePolicy !== undefined
+      ? { realtimePolicy: config.realtimePolicy }
+      : {}),
     ...(config.previousVersionContext !== undefined
       ? { previousVersionContext: config.previousVersionContext }
       : {}),
@@ -1086,7 +1118,7 @@ async function bootFollower(
     try {
       const core = await startWorkerCore({
         config,
-        initConfig: buildInitConfig(config),
+        initConfig: buildInitConfig(config, handle.__headers ?? config.headers),
         lease,
         dispatchEvent: (event) => {
           fireConfigCallbacks(config, event);

package/src/worker-protocol.ts

@@ -34,7 +34,7 @@ import type {
   WindowState,
 } from './client';
 import type { SqlRow, SqlValue } from './database';
-import type { ClientDiagnosticsSnapshot } from './diagnostics';
+import type { ClientDiagnosticsSnapshot, RealtimePolicy } from './diagnostics';
 import type { EncryptionKeyringConfig } from './encryption';
 import type { ClientChangeBatch, LocalRevision } from './invalidation';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge';
@@ -102,12 +102,23 @@ export interface WorkerInitConfig {
   readonly schema: ClientSchema;
   readonly database: WorkerDatabaseInit;
   readonly endpoints: WorkerEndpoints;
+  /**
+   * Host auth headers for sync, segment, and blob requests. `setHeaders`
+   * replaces the whole set at runtime. WebSockets cannot carry headers, so
+   * realtime authenticates through `realtimeUrl` (cookie or ticket).
+   */
+  readonly headers?: Readonly<Record<string, string>>;
   /** Portable raw keyring installed inside the worker-owned client core. */
   readonly encryption?: EncryptionKeyringConfig;
   /** Open the worker-owned replica behind the fail-closed security gate. */
   readonly securityPreflight?: boolean;
   readonly clientId?: string;
   readonly limits?: SyncClientLimits;
+  /**
+   * SPEC §8.8 realtime policy for the worker-owned core; forwarded verbatim.
+   * Absent ⇒ `optional` (a connected socket, otherwise `POST /sync`).
+   */
+  readonly realtimePolicy?: RealtimePolicy;
   /**
    * RFC 0005 previous-version context, forwarded verbatim into the worker's
    * `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
@@ -190,6 +201,8 @@ export interface WorkerApi extends Omit<
     options?: { readonly mediaType?: string; readonly name?: string },
   ): Promise<BlobRef>;
   fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
+  /** Replace the host auth header set; the next HTTP request uses it. */
+  setHeaders(headers: Readonly<Record<string, string>>): void;
   /** Sever/restore the transport + realtime (offline simulation, demos). */
   setOffline(offline: boolean): void;
   close(): Promise<void>;