@spooky-sync/core 0.0.1-canary.32 → 0.0.1-canary.321

package/src/client/services.ts

@@ -0,0 +1,418 @@
+import type { Uuid } from 'surrealdb';
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { Sp00kyConfig, PersistenceClient } from '../types';
+import type { Logger } from '../services/logger/index';
+import { LogTap, createLogger } from '../services/logger/index';
+import { ConnectionSupervisor, LocalMigrator, RemoteDatabaseService, createLocalEngine } from '../services/database/index';
+import type { LocalStore } from '../services/database/index';
+import { StreamProcessorService } from '../services/stream-processor/index';
+import type { StreamUpdate } from '../services/stream-processor/index';
+import { extractSelectPermissions } from '../services/stream-processor/permissions';
+import { EventSystem } from '../events/index';
+import { AuthService } from '../modules/auth/index';
+import { CrdtManager } from '../modules/crdt/index';
+import { preloadLoro } from '../modules/crdt/loro-loader';
+import { LocalStoragePersistenceClient } from '../services/persistence/localstorage';
+import { SurrealDBPersistenceClient } from '../services/persistence/surrealdb';
+import { ResilientPersistenceClient } from '../services/persistence/resilient';
+import { ANON_USER_ID } from '../modules/ref-tables';
+import { detectSharedTabsSupport } from '../services/tabs/support';
+import { TabsCoordinator, type CoordinatorHooks } from '../services/tabs/coordinator';
+import type { LeaderSyncHub, SyncForwarder } from '../services/tabs/coordinator';
+import { computeTabsFingerprint, hash53 } from '../services/tabs/protocol';
+import type { SqliteCacheEngine } from '../services/database/sqlite-cache-engine';
+import type { BlobCache } from '../services/blobs/index';
+import { MemoryBlobStore, createBlobCache, resolveBlobBudget } from '../services/blobs/index';
+import type { Adapters } from '../kernel/interpreter';
+import type { RuntimeEvent } from '../kernel/events';
+import type { ServiceCalls } from '../kernel/effects';
+import { encodeRecordId } from '../utils/index';
+import { sha256Hex } from '../utils/sha256';
+import { leaveViewsBeacon, listRefLive } from '../query/sql';
+import { hashOfEdge, rowOfEdge } from '../utils/edges';
+import { mintMutationId } from '../mutation/mutation-id';
+import { BucketHandle, bucketContentToBlob } from './bucket-handle';
+
+const LAST_BUCKET_KEY = 'sp00ky:last_bucket';
+
+export function readBootBucketHint(): string | null {
+  try {
+    return typeof localStorage !== 'undefined' ? localStorage.getItem(LAST_BUCKET_KEY) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeBootBucketHint(bucketId: string): void {
+  try {
+    if (typeof localStorage !== 'undefined') localStorage.setItem(LAST_BUCKET_KEY, bucketId);
+  } catch {
+    /* private-mode storage errors: boot falls back to the anon bucket */
+  }
+}
+
+const RELOAD_SALT_KEY = 'sp00ky:salt';
+
+/**
+ * Take the salt this tab's previous page left on its way out, if it was minted
+ * for the same principal. A reload that keeps its salt re-registers every
+ * query onto the `_00_query` row it already had, which the SSP answers from
+ * the live view instead of building a new one.
+ *
+ * Taken, not read: the key is absent while a page lives, so a duplicated tab
+ * (which copies sessionStorage) mints its own salt rather than sharing this
+ * tab's remote views.
+ */
+export function takeReloadSalt(authId: string | null): { salt: string; sessionIds: string[] } | null {
+  try {
+    if (typeof sessionStorage === 'undefined') return null;
+    const raw = sessionStorage.getItem(RELOAD_SALT_KEY);
+    if (raw === null) return null;
+    sessionStorage.removeItem(RELOAD_SALT_KEY);
+    const left = JSON.parse(raw) as { salt?: unknown; authId?: unknown; sessionIds?: unknown };
+    if (typeof left.salt !== 'string' || left.salt === '' || (left.authId ?? null) !== authId) return null;
+    const sessionIds = Array.isArray(left.sessionIds) ? left.sessionIds.filter((sid): sid is string => typeof sid === 'string') : [];
+    return { salt: left.salt, sessionIds };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Leave this page's salt for the next page in this tab; see {@link takeReloadSalt}.
+ *
+ * The session ids of this page's sockets go with it. The views the next page
+ * re-registers keep the edges this page's sockets stamped, and the anonymous
+ * LIVE only hears edges stamped by a session it knows (see `listRefLive`).
+ */
+export function leaveReloadSalt(salt: string, authId: string | null, sessionIds: ReadonlyArray<string> = []): void {
+  try {
+    if (typeof sessionStorage !== 'undefined')
+      sessionStorage.setItem(RELOAD_SALT_KEY, JSON.stringify({ salt, authId, sessionIds }));
+  } catch {
+    /* private-mode storage errors: the next page mints a fresh salt */
+  }
+}
+
+// Moved to a pure module so `@spooky-sync/core/pure` and the live feed share
+// it; re-exported here for existing imports.
+export { sha256Hex };
+
+export function mintSalt(): string {
+  const c = (globalThis as { crypto?: Crypto }).crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `s${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
+}
+
+/** Everything the facade talks to besides the runtime. */
+export interface Services<S extends SchemaStructure> {
+  logger: Logger;
+  /** What the logger wrote, for the DevTools Logs tab. Absent in test fakes. */
+  logTap?: LogTap;
+  local: LocalStore;
+  remote: RemoteDatabaseService;
+  connectionSupervisor: ConnectionSupervisor;
+  blobs: BlobCache;
+  persistence: PersistenceClient;
+  streamProcessor: StreamProcessorService;
+  migrator: LocalMigrator;
+  crdt: CrdtManager;
+  auth: AuthService<S>;
+  tabs: TabsCoordinator | null;
+  tabsUnsupportedReason: string | undefined;
+  tabId: string;
+}
+
+/** What the services need back from the runtime once it exists. */
+export interface ServiceHost {
+  dispatch(event: RuntimeEvent): void;
+  /** Called by the tabs coordinator hooks with the hub / forwarder to relay through. */
+  setTabsChannel(channel: { hub: LeaderSyncHub | null; forwarder: SyncForwarder | null }): void;
+  /** Late-bound modules the boot saga starts (feature flags, app releases). */
+  initModules(): void;
+  detachWindow(): void;
+  setDetachWindow(fn: () => void): void;
+}
+
+export function createServices<S extends SchemaStructure>(config: Sp00kyConfig<S>): Services<S> {
+  const logTap = new LogTap(config.logLevel ?? 'info');
+  const logger = createLogger(config.logLevel ?? 'info', config.otelTransmit, logTap);
+  if (config.crdt) void preloadLoro();
+  const tabsSupport = detectSharedTabsSupport(config);
+  const local = createLocalEngine(config.localEngine, config.database, logger, { shared: tabsSupport.supported });
+  const remote = new RemoteDatabaseService(config.database, logger);
+  const connectionSupervisor = new ConnectionSupervisor(remote, logger);
+  const rawBucket = (name: string) => new BucketHandle(name, remote, null, { blurhash: config.blurhash, logger });
+  const blobs = createBlobCache({
+    local,
+    namespace: ANON_USER_ID,
+    logger,
+    fetchRemote: async (key) => bucketContentToBlob(await rawBucket(key.bucket).get(key.path)),
+    headRemote: (key) => rawBucket(key.bucket).head(key.path),
+    maxBytes: config.blobCache?.maxBytes,
+    store: config.blobCache?.enabled === false ? new MemoryBlobStore(ANON_USER_ID) : undefined,
+  });
+  let persistence: PersistenceClient;
+  if (config.persistenceClient === 'surrealdb') persistence = new SurrealDBPersistenceClient(local, logger);
+  else if (config.persistenceClient === 'localstorage' || !config.persistenceClient) persistence = new LocalStoragePersistenceClient(logger);
+  else persistence = config.persistenceClient;
+  persistence = new ResilientPersistenceClient(persistence, logger);
+  const streamProcessor = new StreamProcessorService(new EventSystem(['stream_update']), local, logger);
+  streamProcessor.configureCircuitPersistence(config.persistCircuit ?? config.localEngine === 'sqlite', config.circuitCheckpointMs);
+  streamProcessor.configureProjection(config.circuitProjection ?? true);
+  const migrator = new LocalMigrator(local, logger);
+  const crdt = new CrdtManager(config.schema, local, remote, logger, config.crdtDebounceMs ?? 500);
+  const auth = new AuthService(config.schema, remote, persistence, logger);
+  const tabId = typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `tab_${Math.random().toString(36).slice(2)}`;
+  return {
+    logger,
+    logTap,
+    local,
+    remote,
+    connectionSupervisor,
+    blobs,
+    persistence,
+    streamProcessor,
+    migrator,
+    crdt,
+    auth,
+    tabs: null,
+    tabsUnsupportedReason: tabsSupport.supported ? undefined : (tabsSupport as { reason: string }).reason,
+    tabId,
+  };
+}
+
+/** The shared-tabs coordinator, wired so role changes and relays become runtime events. */
+export function createTabsCoordinator<S extends SchemaStructure>(config: Sp00kyConfig<S>, s: Services<S>, host: ServiceHost): TabsCoordinator {
+  const engine = s.local as SqliteCacheEngine;
+  const hooks: CoordinatorHooks = {
+    adoptOwner: (bucketId, opts) =>
+      engine.adoptOwner(bucketId, { workerLockName: opts.workerLockName, allowMemoryFallback: opts.allowMemoryFallback, resumeHeld: opts.resumeHeld }),
+    adoptAttached: (dbPort, snapshot) => engine.adoptAttached(dbPort, snapshot, (reason) => engine.onLeaderLost(reason)),
+    releaseOwnership: () => engine.releaseOwnership(),
+    onLeaderLost: (reason) => engine.onLeaderLost(reason),
+    exposeClientPort: (clientId, port) => engine.exposeClientPort(clientId, port),
+    removeClientPort: (clientId) => engine.removeClientPort(clientId),
+    becomeSyncLeader: (hub) => {
+      s.streamProcessor.setPersistenceEnabled(true);
+      hub.onFollowerMessage = (_tabId, msg) => host.dispatch({ type: 'TabMessage', message: followerToRuntime(msg) });
+      host.setTabsChannel({ hub, forwarder: null });
+      host.dispatch({ type: 'TabRole', role: 'leader' });
+    },
+    resumeSyncLeaderDuties: async () => {
+      host.dispatch({ type: 'Drain' });
+      host.dispatch({ type: 'LiveStart' });
+    },
+    becomeSyncFollower: (forwarder) => {
+      s.streamProcessor.setPersistenceEnabled(false);
+      forwarder.onLeaderMessage = (msg) => host.dispatch({ type: 'TabMessage', message: leaderToRuntime(msg) });
+      host.setTabsChannel({ hub: null, forwarder });
+      host.dispatch({ type: 'TabRole', role: 'follower' });
+    },
+    becomeSyncSolo: () => {
+      s.streamProcessor.setPersistenceEnabled(true);
+      host.setTabsChannel({ hub: null, forwarder: null });
+      host.dispatch({ type: 'TabRole', role: 'solo' });
+    },
+    currentStorageHealth: () => s.local.storageHealth ?? { status: 'unknown', fallback: false },
+  };
+  return new TabsCoordinator({
+    tabId: s.tabId,
+    fingerprint: computeTabsFingerprint({
+      coreVersion: typeof __SP00KY_CORE_VERSION__ !== 'undefined' ? __SP00KY_CORE_VERSION__ : 'unknown',
+      schemaHash: hash53(config.schemaSurql),
+      endpoint: config.database.endpoint ?? '',
+      namespace: config.database.namespace,
+      database: config.database.database,
+    }),
+    hooks,
+    logger: s.logger,
+    onLeaderPageHide: () => void engine.shutdownOwnedWorker(),
+  });
+}
+
+/** Wire-protocol messages become the runtime's tab messages. */
+export function followerToRuntime(msg: { type: string; [k: string]: unknown }): unknown {
+  switch (msg.type) {
+    case 'mutation-enqueued':
+      return { type: 'outbox-changed', mutationId: msg.mutationId };
+    case 'ingest':
+      return { type: 'ingest', records: msg.tuples };
+    case 'request-poll':
+      return { type: 'membership-dirty', hashes: [] };
+    default:
+      return msg;
+  }
+}
+
+export function leaderToRuntime(msg: { type: string; [k: string]: unknown }): unknown {
+  switch (msg.type) {
+    case 'ingest-relay':
+      return { type: 'ingest', records: msg.tuples };
+    default:
+      return msg;
+  }
+}
+
+// Edge decoding lives in a pure module (the wasm-free live feed uses it too);
+// re-exported here for existing imports.
+export { hashOfEdge, rowOfEdge };
+
+/** Build the adapters the interpreter drives from the services. */
+export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S>, s: Services<S>, host: ServiceHost, lateModules: () => { init(): void }[]): Adapters {
+  const timers = new Map<string, ReturnType<typeof setTimeout>>();
+  const services: ServiceCalls = {
+    'hint.read': readBootBucketHint,
+    'hint.write': writeBootBucketHint,
+    'salt.take': (authId) => {
+      const left = takeReloadSalt(authId);
+      if (!left) return null;
+      s.remote.adoptSessionIds(left.sessionIds);
+      return left.salt;
+    },
+    'salt.leave': (salt, authId) => leaveReloadSalt(salt, authId, s.remote.sessionIds()),
+    'local.connect': (bucketId) => s.local.connect(bucketId),
+    'local.switchStore': (bucketId) => s.local.switchStore(bucketId),
+    'local.beginSwitch': () => s.local.beginSwitch(),
+    'local.currentBucketId': () => s.local.currentBucketId,
+    'local.usesSurqlSchema': () => s.local.usesSurqlSchema,
+    'local.dropBucket': async (bucketId) => {
+      await s.local.dropBucket?.(bucketId);
+    },
+    'migrator.provision': () => s.migrator.provision(config.schemaSurql),
+    'blobs.start': async (bucketId) => {
+      s.blobs.setMaxBytes(await resolveBlobBudget(config.blobCache?.maxBytes));
+      await s.blobs.start(bucketId);
+    },
+    'blobs.setNamespace': (bucketId) => s.blobs.setNamespace(bucketId),
+    'blobs.clear': () => s.blobs.clear(),
+    'ssp.init': () => s.streamProcessor.init(),
+    'ssp.setPermissions': () => s.streamProcessor.setPermissions(extractSelectPermissions(config.schemaSurql)),
+    'ssp.setSessionAuth': (authId, access) => s.streamProcessor.setSessionAuth(authId, access),
+    'ssp.prime': (pendingIds) =>
+      s.streamProcessor.primeFromLocal({
+        tables: [...config.schema.tables.map((t) => t.name), '_00_user_feature', '_00_app_release'],
+        schemaHash: String(hash53(config.schemaSurql)),
+        pendingIds: new Set(pendingIds),
+        onVersions: (_table, entries) => host.dispatch({ type: 'VersionsPrimed', entries }),
+      }),
+    'ssp.reset': () => s.streamProcessor.reset(),
+    'ssp.setPersistence': (enabled) => s.streamProcessor.setPersistenceEnabled(enabled),
+    'auth.restoreSession': () => s.auth.restoreSessionFromToken(),
+    'auth.init': () => s.auth.init(),
+    'auth.sessionAuthId': () => {
+      const id = s.auth.currentUser?.id;
+      if (!id) return null;
+      return typeof id === 'string' ? id : encodeRecordId(id);
+    },
+    'auth.access': () => s.auth.access,
+    'auth.token': () => s.auth.token,
+    'auth.currentUser': () => (s.auth.currentUser as Record<string, unknown> | null) ?? null,
+    'auth.consumeEndedImpersonation': () => s.auth.consumeEndedImpersonation(),
+    'remote.connect': () => s.remote.connect(),
+    'remote.releaseViews': (ids) => {
+      const sql = leaveViewsBeacon(ids, s.remote.sessionIds());
+      if (sql) s.remote.beaconSql(sql);
+    },
+    'supervisor.start': () => s.connectionSupervisor.start(),
+    'tabs.start': (bucketId) => {
+      if (!s.tabs) throw new Error('shared tabs unavailable');
+      return s.tabs.start(bucketId);
+    },
+    'tabs.moveToBucket': (bucketId) => {
+      if (!s.tabs) throw new Error('shared tabs unavailable');
+      return s.tabs.moveToBucket(bucketId);
+    },
+    'crdt.setSessionId': (id) => s.crdt.setSessionId(id),
+    'crdt.closeAll': (flush) => s.crdt.closeAll({ flush }),
+    'persistence.set': (key, value) => s.persistence.set(key, value),
+    'features.init': () => {
+      for (const m of lateModules()) m.init();
+    },
+    'releases.init': () => undefined,
+    'window.attach': () => {
+      if (typeof window === 'undefined' || typeof window.addEventListener !== 'function') return;
+      // Hidden is the last moment a page reliably gets to run: a reload or a
+      // closed tab follows it, and a backgrounded mobile tab may be killed
+      // without any further event. Pending debounced writes go out then.
+      const onPageHide = (event: PageTransitionEvent) => {
+        host.dispatch({ type: 'FlushPendingWrites' });
+        if (event.persisted) return;
+        host.dispatch({ type: 'PageHide' });
+      };
+      const onWake = () => {
+        if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return;
+        host.dispatch({ type: 'HeartbeatNow' });
+      };
+      const onVisibility = () => {
+        if (document.visibilityState === 'hidden') host.dispatch({ type: 'FlushPendingWrites' });
+        else onWake();
+      };
+      window.addEventListener('pagehide', onPageHide);
+      window.addEventListener('online', onWake);
+      if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVisibility);
+      host.setDetachWindow(() => {
+        window.removeEventListener('pagehide', onPageHide);
+        window.removeEventListener('online', onWake);
+        if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVisibility);
+      });
+    },
+  };
+  return {
+    local: s.local,
+    remote: {
+      queryResponses: (sql, vars) => s.remote.queryResponses(sql, vars),
+      live: async (table, onChange) => {
+        // `FETCH out` resolves the edge's target into the notification, so the
+        // body arrives with the doorbell instead of costing a second round
+        // trip. The clause is only ever added, never relied on: a server that
+        // ignores it, or a row the session cannot read, simply yields no
+        // inline row and the fetch path takes over.
+        const stmt = listRefLive(table, { inlineBodies: config.liveInlineBodies === true, sessionIds: s.remote.sessionIds() });
+        const [uuid] = await s.remote.query<[Uuid]>(stmt.sql, stmt.vars);
+        const live = await s.remote.getClient().liveOf(uuid);
+        live.subscribe((message) => {
+          if (message.action === 'KILLED') return;
+          const hash = hashOfEdge(message.value);
+          if (!hash) return;
+          // Not on DELETE: that edge is a row leaving the view, and for a row
+          // that was actually deleted the join yields nothing anyway. Landing
+          // a body there would only ever write back what is going away.
+          const row = message.action === 'DELETE' ? null : rowOfEdge(message.value);
+          onChange([hash], row ? [row] : undefined);
+        });
+        return String(uuid);
+      },
+      kill: async (uuid) => {
+        await s.remote.query('KILL $u', { u: uuid });
+      },
+    },
+    ssp: {
+      registerQueryPlan: (plan) => s.streamProcessor.registerQueryPlan(plan) as StreamUpdate | undefined,
+      unregisterQueryPlan: (hash) => s.streamProcessor.unregisterQueryPlan(hash),
+      ingestMany: (records) => s.streamProcessor.ingestMany(records),
+    },
+    timers: {
+      set: (key, ms, fire) => {
+        const prev = timers.get(key);
+        if (prev) clearTimeout(prev);
+        timers.set(
+          key,
+          setTimeout(() => {
+            timers.delete(key);
+            fire();
+          }, ms)
+        );
+      },
+      clear: (key) => {
+        const prev = timers.get(key);
+        if (prev) clearTimeout(prev);
+        timers.delete(key);
+      },
+    },
+    clock: { now: () => Date.now() },
+    ids: { mutation: () => mintMutationId(s.tabId), salt: mintSalt },
+    hash: sha256Hex,
+    services,
+  };
+}