@syncular/server 0.0.6-96 → 0.1.0

package/src/cloudflare/scope-cache.ts

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

@@ -0,0 +1,230 @@
+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

@@ -0,0 +1,77 @@
+/**
+ * @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);
+    },
+  };
+}