@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.210

package/src/modules/devtools/versions.ts

@@ -0,0 +1,110 @@
+/**
+ * Backend versions of the stack components, derived from the entity list the
+ * backend `/info` endpoint exposes (read via the `fn::spooky::info()` SurrealQL
+ * function). Any component that isn't reported degrades to `'unavailable'`.
+ */
+export interface BackendVersions {
+  ssp: string;
+  scheduler: string;
+  surrealdb: string;
+}
+
+export const UNAVAILABLE = 'unavailable';
+
+/**
+ * A single stack entity as reported by `/info` (one per ssp / scheduler /
+ * backend). Carries far more than versions — status, uptime, ip, views — so the
+ * DevTools can render the whole stack. Extra fields are preserved verbatim.
+ */
+/** One end-to-end sync-pipeline probe cycle recorded by the scheduler. */
+export interface HeartbeatSample {
+  ts: number;
+  /** `null` for a failed cycle. */
+  ms: number | null;
+  ok: boolean;
+}
+
+/**
+ * E2E heartbeat state, reported on the scheduler entity only. The scheduler
+ * times a probe row's full round trip (DB event → ingest → broadcast → SSP
+ * circuit step); `samples` is its rolling window of recent cycles, which the
+ * DevTools sparkline renders.
+ */
+export interface HeartbeatInfo {
+  enabled: boolean;
+  stale: boolean;
+  /** Nothing to measure right now (e.g. no ready SSPs mid-bootstrap). */
+  blocked?: boolean;
+  blocked_reason?: string | null;
+  last_e2e_ms: number | null;
+  last_ok_epoch_ms: number | null;
+  consecutive_failures: number;
+  interval_secs: number;
+  samples?: HeartbeatSample[];
+}
+
+export interface BackendEntity {
+  entity: string;
+  id?: string;
+  ip?: string | null;
+  status?: string;
+  version?: string;
+  surrealdb_version?: string;
+  uptime_seconds?: number;
+  views?: number;
+  /** Scheduler entity only. */
+  heartbeat?: HeartbeatInfo;
+  [key: string]: unknown;
+}
+
+export interface BackendInfo {
+  versions: BackendVersions;
+  entities: BackendEntity[];
+}
+
+export function emptyBackendVersions(): BackendVersions {
+  return { ssp: UNAVAILABLE, scheduler: UNAVAILABLE, surrealdb: UNAVAILABLE };
+}
+
+export function emptyBackendInfo(): BackendInfo {
+  return { versions: emptyBackendVersions(), entities: [] };
+}
+
+/** Strip a leading `surrealdb-` so versions read as bare semver (e.g. `2.0.3`). */
+function normalizeServerVersion(v: string): string {
+  return String(v).replace(/^surrealdb-/i, '').trim();
+}
+
+/**
+ * Normalize whatever `RETURN fn::spooky::info()` resolves to into the entity
+ * array. The SurrealQL function returns the parsed `/info` array; depending on
+ * how the result is unwrapped it may arrive as the array itself, a single
+ * object, or `null`. Tolerant of all three.
+ */
+export function toEntityArray(raw: unknown): BackendEntity[] {
+  if (Array.isArray(raw)) return raw.filter((e): e is BackendEntity => !!e && typeof e === 'object');
+  if (raw && typeof raw === 'object') return [raw as BackendEntity];
+  return [];
+}
+
+/**
+ * Derive component versions + the full entity list from a `/info` entity array.
+ * `surrealdb` is taken from whichever entity reports `surrealdb_version` (ssp or
+ * scheduler). Never throws; missing pieces stay `'unavailable'`.
+ */
+export function parseBackendInfo(raw: unknown): BackendInfo {
+  const entities = toEntityArray(raw);
+  const versions = emptyBackendVersions();
+
+  for (const entity of entities) {
+    const version = entity.version ? String(entity.version) : undefined;
+    if (entity.entity === 'ssp' && version) versions.ssp = version;
+    else if (entity.entity === 'scheduler' && version) versions.scheduler = version;
+
+    if (versions.surrealdb === UNAVAILABLE && entity.surrealdb_version) {
+      versions.surrealdb = normalizeServerVersion(String(entity.surrealdb_version));
+    }
+  }
+
+  return { versions, entities };
+}

