@syncular/server 0.1.2 → 0.2.0

package/src/service-worker/index.ts

@@ -1,773 +0,0 @@
-import {
-  createSyncularErrorResponse,
-  type SyncTransport,
-} from '@syncular/core';
-import { type ClientOptions, createHttpTransport } from '@syncular/core/http';
-
-export const SERVICE_WORKER_WAKE_CHANNEL = 'syncular-sw-realtime-v1';
-export const SERVICE_WORKER_WAKE_MESSAGE_TYPE =
-  'syncular:service-worker:wakeup';
-
-export type ServiceWorkerConnectionState =
-  | 'disconnected'
-  | 'connecting'
-  | 'connected';
-
-export interface ServiceWorkerWakeMessage {
-  type: string;
-  timestamp: number;
-  cursor?: number;
-  sourceClientId?: string;
-}
-
-export function isServiceWorkerWakeMessage(
-  value: unknown
-): value is ServiceWorkerWakeMessage {
-  if (!value || typeof value !== 'object') return false;
-  const record = value as Record<string, unknown>;
-  if (record.type !== SERVICE_WORKER_WAKE_MESSAGE_TYPE) return false;
-  if (
-    typeof record.timestamp !== 'number' ||
-    !Number.isFinite(record.timestamp)
-  ) {
-    return false;
-  }
-  if (
-    record.cursor !== undefined &&
-    (typeof record.cursor !== 'number' || !Number.isFinite(record.cursor))
-  ) {
-    return false;
-  }
-  if (
-    record.sourceClientId !== undefined &&
-    (typeof record.sourceClientId !== 'string' ||
-      record.sourceClientId.length === 0)
-  ) {
-    return false;
-  }
-  return true;
-}
-
-export interface ServiceWorkerWakeTransport extends SyncTransport {
-  connect(
-    args: { clientId: string },
-    onEvent: (event: {
-      event: 'sync';
-      data: { cursor?: number; timestamp: number };
-    }) => void,
-    onStateChange?: (state: ServiceWorkerConnectionState) => void
-  ): () => void;
-  getConnectionState(): ServiceWorkerConnectionState;
-  reconnect(): void;
-}
-
-export interface ServiceWorkerWakeTransportOptions extends ClientOptions {
-  channelName?: string;
-  includeServiceWorkerMessages?: boolean;
-  isWakeMessage?: (payload: unknown) => payload is ServiceWorkerWakeMessage;
-}
-
-export function createServiceWorkerWakeTransport(
-  options: ServiceWorkerWakeTransportOptions
-): ServiceWorkerWakeTransport {
-  const httpTransport = createHttpTransport({
-    baseUrl: options.baseUrl,
-    getHeaders: options.getHeaders,
-    authLifecycle: options.authLifecycle,
-    fetch: options.fetch,
-    transportPath: options.transportPath,
-  });
-
-  const channelName = options.channelName ?? SERVICE_WORKER_WAKE_CHANNEL;
-  const includeServiceWorkerMessages =
-    options.includeServiceWorkerMessages ?? true;
-  const wakeMessageGuard = options.isWakeMessage ?? isServiceWorkerWakeMessage;
-
-  let connectionState: ServiceWorkerConnectionState = 'disconnected';
-  let currentClientId: string | null = null;
-  let eventCallback:
-    | ((event: {
-        event: 'sync';
-        data: { cursor?: number; timestamp: number };
-      }) => void)
-    | null = null;
-  let stateCallback: ((state: ServiceWorkerConnectionState) => void) | null =
-    null;
-  let channel: BroadcastChannel | null = null;
-  let swMessageListener: ((event: MessageEvent<unknown>) => void) | null = null;
-
-  const setConnectionState = (state: ServiceWorkerConnectionState): void => {
-    if (connectionState === state) return;
-    connectionState = state;
-    stateCallback?.(state);
-  };
-
-  const handleWakeMessage = (payload: unknown): void => {
-    if (!eventCallback) return;
-    if (!wakeMessageGuard(payload)) return;
-    if (currentClientId && payload.sourceClientId === currentClientId) return;
-
-    eventCallback({
-      event: 'sync',
-      data: {
-        cursor: payload.cursor,
-        timestamp: payload.timestamp,
-      },
-    });
-  };
-
-  const detachListeners = (): void => {
-    if (channel) {
-      channel.onmessage = null;
-      channel.close();
-      channel = null;
-    }
-
-    if (
-      swMessageListener &&
-      typeof navigator !== 'undefined' &&
-      'serviceWorker' in navigator
-    ) {
-      navigator.serviceWorker.removeEventListener('message', swMessageListener);
-      swMessageListener = null;
-    }
-  };
-
-  const attachListeners = (): boolean => {
-    detachListeners();
-    let attached = false;
-
-    if (typeof BroadcastChannel !== 'undefined') {
-      channel = new BroadcastChannel(channelName);
-      channel.onmessage = (event) => {
-        handleWakeMessage(event.data);
-      };
-      attached = true;
-    }
-
-    if (
-      includeServiceWorkerMessages &&
-      typeof navigator !== 'undefined' &&
-      'serviceWorker' in navigator
-    ) {
-      swMessageListener = (event: MessageEvent<unknown>) => {
-        handleWakeMessage(event.data);
-      };
-      navigator.serviceWorker.addEventListener('message', swMessageListener);
-      attached = true;
-    }
-
-    return attached;
-  };
-
-  return {
-    ...httpTransport,
-
-    connect(args, onEvent, onStateChange) {
-      currentClientId = args.clientId;
-      eventCallback = onEvent;
-      stateCallback = onStateChange ?? null;
-
-      setConnectionState('connecting');
-      const attached = attachListeners();
-      setConnectionState(attached ? 'connected' : 'disconnected');
-
-      return () => {
-        detachListeners();
-        currentClientId = null;
-        eventCallback = null;
-        stateCallback = null;
-        setConnectionState('disconnected');
-      };
-    },
-
-    getConnectionState() {
-      return connectionState;
-    },
-
-    reconnect() {
-      if (!eventCallback) return;
-      setConnectionState('connecting');
-      const attached = attachListeners();
-      setConnectionState(attached ? 'connected' : 'disconnected');
-    },
-  };
-}
-
-export interface ServiceWorkerServer {
-  shouldHandleRequest(request: Request, localOrigin?: string): boolean;
-  handleRequest(request: Request): Promise<Response>;
-  captureWakeContext(request: Request): Promise<unknown>;
-  resolveWakeMessage(args: {
-    request: Request;
-    response: Response;
-    wakeContext: unknown;
-  }): Promise<ServiceWorkerWakeMessage | null>;
-}
-
-export interface ResolveWakeMessageArgs {
-  request: Request;
-  response: Response;
-  wakeContext: unknown;
-}
-
-export interface ServiceWorkerSyncWakeContext {
-  sourceClientId?: string;
-}
-
-export interface ServiceWorkerSyncWakeMessageResolverOptions {
-  syncPathnames?: string[];
-}
-
-export interface CreateServiceWorkerServerOptions {
-  handleRequest: (request: Request) => Promise<Response> | Response;
-  apiPrefix?: string;
-  serviceWorkerScriptPath?: string;
-  syncPathnames?: string[];
-  captureWakeContext?: (request: Request) => Promise<unknown>;
-  resolveWakeMessage?: (
-    args: ResolveWakeMessageArgs
-  ) => Promise<ServiceWorkerWakeMessage | null>;
-  onError?: (error: unknown, request: Request) => Promise<Response> | Response;
-}
-
-function normalizePrefix(prefix: string | undefined): string {
-  const raw = (prefix ?? '/api').trim();
-  if (!raw) return '/api';
-  const withSlash = raw.startsWith('/') ? raw : `/${raw}`;
-  const trimmed = withSlash.replace(/\/+$/, '');
-  return trimmed || '/';
-}
-
-function pathStartsWithPrefix(pathname: string, prefix: string): boolean {
-  return pathname === prefix || pathname.startsWith(`${prefix}/`);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-async function getSyncPushContext(
-  request: Request,
-  syncPathnameSet: ReadonlySet<string>
-): Promise<{ sourceClientId?: string } | null> {
-  if (request.method !== 'POST') return null;
-
-  const pathname = new URL(request.url).pathname;
-  if (!syncPathnameSet.has(pathname)) return null;
-
-  try {
-    const payload = await request.clone().json();
-    if (!isRecord(payload)) return null;
-    if (!isRecord(payload.push)) return null;
-    const push = payload.push;
-    const hasBatchOperations =
-      Array.isArray(push.commits) &&
-      push.commits.some(
-        (commit) =>
-          isRecord(commit) &&
-          Array.isArray(commit.operations) &&
-          commit.operations.length > 0
-      );
-    if (!hasBatchOperations) return null;
-
-    const sourceClientId =
-      typeof payload.clientId === 'string' && payload.clientId.length > 0
-        ? payload.clientId
-        : undefined;
-
-    return { sourceClientId };
-  } catch {
-    return null;
-  }
-}
-
-async function getAppliedCommitCursor(
-  response: Response
-): Promise<number | undefined> {
-  if (!response.ok) return undefined;
-
-  try {
-    const payload = await response.clone().json();
-    if (!isRecord(payload)) return undefined;
-    if (!isRecord(payload.push)) return undefined;
-    const push = payload.push;
-    if (Array.isArray(push.commits)) {
-      const commitSeqs = push.commits
-        .map((commit) => {
-          if (!isRecord(commit)) return null;
-          if (
-            commit.status !== 'applied' &&
-            commit.status !== 'cached' &&
-            commit.status !== 'rejected'
-          ) {
-            return null;
-          }
-          return typeof commit.commitSeq === 'number' ? commit.commitSeq : null;
-        })
-        .filter((commitSeq): commitSeq is number => commitSeq !== null);
-      if (commitSeqs.length > 0) {
-        return Math.max(...commitSeqs);
-      }
-      return undefined;
-    }
-
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-export function createSyncWakeMessageResolver(
-  options?: ServiceWorkerSyncWakeMessageResolverOptions
-): {
-  captureContext: (
-    request: Request
-  ) => Promise<ServiceWorkerSyncWakeContext | null>;
-  resolveMessage: (
-    args: ResolveWakeMessageArgs
-  ) => Promise<ServiceWorkerWakeMessage | null>;
-} {
-  const syncPathnameSet = new Set(
-    options?.syncPathnames ?? ['/api/sync', '/api/sync/']
-  );
-
-  return {
-    captureContext: async (request: Request) => {
-      return await getSyncPushContext(request, syncPathnameSet);
-    },
-    resolveMessage: async (args: ResolveWakeMessageArgs) => {
-      const syncContext =
-        args.wakeContext && typeof args.wakeContext === 'object'
-          ? (args.wakeContext as ServiceWorkerSyncWakeContext)
-          : null;
-      if (!syncContext) return null;
-
-      const cursor = await getAppliedCommitCursor(args.response);
-      if (cursor === undefined) return null;
-
-      return {
-        type: SERVICE_WORKER_WAKE_MESSAGE_TYPE,
-        timestamp: Date.now(),
-        cursor,
-        ...(syncContext.sourceClientId
-          ? { sourceClientId: syncContext.sourceClientId }
-          : {}),
-      } satisfies ServiceWorkerWakeMessage;
-    },
-  };
-}
-
-export function createServiceWorkerServer(
-  options: CreateServiceWorkerServerOptions
-): ServiceWorkerServer {
-  const apiPrefix = normalizePrefix(options.apiPrefix);
-  const scriptPath = options.serviceWorkerScriptPath;
-  const syncWakeResolver = createSyncWakeMessageResolver({
-    syncPathnames: options.syncPathnames,
-  });
-
-  const captureWakeContext =
-    options.captureWakeContext ?? syncWakeResolver.captureContext;
-  const resolveWakeMessage =
-    options.resolveWakeMessage ?? syncWakeResolver.resolveMessage;
-
-  const onError =
-    options.onError ??
-    (() =>
-      Response.json(createSyncularErrorResponse('runtime.internal'), {
-        status: 500,
-      }));
-
-  return {
-    shouldHandleRequest(request: Request, localOrigin?: string): boolean {
-      const requestUrl = new URL(request.url);
-
-      if (localOrigin && requestUrl.origin !== localOrigin) {
-        return false;
-      }
-      if (!pathStartsWithPrefix(requestUrl.pathname, apiPrefix)) {
-        return false;
-      }
-      if (scriptPath && requestUrl.pathname === scriptPath) {
-        return false;
-      }
-      return true;
-    },
-
-    async handleRequest(request: Request): Promise<Response> {
-      try {
-        return await options.handleRequest(request);
-      } catch (error) {
-        return await onError(error, request);
-      }
-    },
-
-    async captureWakeContext(request: Request) {
-      return await captureWakeContext(request);
-    },
-
-    async resolveWakeMessage(args: ResolveWakeMessageArgs) {
-      return await resolveWakeMessage(args);
-    },
-  };
-}
-
-export interface ServiceWorkerGlobalScopeLike {
-  addEventListener(type: string, listener: (event: unknown) => void): void;
-  location?: { origin?: string };
-  skipWaiting?: () => Promise<void>;
-  clients?: {
-    claim?: () => Promise<void>;
-    matchAll?: (options?: {
-      type?: 'window' | 'worker' | 'sharedworker' | 'all';
-      includeUncontrolled?: boolean;
-    }) => Promise<Array<{ postMessage: (message: unknown) => void }>>;
-  };
-}
-
-interface ServiceWorkerLifecycleEventLike {
-  waitUntil(promise: Promise<unknown>): void;
-}
-
-interface ServiceWorkerFetchEventLike {
-  request: Request;
-  respondWith(response: Response | Promise<Response>): void;
-}
-
-export interface AttachServiceWorkerServerOptions {
-  manageLifecycle?: boolean;
-  channelName?: string;
-  logger?: {
-    error?: (...args: unknown[]) => void;
-  };
-}
-
-function createWakeBroadcaster(
-  globalScope: ServiceWorkerGlobalScopeLike,
-  channelName: string
-): (message: ServiceWorkerWakeMessage) => void {
-  const channel =
-    typeof BroadcastChannel !== 'undefined'
-      ? new BroadcastChannel(channelName)
-      : null;
-
-  return (message: ServiceWorkerWakeMessage): void => {
-    try {
-      if (channel) {
-        channel.postMessage(message);
-        return;
-      }
-    } catch {
-      // fall through to postMessage fallback
-    }
-
-    void globalScope.clients
-      ?.matchAll?.({ type: 'window', includeUncontrolled: true })
-      .then((clients) => {
-        for (const client of clients) {
-          try {
-            client.postMessage(message);
-          } catch {
-            // best-effort wake-up
-          }
-        }
-      })
-      .catch(() => {
-        // best-effort wake-up
-      });
-  };
-}
-
-export function attachServiceWorkerServer(
-  globalScope: ServiceWorkerGlobalScopeLike,
-  server: ServiceWorkerServer,
-  options?: AttachServiceWorkerServerOptions
-): void {
-  const manageLifecycle = options?.manageLifecycle ?? true;
-  const localOrigin = globalScope.location?.origin;
-  const broadcastWakeMessage = createWakeBroadcaster(
-    globalScope,
-    options?.channelName ?? SERVICE_WORKER_WAKE_CHANNEL
-  );
-
-  if (manageLifecycle) {
-    globalScope.addEventListener('install', (event: unknown) => {
-      const installEvent = event as ServiceWorkerLifecycleEventLike;
-      installEvent.waitUntil(globalScope.skipWaiting?.() ?? Promise.resolve());
-    });
-
-    globalScope.addEventListener('activate', (event: unknown) => {
-      const activateEvent = event as ServiceWorkerLifecycleEventLike;
-      activateEvent.waitUntil(
-        globalScope.clients?.claim?.() ?? Promise.resolve()
-      );
-    });
-  }
-
-  globalScope.addEventListener('fetch', (event: unknown) => {
-    const fetchEvent = event as ServiceWorkerFetchEventLike;
-    const request = fetchEvent.request;
-
-    if (!server.shouldHandleRequest(request, localOrigin)) {
-      return;
-    }
-
-    fetchEvent.respondWith(
-      (async () => {
-        const wakeContext = await server.captureWakeContext(request);
-        const response = await server.handleRequest(request);
-
-        try {
-          const wakeMessage = await server.resolveWakeMessage({
-            request,
-            response,
-            wakeContext,
-          });
-          if (wakeMessage) {
-            broadcastWakeMessage(wakeMessage);
-          }
-        } catch (error) {
-          options?.logger?.error?.(
-            '[server-service-worker] failed to resolve wake message',
-            error
-          );
-        }
-
-        return response;
-      })()
-    );
-  });
-}
-
-export interface ConfigureServiceWorkerServerOptions {
-  scriptPath: string;
-  scriptVersion?: string;
-  healthPath?: string;
-  healthCheck?: (response: Response) => boolean | Promise<boolean>;
-  enabled?: boolean;
-  scope?: string;
-  type?: 'classic' | 'module';
-  updateViaCache?: 'imports' | 'all' | 'none';
-  unregisterOnDisable?: boolean;
-  controllerTimeoutMs?: number;
-  healthTimeoutMs?: number;
-  healthRetryDelayMs?: number;
-  healthRequestTimeoutMs?: number;
-  fetchImpl?: typeof fetch;
-  logger?: {
-    info?: (...args: unknown[]) => void;
-    warn?: (...args: unknown[]) => void;
-    error?: (...args: unknown[]) => void;
-  };
-}
-
-export async function unregisterServiceWorkerRegistrations(
-  scriptPath: string
-): Promise<void> {
-  if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) {
-    return;
-  }
-
-  const registrations = await navigator.serviceWorker.getRegistrations();
-  const targetPathname = new URL(scriptPath, window.location.origin).pathname;
-  const unregisterTasks = registrations
-    .filter((registration) => {
-      const scriptUrl =
-        registration.active?.scriptURL ??
-        registration.waiting?.scriptURL ??
-        registration.installing?.scriptURL;
-      if (!scriptUrl) return false;
-      try {
-        return new URL(scriptUrl).pathname === targetPathname;
-      } catch {
-        return scriptUrl.includes(targetPathname);
-      }
-    })
-    .map((registration) => registration.unregister());
-
-  await Promise.all(unregisterTasks);
-}
-
-function waitForControllerChange(
-  timeoutMs: number,
-  previousController: ServiceWorker | null
-): Promise<void> {
-  if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) {
-    return Promise.resolve();
-  }
-
-  const hasChanged = () =>
-    navigator.serviceWorker.controller !== null &&
-    navigator.serviceWorker.controller !== previousController;
-
-  if (hasChanged()) {
-    return Promise.resolve();
-  }
-
-  return new Promise((resolve) => {
-    const onControllerChange = () => {
-      if (!hasChanged()) {
-        return;
-      }
-      clearTimeout(timeoutId);
-      navigator.serviceWorker.removeEventListener(
-        'controllerchange',
-        onControllerChange
-      );
-      resolve();
-    };
-
-    const timeoutId = setTimeout(() => {
-      navigator.serviceWorker.removeEventListener(
-        'controllerchange',
-        onControllerChange
-      );
-      resolve();
-    }, timeoutMs);
-
-    navigator.serviceWorker.addEventListener(
-      'controllerchange',
-      onControllerChange
-    );
-  });
-}
-
-function versionServiceWorkerScriptPath(
-  scriptPath: string,
-  version: string | undefined
-): string {
-  const trimmedVersion = version?.trim();
-  if (!trimmedVersion) return scriptPath;
-
-  const scriptUrl = new URL(scriptPath, window.location.origin);
-  scriptUrl.searchParams.set('v', trimmedVersion);
-  return `${scriptUrl.pathname}${scriptUrl.search}`;
-}
-
-async function waitForHealth(args: {
-  path: string;
-  timeoutMs: number;
-  retryDelayMs: number;
-  requestTimeoutMs: number;
-  fetchImpl: typeof fetch;
-  healthCheck?: (response: Response) => boolean | Promise<boolean>;
-}): Promise<boolean> {
-  const started = Date.now();
-
-  while (Date.now() - started < args.timeoutMs) {
-    try {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(
-        () => controller.abort(),
-        args.requestTimeoutMs
-      );
-      let response: Response;
-      try {
-        response = await args.fetchImpl(args.path, {
-          method: 'GET',
-          cache: 'no-store',
-          signal: controller.signal,
-        });
-      } finally {
-        clearTimeout(timeoutId);
-      }
-      if (response.ok) {
-        if (args.healthCheck) {
-          const matches = await args.healthCheck(response);
-          if (!matches) {
-            throw new Error('Service Worker health probe mismatch');
-          }
-        }
-        return true;
-      }
-    } catch {
-      // keep retrying until timeout
-    }
-
-    await new Promise((resolve) => setTimeout(resolve, args.retryDelayMs));
-  }
-
-  return false;
-}
-
-export async function configureServiceWorkerServer(
-  options: ConfigureServiceWorkerServerOptions
-): Promise<boolean> {
-  if (
-    typeof window === 'undefined' ||
-    typeof navigator === 'undefined' ||
-    !('serviceWorker' in navigator)
-  ) {
-    return false;
-  }
-
-  const enabled = options.enabled ?? true;
-  const logger = options.logger;
-
-  if (!enabled) {
-    if (options.unregisterOnDisable !== false) {
-      await unregisterServiceWorkerRegistrations(options.scriptPath);
-    }
-    logger?.warn?.('[server-service-worker] service worker mode disabled');
-    return false;
-  }
-
-  try {
-    const previousController = navigator.serviceWorker.controller ?? null;
-    const versionedScriptPath = versionServiceWorkerScriptPath(
-      options.scriptPath,
-      options.scriptVersion
-    );
-
-    const registration = await navigator.serviceWorker.register(
-      versionedScriptPath,
-      {
-        scope: options.scope,
-        type: options.type ?? 'module',
-        updateViaCache: options.updateViaCache ?? 'none',
-      }
-    );
-
-    try {
-      await registration.update();
-    } catch {
-      // best-effort refresh; continue to health check even if the browser declines
-    }
-
-    await navigator.serviceWorker.ready;
-    await new Promise((resolve) => setTimeout(resolve, 50));
-    if (
-      previousController === null ||
-      registration.installing ||
-      registration.waiting
-    ) {
-      await waitForControllerChange(
-        options.controllerTimeoutMs ?? 5_000,
-        previousController
-      );
-    }
-
-    const healthy = await waitForHealth({
-      path: options.healthPath ?? '/api/health',
-      timeoutMs: options.healthTimeoutMs ?? 10_000,
-      retryDelayMs: options.healthRetryDelayMs ?? 150,
-      requestTimeoutMs: options.healthRequestTimeoutMs ?? 2_000,
-      fetchImpl: options.fetchImpl ?? fetch,
-      healthCheck: options.healthCheck,
-    });
-
-    if (!healthy) {
-      throw new Error('Service Worker server health check timed out');
-    }
-
-    logger?.info?.('[server-service-worker] service worker server enabled');
-    return true;
-  } catch (error) {
-    logger?.error?.(
-      '[server-service-worker] failed to enable service worker server',
-      error
-    );
-    return false;
-  }
-}