@syncular/server 0.1.2 → 0.2.0

package/src/cloudflare/scope-cache.ts

@@ -1,341 +0,0 @@
-/**
- * Durable Object-backed scope cache for @syncular/server.
- *
- * This module provides two parts:
- * 1) `createDurableObjectScopeCache()` - cache backend to pass to createSyncServer/createSyncRoutes
- * 2) `ScopeCacheDurableObject` - Durable Object class that stores scope entries in DO storage
- */
-
-import { createSyncularErrorResponse } from '@syncular/core';
-
-type ScopeValues = Record<string, string | string[]>;
-
-interface ScopeCacheContext {
-  db: object;
-  auth: {
-    actorId: string;
-    partitionId?: string;
-  };
-  table: string;
-  cacheKey: string;
-}
-
-interface ScopeCacheSetContext extends ScopeCacheContext {
-  scopes: ScopeValues;
-}
-
-interface ScopeCacheBackend {
-  name: string;
-  get(args: ScopeCacheContext): Promise<ScopeValues | null>;
-  set(args: ScopeCacheSetContext): Promise<void>;
-  delete?(args: ScopeCacheContext): Promise<void>;
-}
-
-const DEFAULT_SCOPE_CACHE_TTL_MS = 60_000;
-const DEFAULT_SCOPE_CACHE_DO_NAME = 'syncular-scope-cache';
-const DEFAULT_SCOPE_CACHE_PATH = '/scope-cache';
-const JSON_HEADERS = { 'content-type': 'application/json' };
-
-interface ScopeCacheLookup {
-  cacheKey: string;
-  partitionId: string;
-  actorId: string;
-  table: string;
-}
-
-type ScopeCacheRequestBody =
-  | {
-      action: 'get';
-      cacheKey: string;
-    }
-  | {
-      action: 'set';
-      cacheKey: string;
-      scopes: ScopeValues;
-      ttlMs: number;
-    }
-  | {
-      action: 'delete';
-      cacheKey: string;
-    };
-
-function cloneScopeValues(scopes: ScopeValues): ScopeValues {
-  const cloned: ScopeValues = {};
-  for (const [key, value] of Object.entries(scopes)) {
-    if (typeof value === 'string') {
-      cloned[key] = value;
-      continue;
-    }
-    cloned[key] = [...value];
-  }
-  return cloned;
-}
-
-function isScopeValues(value: unknown): value is ScopeValues {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    return false;
-  }
-
-  for (const scopeValue of Object.values(value)) {
-    if (typeof scopeValue === 'string') {
-      continue;
-    }
-    if (
-      Array.isArray(scopeValue) &&
-      scopeValue.every((entry) => typeof entry === 'string')
-    ) {
-      continue;
-    }
-    return false;
-  }
-  return true;
-}
-
-function parseJsonObject(value: string): Record<string, unknown> | null {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    return null;
-  }
-
-  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    return null;
-  }
-
-  const out: Record<string, unknown> = {};
-  for (const [key, entry] of Object.entries(parsed)) {
-    out[key] = entry;
-  }
-  return out;
-}
-
-async function parseRequestBody(
-  request: Request
-): Promise<ScopeCacheRequestBody | null> {
-  let body: string;
-  try {
-    body = await request.text();
-  } catch {
-    return null;
-  }
-
-  const parsed = parseJsonObject(body);
-  if (!parsed) {
-    return null;
-  }
-
-  const action = parsed.action;
-  const cacheKey = parsed.cacheKey;
-  if (typeof action !== 'string' || typeof cacheKey !== 'string') {
-    return null;
-  }
-
-  if (action === 'get') {
-    return { action: 'get', cacheKey };
-  }
-
-  if (action === 'delete') {
-    return { action: 'delete', cacheKey };
-  }
-
-  if (action === 'set') {
-    const ttlMs = parsed.ttlMs;
-    const scopes = parsed.scopes;
-    if (
-      typeof ttlMs !== 'number' ||
-      Number.isNaN(ttlMs) ||
-      !Number.isFinite(ttlMs)
-    ) {
-      return null;
-    }
-    if (!isScopeValues(scopes)) {
-      return null;
-    }
-    return {
-      action: 'set',
-      cacheKey,
-      scopes: cloneScopeValues(scopes),
-      ttlMs,
-    };
-  }
-
-  return null;
-}
-
-interface StoredScopeCacheValue {
-  scopes: ScopeValues;
-  expiresAt: number;
-}
-
-/**
- * Durable Object for scope cache entries.
- *
- * Bind this class in your Worker as a separate DO namespace.
- */
-export class ScopeCacheDurableObject {
-  private readonly state: DurableObjectState;
-
-  constructor(state: DurableObjectState, _env: object) {
-    this.state = state;
-  }
-
-  async fetch(request: Request): Promise<Response> {
-    if (request.method !== 'POST') {
-      return Response.json(
-        createSyncularErrorResponse('sync.invalid_request', {
-          message: 'Method not allowed',
-        }),
-        { status: 405, headers: { allow: 'POST' } }
-      );
-    }
-
-    const payload = await parseRequestBody(request);
-    if (!payload) {
-      return Response.json(
-        createSyncularErrorResponse('sync.invalid_request', {
-          message: 'Invalid scope cache request',
-        }),
-        { status: 400 }
-      );
-    }
-
-    if (payload.action === 'get') {
-      const entry = await this.state.storage.get<StoredScopeCacheValue>(
-        payload.cacheKey
-      );
-      if (!entry) {
-        return Response.json({ scopes: null });
-      }
-
-      if (entry.expiresAt <= Date.now()) {
-        await this.state.storage.delete(payload.cacheKey);
-        return Response.json({ scopes: null });
-      }
-
-      return Response.json({ scopes: cloneScopeValues(entry.scopes) });
-    }
-
-    if (payload.action === 'set') {
-      if (payload.ttlMs <= 0) {
-        await this.state.storage.delete(payload.cacheKey);
-        return Response.json({ ok: true });
-      }
-
-      await this.state.storage.put(payload.cacheKey, {
-        scopes: cloneScopeValues(payload.scopes),
-        expiresAt: Date.now() + payload.ttlMs,
-      } satisfies StoredScopeCacheValue);
-
-      return Response.json({ ok: true });
-    }
-
-    await this.state.storage.delete(payload.cacheKey);
-    return Response.json({ ok: true });
-  }
-}
-
-export interface DurableObjectScopeCacheOptions {
-  namespace: DurableObjectNamespace;
-  ttlMs?: number;
-  path?: string;
-  getStubId?: (
-    namespace: DurableObjectNamespace,
-    lookup: ScopeCacheLookup
-  ) => DurableObjectId;
-}
-
-/**
- * Create a scope cache backend that reads/writes through a Durable Object.
- */
-export function createDurableObjectScopeCache(
-  options: DurableObjectScopeCacheOptions
-): ScopeCacheBackend {
-  const ttlMs = options.ttlMs ?? DEFAULT_SCOPE_CACHE_TTL_MS;
-  const path = options.path ?? DEFAULT_SCOPE_CACHE_PATH;
-  const getStubId =
-    options.getStubId ??
-    ((namespace: DurableObjectNamespace) =>
-      namespace.idFromName(DEFAULT_SCOPE_CACHE_DO_NAME));
-
-  async function callDurableObject(
-    lookup: ScopeCacheLookup,
-    body: ScopeCacheRequestBody
-  ): Promise<Record<string, unknown>> {
-    const id = getStubId(options.namespace, lookup);
-    const stub = options.namespace.get(id);
-    const response = await stub.fetch(`https://scope-cache${path}`, {
-      method: 'POST',
-      headers: JSON_HEADERS,
-      body: JSON.stringify(body),
-    });
-
-    if (!response.ok) {
-      throw new Error(
-        `Scope cache durable object request failed: ${response.status}`
-      );
-    }
-
-    const parsed = parseJsonObject(await response.text());
-    if (!parsed) {
-      throw new Error('Scope cache durable object response was not JSON');
-    }
-
-    return parsed;
-  }
-
-  return {
-    name: 'durable-object',
-    async get(args) {
-      const lookup: ScopeCacheLookup = {
-        cacheKey: args.cacheKey,
-        partitionId: args.auth.partitionId ?? 'default',
-        actorId: args.auth.actorId,
-        table: args.table,
-      };
-
-      const response = await callDurableObject(lookup, {
-        action: 'get',
-        cacheKey: args.cacheKey,
-      });
-      const scopes = response.scopes;
-      if (scopes === null || scopes === undefined) {
-        return null;
-      }
-
-      if (!isScopeValues(scopes)) {
-        return null;
-      }
-
-      return cloneScopeValues(scopes);
-    },
-    async set(args) {
-      const lookup: ScopeCacheLookup = {
-        cacheKey: args.cacheKey,
-        partitionId: args.auth.partitionId ?? 'default',
-        actorId: args.auth.actorId,
-        table: args.table,
-      };
-
-      await callDurableObject(lookup, {
-        action: 'set',
-        cacheKey: args.cacheKey,
-        scopes: cloneScopeValues(args.scopes),
-        ttlMs,
-      });
-    },
-    async delete(args) {
-      const lookup: ScopeCacheLookup = {
-        cacheKey: args.cacheKey,
-        partitionId: args.auth.partitionId ?? 'default',
-        actorId: args.auth.actorId,
-        table: args.table,
-      };
-
-      await callDurableObject(lookup, {
-        action: 'delete',
-        cacheKey: args.cacheKey,
-      });
-    },
-  };
-}

