@syncular/client 0.25.2 → 0.26.0

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/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>;