package/src/modules/feature-flag/index.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { FeatureFlagModule } from './index';
+
+// vitest runs in the `node` environment here, so there is no localStorage.
+// The module guards every access with `globalThis.localStorage?.`, which keeps
+// overrides in-memory-only — this shim lets the persistence path be tested.
+function installLocalStorage() {
+  const store = new Map<string, string>();
+  const shim = {
+    getItem: (k: string) => store.get(k) ?? null,
+    setItem: (k: string, v: string) => void store.set(k, v),
+    removeItem: (k: string) => void store.delete(k),
+  };
+  (globalThis as any).localStorage = shim;
+  return { store, uninstall: () => delete (globalThis as any).localStorage };
+}
+
+// Minimal mocks for the three deps the module touches. The DataModule mock
+// captures the single subscribe callback so a test can push live results, and
+// counts query() calls to assert the query is SHARED (one registration for all
+// flags), not per-key.
+function makeDeps() {
+  let subCb: ((records: unknown[]) => void) | null = null;
+  const calls: Array<{ sql: string; params: unknown }> = [];
+  let authCb: ((userId: string | null) => void) | null = null;
+
+  const dataModule = {
+    query: async (_table: string, sql: string, params: unknown) => {
+      calls.push({ sql, params });
+      return `hash:${calls.length}`;
+    },
+    subscribe: (_hash: string, cb: (records: unknown[]) => void) => {
+      subCb = cb;
+      return () => {
+        subCb = null;
+      };
+    },
+  };
+  const sync = { enqueueDownEvent: () => {} };
+  const auth = {
+    subscribe: (cb: (userId: string | null) => void) => {
+      authCb = cb;
+      return () => {
+        authCb = null;
+      };
+    },
+  };
+  const logger = { child: () => ({ warn: () => {} }) };
+
+  const deps = { dataModule, sync, auth, logger } as any;
+  return {
+    deps,
+    calls,
+    push: (records: unknown[]) => subCb?.(records),
+    setUser: (id: string | null) => authCb?.(id),
+    hasSub: () => subCb !== null,
+  };
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+describe('FeatureFlagModule', () => {
+  let env: ReturnType<typeof makeDeps>;
+  let mod: FeatureFlagModule<any>;
+
+  beforeEach(() => {
+    env = makeDeps();
+    mod = new FeatureFlagModule(env.deps);
+  });
+
+  it('registers ONE shared, unfiltered query for many flags', async () => {
+    mod.feature('alpha');
+    mod.feature('beta');
+    mod.feature('gamma');
+    await tick();
+
+    expect(env.calls.length).toBe(1);
+    expect(env.calls[0].sql).not.toContain('WHERE');
+    expect(env.calls[0].sql).toContain('FROM _00_user_feature');
+    expect(env.calls[0].params).toEqual({});
+  });
+
+  it('fans the shared result out to each handle by key', async () => {
+    const alpha = mod.feature('alpha', { fallback: 'off' });
+    const beta = mod.feature('beta', { fallback: 'off' });
+    const missing = mod.feature('missing', { fallback: 'off' });
+    await tick();
+
+    env.push([
+      { key: 'alpha', variant: 'on' },
+      { key: 'beta', variant: 'off' },
+    ]);
+
+    expect(alpha.enabled()).toBe(true);
+    expect(alpha.variant()).toBe('on');
+    expect(beta.enabled()).toBe(false); // assigned 'off'
+    expect(missing.enabled()).toBe(false); // no row → fallback 'off'
+  });
+
+  it('observes NEW assignments live without re-registering', async () => {
+    const flag = mod.feature('live', { fallback: 'off' });
+    await tick();
+
+    env.push([]); // user starts with no assignment
+    expect(flag.enabled()).toBe(false);
+
+    env.push([{ key: 'live', variant: 'on' }]); // assigned while observing
+    expect(flag.enabled()).toBe(true);
+
+    expect(env.calls.length).toBe(1); // still the same single query
+  });
+
+  it('seeds a late-created handle from the already-loaded snapshot', async () => {
+    mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'on' }]);
+
+    const late = mod.feature('alpha', { fallback: 'off' });
+    expect(late.enabled()).toBe(true); // no fallback flash
+  });
+
+  it('clears flags and re-observes on user change', async () => {
+    mod.init();
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'on' }]);
+    expect(flag.enabled()).toBe(true);
+
+    env.setUser('user:other'); // sign-in as a different user
+    await tick();
+    expect(flag.enabled()).toBe(false); // cleared until the new query resolves
+    expect(env.hasSub()).toBe(true); // re-registered for the new user
+  });
+});
+
+// Local overrides force a variant in THIS browser only. They must win over the
+// server assignment on every read path — `variant()`, `payload()`, `enabled()`
+// and `subscribe()` all funnel through the same resolver, so a gap in any one
+// of them is a gap in all of them.
+describe('FeatureFlagModule local overrides', () => {
+  let env: ReturnType<typeof makeDeps>;
+  let mod: FeatureFlagModule<any>;
+  let ls: ReturnType<typeof installLocalStorage>;
+
+  beforeEach(() => {
+    ls = installLocalStorage();
+    env = makeDeps();
+    mod = new FeatureFlagModule(env.deps);
+  });
+
+  afterEach(() => ls.uninstall());
+
+  it('wins over the server assignment', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'off' }]);
+    expect(flag.enabled()).toBe(false);
+
+    mod.setLocalOverride('alpha', 'on');
+    expect(flag.variant()).toBe('on');
+    expect(flag.enabled()).toBe(true);
+  });
+
+  it('survives a later live result for the same key', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    mod.setLocalOverride('alpha', 'on');
+
+    env.push([{ key: 'alpha', variant: 'off' }]); // server disagrees
+    expect(flag.variant()).toBe('on');
+  });
+
+  it('applies before the first result, without a fallback flash', () => {
+    mod.setLocalOverride('alpha', 'on');
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    expect(flag.variant()).toBe('on'); // seeded even though nothing loaded yet
+  });
+
+  it('carries its own payload', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'off', payload: { copy: 'server' } }]);
+
+    mod.setLocalOverride('alpha', 'on', { copy: 'local' });
+    expect(flag.payload()).toEqual({ copy: 'local' });
+  });
+
+  it('notifies subscribers when set and cleared', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'off' }]);
+
+    const seen: (string | undefined)[] = [];
+    flag.subscribe((s) => seen.push(s.variant));
+    expect(seen).toEqual(['off']); // immediate call
+
+    mod.setLocalOverride('alpha', 'on');
+    mod.setLocalOverride('alpha', null);
+    expect(seen).toEqual(['off', 'on', 'off']);
+  });
+
+  it('restores the server assignment when cleared', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'treatment', payload: { copy: 'server' } }]);
+
+    mod.setLocalOverride('alpha', 'off');
+    expect(flag.variant()).toBe('off');
+
+    mod.clearLocalOverrides();
+    expect(flag.variant()).toBe('treatment');
+    expect(flag.payload()).toEqual({ copy: 'server' });
+  });
+
+  it('survives a user change — it is a browser setting, not a session one', async () => {
+    mod.init();
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    mod.setLocalOverride('alpha', 'on');
+
+    env.setUser('user:other');
+    await tick();
+    expect(flag.variant()).toBe('on');
+  });
+
+  it('persists to localStorage and reloads into a fresh module', () => {
+    mod.setLocalOverride('alpha', 'on', { copy: 'local' });
+    expect(mod.getLocalOverrides()).toEqual({ alpha: { variant: 'on', payload: { copy: 'local' } } });
+
+    // A new module reads the same page-origin store, as after a reload.
+    const reloaded = new FeatureFlagModule(makeDeps().deps);
+    expect(reloaded.getLocalOverrides()).toEqual({
+      alpha: { variant: 'on', payload: { copy: 'local' } },
+    });
+    expect(reloaded.feature('alpha', { fallback: 'off' }).variant()).toBe('on');
+  });
+
+  it('drops the storage key entirely once the last override is cleared', () => {
+    mod.setLocalOverride('alpha', 'on');
+    expect(ls.store.size).toBe(1);
+
+    mod.setLocalOverride('alpha', null);
+    expect(ls.store.size).toBe(0);
+    expect(new FeatureFlagModule(makeDeps().deps).getLocalOverrides()).toEqual({});
+  });
+
+  it('ignores a corrupt store rather than failing to construct', () => {
+    ls.store.set('sp00ky:feature-overrides', '{not json');
+    expect(() => new FeatureFlagModule(makeDeps().deps)).not.toThrow();
+  });
+});