package/src/cloudflare/sentry.ts

@@ -1,230 +0,0 @@
-import * as Sentry from '@sentry/cloudflare';
-import {
-  configureSyncTelemetry,
-  type SyncMetricOptions,
-  type SyncTelemetry,
-  type SyncTelemetryAttributeValue,
-} from '@syncular/core';
-import { createSentrySyncTelemetry } from '@syncular/core/sentry';
-
-function toCountMetricOptions(
-  options?: SyncMetricOptions
-): Parameters<typeof Sentry.metrics.count>[2] | undefined {
-  if (!options?.attributes) return undefined;
-  return { attributes: options.attributes };
-}
-
-function toValueMetricOptions(
-  options?: SyncMetricOptions
-): Parameters<typeof Sentry.metrics.gauge>[2] | undefined {
-  if (!options) return undefined;
-  const hasAttributes = Boolean(options.attributes);
-  const hasUnit = Boolean(options.unit);
-  if (!hasAttributes && !hasUnit) return undefined;
-  return {
-    attributes: options.attributes,
-    unit: options.unit,
-  };
-}
-
-export type CloudflareSentryCaptureMessageLevel = Parameters<
-  typeof Sentry.captureMessage
->[1];
-
-interface CloudflareSentryCaptureMessageOptions {
-  level?: CloudflareSentryCaptureMessageLevel;
-  tags?: Record<string, string>;
-}
-
-type CloudflareSentryLogLevel =
-  | 'trace'
-  | 'debug'
-  | 'info'
-  | 'warn'
-  | 'error'
-  | 'fatal';
-
-interface CloudflareSentryLogOptions {
-  level?: CloudflareSentryLogLevel;
-  attributes?: Record<string, SyncTelemetryAttributeValue>;
-}
-
-function resolveCloudflareLogMethod(
-  level: CloudflareSentryLogLevel
-):
-  | ((
-      message: string,
-      attributes?: Record<string, SyncTelemetryAttributeValue>
-    ) => void)
-  | null {
-  switch (level) {
-    case 'trace':
-      return Sentry.logger.trace ?? Sentry.logger.debug ?? Sentry.logger.info;
-    case 'debug':
-      return Sentry.logger.debug ?? Sentry.logger.info;
-    case 'info':
-      return Sentry.logger.info;
-    case 'warn':
-      return Sentry.logger.warn ?? Sentry.logger.info;
-    case 'error':
-      return Sentry.logger.error ?? Sentry.logger.warn ?? Sentry.logger.info;
-    case 'fatal':
-      return (
-        Sentry.logger.fatal ??
-        Sentry.logger.error ??
-        Sentry.logger.warn ??
-        Sentry.logger.info
-      );
-    default:
-      return Sentry.logger.info;
-  }
-}
-
-/**
- * Re-export Cloudflare Sentry worker wrapper.
- */
-export const withCloudflareSentry = Sentry.withSentry;
-export const instrumentCloudflareDurableObjectWithSentry =
-  Sentry.instrumentDurableObjectWithSentry;
-
-export interface CloudflareSentryTraceHeaders {
-  sentryTrace?: string;
-  baggage?: string;
-}
-
-/**
- * Read current trace headers from the active Cloudflare Sentry scope.
- */
-export function getCloudflareSentryTraceHeaders(
-  traceData: ReturnType<typeof Sentry.getTraceData> = Sentry.getTraceData()
-): CloudflareSentryTraceHeaders {
-  const sentryTrace = traceData['sentry-trace']?.trim();
-  const baggage = traceData.baggage?.trim();
-  return {
-    ...(sentryTrace ? { sentryTrace } : {}),
-    ...(baggage ? { baggage } : {}),
-  };
-}
-
-/**
- * Clone a request and attach active Cloudflare trace headers when available.
- */
-export function attachCloudflareSentryTraceHeaders(
-  request: Request,
-  traceHeaders: CloudflareSentryTraceHeaders = getCloudflareSentryTraceHeaders()
-): Request {
-  if (!traceHeaders.sentryTrace && !traceHeaders.baggage) {
-    return request;
-  }
-
-  const headers = new Headers(request.headers);
-  if (traceHeaders.sentryTrace) {
-    headers.set('sentry-trace', traceHeaders.sentryTrace);
-  }
-  if (traceHeaders.baggage) {
-    headers.set('baggage', traceHeaders.baggage);
-  }
-
-  return new Request(request, { headers });
-}
-
-/**
- * Create a Syncular telemetry backend wired to `@sentry/cloudflare`.
- */
-export function createCloudflareSentryTelemetry(): SyncTelemetry {
-  return createSentrySyncTelemetry({
-    logger: Sentry.logger,
-    startSpan(options, callback) {
-      return Sentry.startSpan(options, (span) =>
-        callback({
-          setAttribute(name, value) {
-            span.setAttribute(name, value);
-          },
-          setAttributes(attributes) {
-            span.setAttributes(attributes);
-          },
-          setStatus(status) {
-            span.setStatus({
-              code: status === 'ok' ? 1 : 2,
-            });
-          },
-        })
-      );
-    },
-    metrics: {
-      count(name, value, options) {
-        const metricOptions = toCountMetricOptions(options);
-        if (metricOptions) {
-          Sentry.metrics.count(name, value, metricOptions);
-          return;
-        }
-        Sentry.metrics.count(name, value);
-      },
-      gauge(name, value, options) {
-        const metricOptions = toValueMetricOptions(options);
-        if (metricOptions) {
-          Sentry.metrics.gauge(name, value, metricOptions);
-          return;
-        }
-        Sentry.metrics.gauge(name, value);
-      },
-      distribution(name, value, options) {
-        const metricOptions = toValueMetricOptions(options);
-        if (metricOptions) {
-          Sentry.metrics.distribution(name, value, metricOptions);
-          return;
-        }
-        Sentry.metrics.distribution(name, value);
-      },
-    },
-    captureException(error) {
-      Sentry.captureException(error);
-    },
-  });
-}
-
-/**
- * Configure Syncular core telemetry to use the Cloudflare Sentry adapter.
- */
-export function configureCloudflareSentryTelemetry(): SyncTelemetry {
-  const telemetry = createCloudflareSentryTelemetry();
-  configureSyncTelemetry(telemetry);
-  return telemetry;
-}
-
-/**
- * Capture a worker message in Sentry with optional tags.
- */
-export function captureCloudflareSentryMessage(
-  message: string,
-  options?: CloudflareSentryCaptureMessageOptions
-): void {
-  if (!options?.tags || Object.keys(options.tags).length === 0) {
-    Sentry.captureMessage(message, options?.level);
-    return;
-  }
-
-  Sentry.withScope((scope) => {
-    for (const [name, value] of Object.entries(options.tags ?? {})) {
-      scope.setTag(name, value);
-    }
-    Sentry.captureMessage(message, options?.level);
-  });
-}
-
-/**
- * Emit a Cloudflare Sentry log entry.
- */
-export function logCloudflareSentryMessage(
-  message: string,
-  options?: CloudflareSentryLogOptions
-): void {
-  const level = options?.level ?? 'info';
-  const logMethod = resolveCloudflareLogMethod(level);
-  if (!logMethod) return;
-  if (!options?.attributes || Object.keys(options.attributes).length === 0) {
-    logMethod(message);
-    return;
-  }
-  logMethod(message, options.attributes);
-}

