@syncular/client 0.0.6-95 → 0.1.0

package/src/sentry.ts

@@ -0,0 +1,215 @@
+import * as Sentry from '@sentry/react';
+import {
+  configureSyncTelemetry,
+  type SyncMetricOptions,
+  type SyncTelemetry,
+  type SyncTelemetryAttributeValue,
+} from '@syncular/core';
+import { createSentrySyncTelemetry } from '@syncular/core/sentry';
+
+export type BrowserSentryInitOptions = Parameters<typeof Sentry.init>[0];
+export type BrowserSentryCaptureMessageLevel = Parameters<
+  typeof Sentry.captureMessage
+>[1];
+
+interface BrowserSentryCaptureMessageOptions {
+  level?: BrowserSentryCaptureMessageLevel;
+  tags?: Record<string, string>;
+}
+
+type BrowserSentryLogLevel =
+  | 'trace'
+  | 'debug'
+  | 'info'
+  | 'warn'
+  | 'error'
+  | 'fatal';
+
+interface BrowserSentryLogOptions {
+  level?: BrowserSentryLogLevel;
+  attributes?: Record<string, SyncTelemetryAttributeValue>;
+}
+
+function resolveBrowserLogMethod(
+  level: BrowserSentryLogLevel
+):
+  | ((
+      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;
+  }
+}
+
+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,
+  };
+}
+
+/**
+ * Create a Syncular telemetry backend wired to `@sentry/react`.
+ */
+export function createBrowserSentryTelemetry(): 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 browser Sentry adapter.
+ */
+export function configureBrowserSentryTelemetry(): SyncTelemetry {
+  const telemetry = createBrowserSentryTelemetry();
+  configureSyncTelemetry(telemetry);
+  return telemetry;
+}
+
+/**
+ * Initialize browser Sentry and configure Syncular telemetry.
+ */
+export function initAndConfigureBrowserSentry(
+  options: BrowserSentryInitOptions
+): SyncTelemetry {
+  const configuredOptions = ensureBrowserTracingIntegration(options);
+  Sentry.init(configuredOptions);
+  return configureBrowserSentryTelemetry();
+}
+
+function ensureBrowserTracingIntegration(
+  options: BrowserSentryInitOptions
+): BrowserSentryInitOptions {
+  const integrations = options.integrations;
+  if (typeof integrations === 'function') return options;
+
+  const configuredIntegrations = integrations ?? [];
+  const hasBrowserTracing = configuredIntegrations.some(
+    (integration) => integration.name === 'BrowserTracing'
+  );
+  if (hasBrowserTracing) return options;
+
+  return {
+    ...options,
+    integrations: [
+      Sentry.browserTracingIntegration(),
+      ...configuredIntegrations,
+    ],
+  };
+}
+
+/**
+ * Capture a browser message in Sentry with optional tags.
+ */
+export function captureBrowserSentryMessage(
+  message: string,
+  options?: BrowserSentryCaptureMessageOptions
+): 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 browser Sentry log entry.
+ */
+export function logBrowserSentryMessage(
+  message: string,
+  options?: BrowserSentryLogOptions
+): void {
+  const level = options?.level ?? 'info';
+  const logMethod = resolveBrowserLogMethod(level);
+  if (!logMethod) return;
+  if (!options?.attributes || Object.keys(options.attributes).length === 0) {
+    logMethod(message);
+    return;
+  }
+  logMethod(message, options.attributes);
+}

package/src/sql-safety.ts

@@ -0,0 +1,61 @@
+const READONLY_SQL_START = new Set(['select', 'with', 'pragma', 'explain']);
+const TRANSACTION_SQL_START = new Set([
+  'begin',
+  'commit',
+  'rollback',
+  'savepoint',
+  'release',
+]);
+
+export function assertSyncularReadonlySql(sql: string): void {
+  if (isSyncularReadonlySql(sql)) return;
+  throw new Error(
+    'Syncular public SQL is read-only. Use generated Syncular mutations for synced writes.'
+  );
+}
+
+export function isSyncularReadonlySql(sql: string): boolean {
+  const normalized = stripLeadingSqlComments(sql).trimStart();
+  if (!normalized) return true;
+  if (hasMultipleSqlStatements(normalized)) return false;
+  const keyword = firstSqlKeyword(normalized);
+  if (!keyword) return true;
+  if (TRANSACTION_SQL_START.has(keyword)) return true;
+  if (!READONLY_SQL_START.has(keyword)) return false;
+  if (keyword === 'pragma') return isReadonlyPragma(normalized);
+  return true;
+}
+
+function stripLeadingSqlComments(sql: string): string {
+  let rest = sql;
+  for (;;) {
+    const trimmed = rest.trimStart();
+    if (trimmed.startsWith('--')) {
+      const newline = trimmed.indexOf('\n');
+      rest = newline < 0 ? '' : trimmed.slice(newline + 1);
+      continue;
+    }
+    if (trimmed.startsWith('/*')) {
+      const end = trimmed.indexOf('*/');
+      rest = end < 0 ? '' : trimmed.slice(end + 2);
+      continue;
+    }
+    return trimmed;
+  }
+}
+
+function hasMultipleSqlStatements(sql: string): boolean {
+  const firstSemicolon = sql.indexOf(';');
+  if (firstSemicolon < 0) return false;
+  return sql.slice(firstSemicolon + 1).trim().length > 0;
+}
+
+function firstSqlKeyword(sql: string): string | null {
+  const match = /^[a-zA-Z_]+/.exec(sql);
+  return match?.[0]?.toLowerCase() ?? null;
+}
+
+function isReadonlyPragma(sql: string): boolean {
+  const withoutTrailingSemicolon = sql.trim().replace(/;+$/, '').trim();
+  return !withoutTrailingSemicolon.includes('=');
+}

