@venturewild/workspace 0.3.7 → 0.3.8

package/server/src/canvas-rails.mjs

@@ -0,0 +1,108 @@
+// CanvasRails — per-identity canvas state on the rails (multi-host step 1).
+//
+// WHY: canvas layout/templates/user-theme used to be per-INSTALL (one folder on
+// one machine). Multi-host (docs/multi-host-workspaces-design.md §8.1) makes them
+// per-(workspace, person) on VW's rails, so a person's arrangement follows them
+// across hosts/devices/reinstalls. The rails (bmo-sync) are the source of truth;
+// the local ~/.wild-workspace/canvas/people/<personKey>/ files become a
+// read-through + offline cache — the same "server is truth, cache below it"
+// pattern lifted one level up.
+//
+// This is a thin client over bmo-sync's POST /api/canvas-state/{pull,push}
+// (account-token self-authed, exactly like /api/telemetry). person_id and the
+// workspace_slug are DERIVED server-side from the account token today — a caller
+// can only touch its own account's row (no IDOR). Modeled on session-reporter.mjs.
+//
+// degrade-never-throw: every method fails soft (pull → {ok:false}, push → false)
+// so the canvas keeps working from the local cache when the rails are down or the
+// install has no account. `pull` distinguishes "rails answered, empty" (ok:true,
+// state:null → migration may fire) from "rails unreachable" (ok:false → serve the
+// local cache, do NOT migrate).
+
+const DEFAULT_TIMEOUT_MS = 3000;
+
+export class CanvasRails {
+  constructor({
+    bmoSyncUrl,
+    accountToken,
+    slug = null,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    fetchImpl = (...a) => globalThis.fetch(...a),
+  } = {}) {
+    this.bmoSyncUrl = bmoSyncUrl ? bmoSyncUrl.replace(/\/$/, '') : null;
+    this.accountToken = accountToken || null;
+    this.slug = slug;
+    this.timeoutMs = timeoutMs;
+    this.fetchImpl = fetchImpl;
+    // Inert without a token (can't key it) or without a server URL. Unlike
+    // telemetry we do NOT exclude localhost — the e2e test points a local
+    // wild-workspace at a local bmo-sync, and dev installs have no account
+    // token anyway, so they stay inert without an extra guard.
+    this.capable = Boolean(this.accountToken) && Boolean(this.bmoSyncUrl);
+  }
+
+  async _post(path, body) {
+    if (!this.capable) return null;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    if (timer.unref) timer.unref();
+    try {
+      const r = await this.fetchImpl(`${this.bmoSyncUrl}${path}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ account_token: this.accountToken, ...body }),
+        signal: ctrl.signal,
+      });
+      if (!r || !r.ok) return null;
+      return await r.json().catch(() => null);
+    } catch {
+      return null; // network / abort / parse — caller degrades to the local cache
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Pull this person's canvas state from the rails.
+   * @returns {Promise<{ok: boolean, state: object|null}>}
+   *   ok:true  → the rails answered. state is the {layout,templates,userTheme}
+   *              object, or null when the rails have nothing yet (→ migration may fire).
+   *   ok:false → the rails were unreachable / not configured (→ serve the local cache).
+   */
+  async pull(workspaceSlug = this.slug) {
+    const resp = await this._post('/api/canvas-state/pull', { workspace_slug: workspaceSlug });
+    if (!resp || resp.ok !== true) return { ok: false, state: null };
+    // resp.json is the stored blob as a STRING (or null/absent when empty).
+    if (resp.json == null || resp.json === '') return { ok: true, state: null };
+    try {
+      const state = JSON.parse(resp.json);
+      return { ok: true, state: state && typeof state === 'object' ? state : null };
+    } catch {
+      return { ok: true, state: null }; // corrupt row → treat as empty
+    }
+  }
+
+  /**
+   * Push this person's FULL canvas snapshot to the rails (last-write-wins; Node
+   * owns the merge, so the rails always receive the complete {layout,templates,
+   * userTheme}). Best-effort.
+   * @returns {Promise<boolean>} true iff the rails accepted the write.
+   */
+  async push(snapshot, workspaceSlug = this.slug) {
+    const resp = await this._post('/api/canvas-state/push', {
+      workspace_slug: workspaceSlug,
+      json: JSON.stringify(snapshot ?? {}),
+    });
+    return Boolean(resp && resp.ok === true);
+  }
+}
+
+/** Build the rails client from server config + account (or null when not logged in). */
+export function createCanvasRails(config, account, fetchImpl) {
+  return new CanvasRails({
+    bmoSyncUrl: config?.bmoSyncServerUrl,
+    accountToken: account?.accountToken,
+    slug: account?.slug || config?.account?.slug || null,
+    fetchImpl,
+  });
+}