@syncular/core 0.0.6-95 → 0.1.0

package/src/http/index.ts

@@ -0,0 +1,365 @@
+/**
+ * @syncular/core/http - HTTP transport for Sync
+ *
+ * Provides:
+ * - a lightweight fetch-based SyncTransport for client runtime use
+ * - a separately exported typed API client for advanced/console use
+ */
+
+import type {
+  SyncBootstrapApplyMode,
+  SyncCombinedRequest,
+  SyncCombinedResponse,
+  SyncTransport,
+  SyncTransportCapabilities,
+  SyncTransportOptions,
+} from '@syncular/core';
+import { SyncTransportError } from '@syncular/core';
+import type { SyncClient } from './api-client';
+import {
+  applySnapshotScopesHeader,
+  bytesToReadableStream,
+  type ClientOptions,
+  executeWithAuthRetry,
+  executeWithTransientNetworkRetry,
+  getErrorMessage,
+  resolveSnapshotChunkRequestUrl,
+  type SyncTransportPath,
+  unwrap,
+} from './shared';
+import {
+  createTransportApiClient,
+  createTransportAuthRetryResolver,
+  HTTP_TRANSPORT_SOURCE,
+  type HttpTransportSource,
+} from './transport-client';
+
+export type {
+  SyncAuthErrorContext,
+  SyncAuthLifecycle,
+  SyncAuthOperation,
+  SyncTransport,
+  SyncTransportOptions,
+} from '@syncular/core';
+export { createApiClient } from './api-client';
+export type { operations } from './generated/api';
+export { type ClientOptions, type SyncClient, type SyncTransportPath, unwrap };
+
+function detectDefaultTransportCapabilities(): SyncTransportCapabilities {
+  const isReactNative =
+    typeof navigator !== 'undefined' && navigator?.product === 'ReactNative';
+  const snapshotChunkReadMode = isReactNative ? 'bytes' : 'stream';
+  const gzipDecompressionMode =
+    !isReactNative && typeof DecompressionStream !== 'undefined'
+      ? 'stream'
+      : 'buffered';
+  const preferredBootstrapApplyMode: SyncBootstrapApplyMode =
+    snapshotChunkReadMode === 'bytes' || gzipDecompressionMode === 'buffered'
+      ? 'per-subscription'
+      : 'single-transaction';
+
+  return {
+    snapshotChunkReadMode,
+    gzipDecompressionMode,
+    preferredBootstrapApplyMode,
+    preferredSnapshotApplyYieldMs: isReactNative ? 0 : false,
+  };
+}
+
+function mergeTransportCapabilities(
+  overrides?: Partial<SyncTransportCapabilities>
+): SyncTransportCapabilities {
+  const defaults = detectDefaultTransportCapabilities();
+  const merged: SyncTransportCapabilities = {
+    ...defaults,
+    ...overrides,
+  };
+
+  if (
+    overrides?.preferredBootstrapApplyMode !== undefined &&
+    overrides?.preferredSnapshotApplyYieldMs !== undefined
+  ) {
+    return merged;
+  }
+
+  const preferredBootstrapApplyMode: SyncBootstrapApplyMode =
+    merged.snapshotChunkReadMode === 'bytes' ||
+    merged.gzipDecompressionMode === 'buffered'
+      ? 'per-subscription'
+      : 'single-transaction';
+
+  return {
+    ...merged,
+    preferredBootstrapApplyMode:
+      overrides?.preferredBootstrapApplyMode ?? preferredBootstrapApplyMode,
+    preferredSnapshotApplyYieldMs:
+      overrides?.preferredSnapshotApplyYieldMs ??
+      (merged.snapshotChunkReadMode === 'bytes' ||
+      merged.gzipDecompressionMode === 'buffered'
+        ? 0
+        : false),
+  };
+}
+
+function shouldUseResponseBodyStream(
+  response: Response,
+  capabilities: SyncTransportCapabilities
+): boolean {
+  if (!response.body) return false;
+  if (capabilities.snapshotChunkReadMode === 'bytes') {
+    return false;
+  }
+  return (
+    typeof (response.body as ReadableStream<Uint8Array>).getReader ===
+    'function'
+  );
+}
+
+export const REACT_NATIVE_TRANSPORT_CAPABILITIES: SyncTransportCapabilities = {
+  snapshotChunkReadMode: 'bytes',
+  gzipDecompressionMode: 'buffered',
+  preferredBootstrapApplyMode: 'per-subscription',
+  preferredSnapshotApplyYieldMs: 0,
+  preferMaterializedSnapshots: true,
+};
+
+export function createHttpTransport(
+  clientOrOptions: SyncClient | ClientOptions
+): SyncTransport {
+  const client = createTransportApiClient(clientOrOptions);
+  const resolveAuthRetry = createTransportAuthRetryResolver(clientOrOptions);
+  const transportOptions =
+    'baseUrl' in clientOrOptions ? clientOrOptions : undefined;
+  const capabilities =
+    'baseUrl' in clientOrOptions
+      ? mergeTransportCapabilities(clientOrOptions.capabilities)
+      : mergeTransportCapabilities();
+
+  const transport: SyncTransport = {
+    capabilities,
+    async sync(
+      request: SyncCombinedRequest,
+      transportRequestOptions?: SyncTransportOptions
+    ): Promise<SyncCombinedResponse> {
+      const { data, error, response } = await executeWithTransientNetworkRetry({
+        execute: (signal) =>
+          executeWithAuthRetry(
+            (retrySignal) => client.sync(request, retrySignal),
+            { ...transportRequestOptions, signal },
+            'sync',
+            resolveAuthRetry
+          ),
+        options: transportRequestOptions,
+      });
+
+      if (error || !data) {
+        throw new SyncTransportError(
+          `Sync failed: ${getErrorMessage(error) || response.statusText}`,
+          response.status
+        );
+      }
+
+      return data as SyncCombinedResponse;
+    },
+
+    async fetchSnapshotChunk(
+      request: {
+        chunkId: string;
+        scopeValues?: Record<string, string | string[]>;
+      },
+      options?: SyncTransportOptions
+    ): Promise<Uint8Array> {
+      if (!transportOptions) {
+        const { data, error, response } = await executeWithAuthRetry(
+          (signal) =>
+            client.getSnapshotChunk(
+              request.chunkId,
+              request.scopeValues,
+              signal
+            ),
+          options,
+          'snapshotChunk',
+          resolveAuthRetry
+        );
+
+        if (error || !data) {
+          throw new SyncTransportError(
+            `Snapshot chunk download failed: ${getErrorMessage(error) || response.statusText}`,
+            response.status
+          );
+        }
+
+        return new Uint8Array(await (data as Blob).arrayBuffer());
+      }
+
+      const fetchImpl = transportOptions.fetch ?? globalThis.fetch;
+      const requestUrl = resolveSnapshotChunkRequestUrl(
+        transportOptions.baseUrl,
+        request.chunkId,
+        request.scopeValues
+      );
+
+      const performRequest = async (
+        signal?: AbortSignal
+      ): Promise<Response> => {
+        const headers = new Headers();
+        applySnapshotScopesHeader(headers, request.scopeValues);
+        const extraHeaders = await transportOptions.getHeaders?.();
+        if (extraHeaders) {
+          for (const [key, value] of Object.entries(extraHeaders)) {
+            headers.set(key, value);
+          }
+        }
+        if (!headers.has('x-syncular-transport-path')) {
+          headers.set(
+            'x-syncular-transport-path',
+            transportOptions.transportPath ?? 'direct'
+          );
+        }
+        return fetchImpl(requestUrl, {
+          method: 'GET',
+          headers,
+          ...(signal ? { signal } : {}),
+        });
+      };
+
+      let response = await performRequest(options?.signal);
+      if (response.status === 401 || response.status === 403) {
+        const shouldRetry = await resolveAuthRetry(
+          {
+            operation: 'snapshotChunk',
+            status: response.status,
+          },
+          options
+        );
+        if (shouldRetry) {
+          response = await performRequest(options?.signal);
+        }
+      }
+
+      if (!response.ok) {
+        let reason = response.statusText || 'Request failed';
+        try {
+          const maybeJson = (await response.json()) as
+            | { error?: unknown; message?: unknown }
+            | undefined;
+          reason = getErrorMessage(maybeJson) || reason;
+        } catch {
+          // ignore parse failures
+        }
+        throw new SyncTransportError(
+          `Snapshot chunk download failed: ${reason}`,
+          response.status
+        );
+      }
+
+      return new Uint8Array(await response.arrayBuffer());
+    },
+
+    async fetchSnapshotChunkStream(
+      request: {
+        chunkId: string;
+        scopeValues?: Record<string, string | string[]>;
+      },
+      options?: SyncTransportOptions
+    ): Promise<ReadableStream<Uint8Array>> {
+      if (!transportOptions) {
+        const bytes = await this.fetchSnapshotChunk(request, options);
+        return bytesToReadableStream(bytes);
+      }
+
+      const fetchImpl = transportOptions.fetch ?? globalThis.fetch;
+      const requestUrl = resolveSnapshotChunkRequestUrl(
+        transportOptions.baseUrl,
+        request.chunkId,
+        request.scopeValues
+      );
+
+      const performRequest = async (
+        signal?: AbortSignal
+      ): Promise<Response> => {
+        const headers = new Headers();
+        applySnapshotScopesHeader(headers, request.scopeValues);
+        const extraHeaders = await transportOptions.getHeaders?.();
+        if (extraHeaders) {
+          for (const [key, value] of Object.entries(extraHeaders)) {
+            headers.set(key, value);
+          }
+        }
+        if (!headers.has('x-syncular-transport-path')) {
+          headers.set(
+            'x-syncular-transport-path',
+            transportOptions.transportPath ?? 'direct'
+          );
+        }
+        return fetchImpl(requestUrl, {
+          method: 'GET',
+          headers,
+          ...(signal ? { signal } : {}),
+        });
+      };
+
+      let response = await performRequest(options?.signal);
+      if (response.status === 401 || response.status === 403) {
+        const shouldRetry = await resolveAuthRetry(
+          {
+            operation: 'snapshotChunkStream',
+            status: response.status,
+          },
+          options
+        );
+        if (shouldRetry) {
+          response = await performRequest(options?.signal);
+        }
+      }
+
+      if (!response.ok) {
+        let reason = response.statusText || 'Request failed';
+        try {
+          const maybeJson = (await response.json()) as
+            | { error?: unknown; message?: unknown }
+            | undefined;
+          reason = getErrorMessage(maybeJson) || reason;
+        } catch {
+          // ignore parse failures
+        }
+        throw new SyncTransportError(
+          `Snapshot chunk download failed: ${reason}`,
+          response.status
+        );
+      }
+
+      if (!shouldUseResponseBodyStream(response, capabilities)) {
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        return bytesToReadableStream(bytes);
+      }
+
+      return response.body as ReadableStream<Uint8Array>;
+    },
+  };
+
+  Object.defineProperty(transport, HTTP_TRANSPORT_SOURCE, {
+    configurable: false,
+    enumerable: false,
+    value: clientOrOptions as HttpTransportSource,
+    writable: false,
+  });
+
+  return transport;
+}
+
+export function createReactNativeHttpTransport(
+  clientOrOptions: SyncClient | ClientOptions
+): SyncTransport {
+  if (!('baseUrl' in clientOrOptions)) {
+    return createHttpTransport(clientOrOptions);
+  }
+
+  return createHttpTransport({
+    ...clientOrOptions,
+    capabilities: {
+      ...REACT_NATIVE_TRANSPORT_CAPABILITIES,
+      ...clientOrOptions.capabilities,
+    },
+  });
+}