package/src/tauri/index.ts

@@ -0,0 +1,211 @@
+import {
+  type CreateSyncularBridgeClientOptions,
+  createSyncularBridgeClient,
+  type SyncularAuthLeaseRecord,
+  type SyncularBridge,
+  type SyncularBridgeMutationBatch,
+  type SyncularBridgeQueryRequest,
+  type SyncularBridgeQueryResult,
+  type SyncularBridgeStatus,
+  type SyncularClientEventMap,
+  type SyncularClientEventSink,
+  type SyncularClientEventType,
+  type SyncularClientLike,
+  type SyncularConflictResolution,
+  type SyncularConflictSummary,
+  type SyncularDiagnosticSnapshot,
+  type SyncularPresenceEntry,
+  type SyncularPresenceSink,
+  type SyncularSubscriptionSpec,
+  type SyncularSyncResult,
+} from '@syncular/client';
+import type { SyncAuthLeaseIssueRequest } from '@syncular/core';
+
+export type SyncularTauriInvoke = <TResult>(
+  command: string,
+  args?: Record<string, unknown>
+) => Promise<TResult>;
+
+export type SyncularTauriListen = <TPayload>(
+  event: string,
+  handler: (event: { payload: TPayload }) => void
+) => Promise<() => void>;
+
+export interface SyncularTauriCommands {
+  executeSql: string;
+  applyMutationsCommit: string;
+  applyLeasedMutationsCommit: string;
+  sync: string;
+  resumeFromBackground: string;
+  start: string;
+  stop: string;
+  setSubscriptions: string;
+  issueAuthLease: string;
+  upsertAuthLease: string;
+  authLease: string;
+  activeAuthLeases: string;
+  diagnosticSnapshot: string;
+  joinPresence: string;
+  leavePresence: string;
+  updatePresenceMetadata: string;
+  listConflicts: string;
+  retryConflictKeepLocal: string;
+  resolveConflict: string;
+}
+
+export interface CreateSyncularTauriClientOptions
+  extends Omit<CreateSyncularBridgeClientOptions, 'bridge'> {
+  invoke: SyncularTauriInvoke;
+  listen?: SyncularTauriListen;
+  commands?: Partial<SyncularTauriCommands>;
+  eventPrefix?: string;
+}
+
+const DEFAULT_COMMANDS: SyncularTauriCommands = {
+  executeSql: 'syncular_execute_sql',
+  applyMutationsCommit: 'syncular_apply_mutations_commit',
+  applyLeasedMutationsCommit: 'syncular_apply_leased_mutations_commit',
+  sync: 'syncular_sync',
+  resumeFromBackground: 'syncular_resume_from_background',
+  start: 'syncular_start',
+  stop: 'syncular_stop',
+  setSubscriptions: 'syncular_set_subscriptions',
+  issueAuthLease: 'syncular_issue_auth_lease',
+  upsertAuthLease: 'syncular_upsert_auth_lease',
+  authLease: 'syncular_auth_lease',
+  activeAuthLeases: 'syncular_active_auth_leases',
+  diagnosticSnapshot: 'syncular_diagnostic_snapshot',
+  joinPresence: 'syncular_join_presence',
+  leavePresence: 'syncular_leave_presence',
+  updatePresenceMetadata: 'syncular_update_presence_metadata',
+  listConflicts: 'syncular_conflict_summaries',
+  retryConflictKeepLocal: 'syncular_retry_conflict_keep_local',
+  resolveConflict: 'syncular_resolve_conflict',
+};
+
+export async function createSyncularTauriClient<DB>(
+  options: CreateSyncularTauriClientOptions
+): Promise<SyncularClientLike<DB>> {
+  return createSyncularBridgeClient<DB>({
+    ...options,
+    bridge: createSyncularTauriBridge(options),
+  });
+}
+
+export function createSyncularTauriBridge(
+  options: CreateSyncularTauriClientOptions
+): SyncularBridge {
+  const commands = { ...DEFAULT_COMMANDS, ...options.commands };
+  const eventPrefix = options.eventPrefix ?? 'syncular';
+  const presence = new Map<string, SyncularPresenceEntry[]>();
+  let status: SyncularBridgeStatus = {};
+
+  const invoke = <TResult>(
+    command: string,
+    args?: Record<string, unknown>
+  ): Promise<TResult> => options.invoke<TResult>(command, args);
+
+  return {
+    executeSql: <Row extends Record<string, unknown>>(
+      request: SyncularBridgeQueryRequest
+    ) =>
+      invoke<SyncularBridgeQueryResult<Row>>(commands.executeSql, { request }),
+    applyMutationsCommit: (batch: SyncularBridgeMutationBatch) =>
+      invoke<string>(commands.applyMutationsCommit, { batch }),
+    applyLeasedMutationsCommit: (batch: SyncularBridgeMutationBatch) =>
+      invoke<string>(commands.applyLeasedMutationsCommit, { batch }),
+    sync: () => invoke<SyncularSyncResult>(commands.sync),
+    resumeFromBackground: (syncOptions) =>
+      invoke<SyncularSyncResult>(commands.resumeFromBackground, {
+        options: syncOptions,
+      }),
+    start: () => invoke<void>(commands.start),
+    stop: () => invoke<void>(commands.stop),
+    setSubscriptions: (subscriptions: readonly SyncularSubscriptionSpec[]) =>
+      invoke<void>(commands.setSubscriptions, {
+        subscriptions: [...subscriptions],
+      }),
+    getStatus: () => status,
+    issueAuthLease: (request: SyncAuthLeaseIssueRequest) =>
+      invoke<SyncularAuthLeaseRecord>(commands.issueAuthLease, { request }),
+    upsertAuthLease: (lease: SyncularAuthLeaseRecord) =>
+      invoke<void>(commands.upsertAuthLease, { lease }),
+    authLease: (leaseId: string) =>
+      invoke<SyncularAuthLeaseRecord | null>(commands.authLease, {
+        leaseId,
+      }),
+    activeAuthLeases: (actorId?: string | null, nowMs?: number) =>
+      invoke<SyncularAuthLeaseRecord[]>(commands.activeAuthLeases, {
+        actorId,
+        nowMs,
+      }),
+    diagnosticSnapshot: () =>
+      invoke<SyncularDiagnosticSnapshot>(commands.diagnosticSnapshot),
+    on: (event, listener) =>
+      listen(options.listen, `${eventPrefix}:${event}`, (payload) => {
+        if (event === 'lifecycleChanged') {
+          status = {
+            ...status,
+            lifecycle: payload as SyncularBridgeStatus['lifecycle'],
+          };
+        }
+        listener(payload as never);
+      }),
+    presence: {
+      get: <TMetadata = Record<string, unknown>>(scopeKey: string) =>
+        (presence.get(scopeKey) ?? []) as SyncularPresenceEntry<TMetadata>[],
+      join: (scopeKey, metadata) => {
+        void invoke<void>(commands.joinPresence, { scopeKey, metadata });
+      },
+      leave: (scopeKey) => {
+        void invoke<void>(commands.leavePresence, { scopeKey });
+      },
+      updateMetadata: (scopeKey, metadata) => {
+        void invoke<void>(commands.updatePresenceMetadata, {
+          scopeKey,
+          metadata,
+        });
+      },
+      onChange: <TMetadata = Record<string, unknown>>(
+        listener: SyncularPresenceSink<TMetadata>
+      ) =>
+        listen(options.listen, `${eventPrefix}:presenceChanged`, (payload) => {
+          const event = payload as SyncularClientEventMap['presenceChanged'];
+          presence.set(event.scopeKey, event.presence);
+          listener(event as Parameters<SyncularPresenceSink<TMetadata>>[0]);
+        }),
+    },
+    conflicts: {
+      list: () => invoke<SyncularConflictSummary[]>(commands.listConflicts),
+      retryKeepLocal: (id) =>
+        invoke<string>(commands.retryConflictKeepLocal, { id }),
+      resolve: (id, resolution: SyncularConflictResolution) =>
+        invoke<void>(commands.resolveConflict, { id, resolution }),
+    },
+  };
+}
+
+function listen<T extends SyncularClientEventType>(
+  listenFn: SyncularTauriListen | undefined,
+  event: string,
+  listener: SyncularClientEventSink<T>
+): () => void {
+  if (!listenFn) return noop;
+  let unlisten: (() => void) | undefined;
+  let closed = false;
+  void listenFn(event, ({ payload }) => listener(payload as never)).then(
+    (nextUnlisten) => {
+      if (closed) {
+        nextUnlisten();
+      } else {
+        unlisten = nextUnlisten;
+      }
+    }
+  );
+  return () => {
+    closed = true;
+    unlisten?.();
+  };
+}
+
+function noop(): void {}