package/src/cloudflare/worker.ts

@@ -1,77 +0,0 @@
-/**
- * @syncular/server/cloudflare - Worker handler (polling only)
- *
- * Creates a stateless Cloudflare Worker that serves sync routes via Hono.
- * No WebSocket support — use the Durable Object adapter for realtime.
- *
- * @example
- * ```typescript
- * import { createSyncWorker } from '@syncular/server/cloudflare/worker';
- * import { createD1Dialect } from '@syncular/server/d1';
- * import { createSqliteServerDialect } from '@syncular/server/sqlite';
- * import { ensureSyncSchema } from '@syncular/server';
- * import { createSyncServer } from '@syncular/server/hono';
- *
- * type Env = { DB: D1Database };
- *
- * export default createSyncWorker<Env>((app, env) => {
- *   const db = createD1Dialect(env.DB);
- *   const dialect = createSqliteServerDialect();
- *   const { syncRoutes, consoleRoutes } = createSyncServer({
- *     db, dialect,
- *     sync: {
- *       handlers: [tasksHandler],
- *       authenticate: async (request) => ({
- *         actorId: request.headers.get('x-user-id')!,
- *       }),
- *     },
- *   });
- *   app.route('/sync', syncRoutes);
- *   if (consoleRoutes) app.route('/console', consoleRoutes);
- * });
- * ```
- */
-
-import { Hono } from 'hono';
-
-type SyncWorkerSetup<B extends object> = (
-  app: Hono<{ Bindings: B }>,
-  env: B
-) => void | Promise<void>;
-
-/**
- * Create a Cloudflare Worker export that lazily initializes a Hono app.
- *
- * The `setup` callback is called once per isolate on the first request.
- * It receives a fresh Hono app and the Worker env bindings.
- */
-export function createSyncWorker<
-  Bindings extends object = Record<string, unknown>,
->(setup: SyncWorkerSetup<Bindings>): ExportedHandler<Bindings> {
-  type E = { Bindings: Bindings };
-  let app: Hono<E> | null = null;
-  let initPromise: Promise<void> | null = null;
-
-  async function getApp(env: Bindings): Promise<Hono<E>> {
-    if (app) return app;
-    if (!initPromise) {
-      const honoApp = new Hono<E>();
-      initPromise = Promise.resolve(setup(honoApp, env)).then(() => {
-        app = honoApp;
-      });
-    }
-    await initPromise;
-    return app!;
-  }
-
-  return {
-    async fetch(
-      request: Request,
-      env: Bindings,
-      ctx: ExecutionContext
-    ): Promise<Response> {
-      const honoApp = await getApp(env);
-      return honoApp.fetch(request, env, ctx);
-    },
-  };
-}