@syncular/core 0.1.3 → 0.2.0

package/src/http/index.ts

@@ -1,365 +0,0 @@
-/**
- * @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

@@ -1,220 +0,0 @@
-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();
-}