package/src/modules/feature-flag/index.ts

@@ -0,0 +1,308 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { DataModule } from '../data/index';
+import type { Sp00kySync } from '../sync/index';
+import type { AuthService } from '../auth/index';
+import type { Logger } from '../../services/logger/index';
+import type { QueryTimeToLive } from '../../types';
+
+// One shared LIVE query over ALL of the signed-in user's assignments — the
+// `_00_user_feature` select permission scopes it to `user = $auth.id`, so no
+// per-key `WHERE key = $key` param is needed. A single registration means every
+// flag the user is (or becomes) assigned is observed at once: new assignments
+// stream in live, and a handle for an unassigned key simply resolves to its
+// fallback. Avoids one-registration-per-flag and the param-filtered live query.
+const FEATURE_QUERY = 'SELECT key, variant, payload FROM _00_user_feature';
+
+// Local overrides live on the PAGE origin, so they survive reloads and are
+// shared across tabs of the app. Deliberately not the DevTools panel's own
+// storage — the panel runs on a different origin and would get a separate
+// bucket.
+const OVERRIDE_STORAGE_KEY = 'sp00ky:feature-overrides';
+
+interface FeatureRow {
+  key?: string;
+  variant?: string;
+  payload?: unknown;
+}
+
+export interface FeatureFlagSnapshot {
+  variant: string | undefined;
+  payload: unknown | undefined;
+}
+
+export interface FeatureFlagOptions {
+  fallback?: string;
+  ttl?: QueryTimeToLive;
+}
+
+/**
+ * A locally forced variant. Applies to THIS browser only and is never sent to
+ * the server — the assignment in `_00_user_feature` is untouched, so clearing
+ * the override restores whatever the server says.
+ */
+export interface FeatureFlagOverride {
+  variant: string;
+  payload?: unknown;
+}
+
+export class FeatureFlagHandle {
+  private latest: FeatureFlagSnapshot = { variant: undefined, payload: undefined };
+  private listeners = new Set<(s: FeatureFlagSnapshot) => void>();
+  private unsubscribeFn: (() => void) | null = null;
+  private onCloseFn: (() => void) | null = null;
+  private closed = false;
+
+  constructor(
+    public readonly key: string,
+    public readonly fallback: string | undefined,
+  ) {}
+
+  attach(unsubscribe: () => void): void {
+    this.unsubscribeFn?.();
+    this.unsubscribeFn = unsubscribe;
+  }
+
+  detach(): void {
+    this.unsubscribeFn?.();
+    this.unsubscribeFn = null;
+  }
+
+  set(snapshot: FeatureFlagSnapshot): void {
+    if (this.closed) return;
+    this.latest = snapshot;
+    for (const cb of this.listeners) cb(snapshot);
+  }
+
+  variant(): string | undefined {
+    return this.latest.variant ?? this.fallback;
+  }
+
+  payload<T = unknown>(): T | undefined {
+    return this.latest.payload as T | undefined;
+  }
+
+  enabled(): boolean {
+    const v = this.variant();
+    return v !== undefined && v !== 'off';
+  }
+
+  subscribe(cb: (s: FeatureFlagSnapshot) => void): () => void {
+    this.listeners.add(cb);
+    cb({ variant: this.variant(), payload: this.latest.payload });
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+
+  onClose(cb: () => void): void {
+    this.onCloseFn = cb;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.listeners.clear();
+    this.detach();
+    this.onCloseFn?.();
+  }
+}
+
+export interface FeatureFlagModuleDeps<S extends SchemaStructure> {
+  dataModule: DataModule<S>;
+  sync: Sp00kySync<S>;
+  auth: AuthService<S>;
+  logger: Logger;
+}
+
+export class FeatureFlagModule<S extends SchemaStructure> {
+  private logger: Logger;
+  private handles = new Set<FeatureFlagHandle>();
+  private authUnsubscribe: (() => void) | null = null;
+  private lastUserId: string | null = null;
+
+  // The single shared live query over the user's assignments.
+  private querySubscription: (() => void) | null = null;
+  private starting = false;
+  // Longest TTL any caller asked for (the query is shared across all flags).
+  private ttl: QueryTimeToLive = '10m';
+  // Latest assignment per key, plus whether the query has resolved at least
+  // once (so a handle created before the first result knows to wait vs. fall
+  // back). `snapshots` only holds ASSIGNED keys; an absent key → fallback.
+  private snapshots = new Map<string, FeatureFlagSnapshot>();
+  private loaded = false;
+  // Developer-forced variants, this browser only. Take precedence over the
+  // server assignment for every read path.
+  private overrides = new Map<string, FeatureFlagOverride>();
+
+  constructor(private deps: FeatureFlagModuleDeps<S>) {
+    this.logger = deps.logger.child({ service: 'FeatureFlagModule' });
+    // Loaded in the constructor rather than `init()` so an override applies
+    // even when `client.feature()` is called before auth resolves.
+    this.loadOverrides();
+  }
+
+  init(): void {
+    if (this.authUnsubscribe) return;
+    this.authUnsubscribe = this.deps.auth.subscribe((userId) => {
+      if (userId === this.lastUserId) return;
+      this.lastUserId = userId;
+      void this.refresh();
+    });
+  }
+
+  feature(key: string, options: FeatureFlagOptions = {}): FeatureFlagHandle {
+    const handle = new FeatureFlagHandle(key, options.fallback);
+    this.handles.add(handle);
+    handle.onClose(() => this.handles.delete(handle));
+    if (options.ttl) this.ttl = options.ttl;
+    // If the shared query already resolved, seed this handle immediately so a
+    // late `feature()` call doesn't flash the fallback for an assigned key.
+    // An override seeds it too, even before the first result: forcing a
+    // variant should take effect instantly, not one round trip later.
+    if (this.loaded || this.overrides.has(key)) {
+      handle.set(this.resolve(key));
+    }
+    void this.ensureStarted();
+    return handle;
+  }
+
+  async closeAll(): Promise<void> {
+    this.authUnsubscribe?.();
+    this.authUnsubscribe = null;
+    this.teardownQuery();
+    for (const handle of [...this.handles]) handle.close();
+  }
+
+  /** Auth changed: drop the old user's query/snapshots and re-observe. */
+  private async refresh(): Promise<void> {
+    this.teardownQuery();
+    this.loaded = false;
+    this.snapshots.clear();
+    // Clear handles immediately so a sign-out hides flag-gated UI without lag.
+    // `resolve` keeps any local override in place across the switch — it is a
+    // developer setting for this browser, not part of the session.
+    for (const handle of this.handles) {
+      handle.set(this.resolve(handle.key));
+    }
+    await this.ensureStarted();
+  }
+
+  private teardownQuery(): void {
+    this.querySubscription?.();
+    this.querySubscription = null;
+  }
+
+  /** Start the single shared live query (idempotent; no-op with no handles). */
+  private async ensureStarted(): Promise<void> {
+    if (this.querySubscription || this.starting || this.handles.size === 0) return;
+    this.starting = true;
+    try {
+      const hash = await this.deps.dataModule.query(
+        '_00_user_feature' as any,
+        FEATURE_QUERY,
+        {},
+        this.ttl,
+      );
+      this.deps.sync.enqueueDownEvent({ type: 'register', payload: { hash } });
+      this.querySubscription = this.deps.dataModule.subscribe(
+        hash,
+        (records) => this.applyRecords(records as FeatureRow[]),
+        { immediate: true },
+      );
+    } catch (err) {
+      this.logger.warn(
+        { err, Category: 'sp00ky-client::FeatureFlagModule::register' },
+        'Failed to register feature flag query',
+      );
+    } finally {
+      this.starting = false;
+    }
+  }
+
+  /** Live query result → per-key snapshots → push to every active handle. */
+  private applyRecords(records: FeatureRow[]): void {
+    this.snapshots.clear();
+    for (const row of records ?? []) {
+      if (row && typeof row.key === 'string') {
+        this.snapshots.set(row.key, { variant: row.variant, payload: row.payload });
+      }
+    }
+    this.loaded = true;
+    this.pushAll();
+  }
+
+  // ===========================================================
+  // Local overrides (this browser only)
+  // ===========================================================
+
+  /**
+   * Force `key` to `variant` in THIS browser. Pass `null` to clear.
+   *
+   * Nothing is written to the server: the `_00_user_feature` assignment is
+   * untouched, so clearing restores whatever the server says. Persisted to
+   * localStorage on the page origin, so it survives a reload.
+   */
+  setLocalOverride(key: string, variant: string | null, payload?: unknown): void {
+    if (variant === null) this.overrides.delete(key);
+    else this.overrides.set(key, { variant, payload });
+    this.persistOverrides();
+    this.pushAll();
+  }
+
+  clearLocalOverrides(): void {
+    this.overrides.clear();
+    this.persistOverrides();
+    this.pushAll();
+  }
+
+  getLocalOverrides(): Record<string, FeatureFlagOverride> {
+    return Object.fromEntries(this.overrides);
+  }
+
+  /** The assignment for `key`, with any local override taking precedence. */
+  private resolve(key: string): FeatureFlagSnapshot {
+    const override = this.overrides.get(key);
+    if (override) return { variant: override.variant, payload: override.payload };
+    return this.snapshots.get(key) ?? { variant: undefined, payload: undefined };
+  }
+
+  private pushAll(): void {
+    for (const handle of this.handles) handle.set(this.resolve(handle.key));
+  }
+
+  private loadOverrides(): void {
+    try {
+      const raw = globalThis.localStorage?.getItem(OVERRIDE_STORAGE_KEY);
+      if (!raw) return;
+      const parsed = JSON.parse(raw) as Record<string, FeatureFlagOverride>;
+      for (const [key, value] of Object.entries(parsed ?? {})) {
+        if (value && typeof value.variant === 'string') this.overrides.set(key, value);
+      }
+    } catch (err) {
+      // Best-effort: a corrupt or unavailable store must never stop the
+      // client from booting. Same posture as the DevTools prefs helper.
+      this.logger.warn(
+        { err, Category: 'sp00ky-client::FeatureFlagModule::loadOverrides' },
+        'Failed to read local feature flag overrides',
+      );
+    }
+  }
+
+  private persistOverrides(): void {
+    try {
+      if (this.overrides.size === 0) {
+        globalThis.localStorage?.removeItem(OVERRIDE_STORAGE_KEY);
+        return;
+      }
+      globalThis.localStorage?.setItem(
+        OVERRIDE_STORAGE_KEY,
+        JSON.stringify(this.getLocalOverrides()),
+      );
+    } catch (err) {
+      this.logger.warn(
+        { err, Category: 'sp00ky-client::FeatureFlagModule::persistOverrides' },
+        'Failed to persist local feature flag overrides',
+      );
+    }
+  }
+}