package/src/http/shared.ts

@@ -0,0 +1,220 @@
+import type {
+  ScopeValues,
+  SyncAuthErrorContext,
+  SyncAuthLifecycle,
+  SyncAuthOperation,
+  SyncTransportCapabilities,
+  SyncTransportOptions,
+} from '@syncular/core';
+import { resolveUrlFromBase } from '@syncular/core';
+
+export type SyncTransportPath = 'direct' | 'relay';
+
+export interface ClientOptions {
+  /** Base URL for the API (e.g., 'https://api.example.com') */
+  baseUrl: string;
+  /** Function to get headers for requests (e.g., for auth tokens) */
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+  /** Shared auth lifecycle for all transport operations. */
+  authLifecycle?: SyncAuthLifecycle;
+  /** Custom fetch implementation (defaults to globalThis.fetch) */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Transport path telemetry sent to the server.
+   * Defaults to 'direct'.
+   */
+  transportPath?: SyncTransportPath;
+  /**
+   * Explicit runtime capabilities override.
+   * Use this to avoid environment sniffing in runtimes like React Native.
+   */
+  capabilities?: Partial<SyncTransportCapabilities>;
+}
+
+export type ApiResult<T> = {
+  data?: T;
+  error?: unknown;
+  response: Response;
+};
+
+export type ResolveAuthRetry = (
+  context: SyncAuthErrorContext,
+  options?: SyncTransportOptions
+) => Promise<boolean>;
+
+const TRANSIENT_NETWORK_RETRY_DELAYS_MS = [75, 150, 300] as const;
+
+class ApiResponseError extends Error {
+  constructor(
+    message: string,
+    public readonly error?: unknown
+  ) {
+    super(message);
+    this.name = 'ApiResponseError';
+  }
+}
+
+export function getErrorMessage(error: unknown): string {
+  if (error && typeof error === 'object' && 'error' in error) {
+    const inner = (error as { error: unknown }).error;
+    if (typeof inner === 'string') return inner;
+  }
+  if (error && typeof error === 'object' && 'message' in error) {
+    const msg = (error as { message: unknown }).message;
+    if (typeof msg === 'string') return msg;
+  }
+  return 'Request failed';
+}
+
+export async function unwrap<T>(
+  promise: Promise<{ data?: T; error?: unknown }>
+): Promise<T> {
+  const { data, error } = await promise;
+  if (error || !data) {
+    throw new ApiResponseError(getErrorMessage(error), error);
+  }
+  return data;
+}
+
+export async function executeWithAuthRetry<T>(
+  execute: (signal?: AbortSignal) => Promise<ApiResult<T>>,
+  options: SyncTransportOptions | undefined,
+  operation: SyncAuthOperation,
+  resolveAuthRetry: ResolveAuthRetry
+): Promise<ApiResult<T>> {
+  const first = await execute(options?.signal);
+  if (first.response.status !== 401 && first.response.status !== 403) {
+    return first;
+  }
+  const shouldRetry = await resolveAuthRetry(
+    { operation, status: first.response.status },
+    options
+  );
+  if (!shouldRetry) {
+    return first;
+  }
+
+  return execute(options?.signal);
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === 'AbortError';
+}
+
+function isTransientNetworkError(error: unknown): boolean {
+  if (isAbortError(error)) return false;
+
+  const message =
+    error instanceof Error
+      ? error.message.toLowerCase()
+      : String(error).toLowerCase();
+
+  return (
+    message.includes('fetch failed') ||
+    message.includes('network') ||
+    message.includes('socket') ||
+    message.includes('econnreset') ||
+    message.includes('econnrefused') ||
+    message.includes('connection refused') ||
+    message.includes('connection reset') ||
+    message.includes('terminated') ||
+    message.includes('eof')
+  );
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+export async function executeWithTransientNetworkRetry<T>(args: {
+  execute: (signal?: AbortSignal) => Promise<T>;
+  options?: SyncTransportOptions;
+}): Promise<T> {
+  let lastError: unknown;
+
+  for (
+    let attemptIndex = 0;
+    attemptIndex <= TRANSIENT_NETWORK_RETRY_DELAYS_MS.length;
+    attemptIndex += 1
+  ) {
+    try {
+      return await args.execute(args.options?.signal);
+    } catch (error) {
+      lastError = error;
+      if (!isTransientNetworkError(error) || args.options?.signal?.aborted) {
+        throw error;
+      }
+
+      const delayMs = TRANSIENT_NETWORK_RETRY_DELAYS_MS[attemptIndex];
+      if (delayMs === undefined) {
+        throw error;
+      }
+
+      await delay(delayMs);
+
+      if (args.options?.signal?.aborted) {
+        throw error;
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+export const SNAPSHOT_SCOPES_HEADER = 'x-syncular-snapshot-scopes';
+
+export function resolveRequestUrl(baseUrl: string, path: string): string {
+  return resolveUrlFromBase(
+    baseUrl,
+    path,
+    typeof location === 'undefined' ? undefined : location.origin
+  );
+}
+
+export function bytesToReadableStream(
+  bytes: Uint8Array
+): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+export function encodeSnapshotScopes(
+  scopeValues: ScopeValues | undefined
+): string | null {
+  if (!scopeValues) return null;
+  if (Object.keys(scopeValues).length === 0) return null;
+  return JSON.stringify(scopeValues);
+}
+
+export function applySnapshotScopesHeader(
+  headers: Headers,
+  scopeValues: ScopeValues | undefined
+): void {
+  const encodedScopes = encodeSnapshotScopes(scopeValues);
+  if (!encodedScopes) return;
+  headers.set(SNAPSHOT_SCOPES_HEADER, encodedScopes);
+}
+
+export function resolveSnapshotChunkRequestUrl(
+  baseUrl: string,
+  chunkId: string,
+  scopeValues: ScopeValues | undefined
+): string {
+  const requestUrl = new URL(
+    resolveRequestUrl(
+      baseUrl,
+      `/sync/snapshot-chunks/${encodeURIComponent(chunkId)}`
+    )
+  );
+  const encodedScopes = encodeSnapshotScopes(scopeValues);
+  if (encodedScopes) {
+    requestUrl.searchParams.set('scopes', encodedScopes);
+  }
+  return requestUrl.toString();
+}