@bygghammar/cms-platform 0.80.1 → 0.90.0-m7.10

package/src/server/edit-lock-supabase-adapter.ts

@@ -0,0 +1,135 @@
+/**
+ * The editing-lock adapter for hosts that already talk PostgREST.
+ *
+ * Every Supabase- and PostgREST-shaped assumption in this feature lives in
+ * this one file: calling database functions by name, passing `_`-prefixed
+ * named arguments, reading `{ data, error }` instead of catching, and knowing
+ * that `PGRST202` means "no such function". `edit-locks-core` knows none of
+ * it, so a host on ordinary PostgreSQL simply never imports this module.
+ */
+import { asEditLockState } from "../cms/edit-lock";
+import {
+  EditLockNotInstalledError,
+  type EditLockAcquireInput,
+  type EditLockAdapter,
+  type EditLockReleaseInput,
+  type EditLockRow,
+  type EditLockStatusInput,
+} from "./edit-lock-adapter";
+import { assertStaff, type PlatformAuthContext } from "./guards";
+
+/**
+ * Codes and wording that mean "this installation has not run the editing-lock
+ * migration yet". `PGRST202`/`PGRST203` come from PostgREST, `42883`/`42P01`
+ * from PostgreSQL itself.
+ */
+const NOT_INSTALLED = new Set(["PGRST202", "PGRST203", "42883", "42P01"]);
+
+type PostgrestError = { code?: string | null; message?: string | null } | null;
+
+function notInstalled(error: PostgrestError): boolean {
+  if (!error) return false;
+  if (error.code && NOT_INSTALLED.has(error.code)) return true;
+  return /could not find the function|does not exist/i.test(
+    String(error.message ?? ""),
+  );
+}
+
+/**
+ * One database-function call, with the two failure modes separated: a missing
+ * function becomes `EditLockNotInstalledError`, anything else is a real error.
+ */
+async function rpc(
+  context: PlatformAuthContext,
+  fn: string,
+  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+  args: Record<string, any>,
+  whenFailed: string,
+): Promise<unknown> {
+  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+  const { data, error } = (await context.supabase.rpc(
+    /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+    fn as any,
+    /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+    args as any,
+  )) as { data: unknown; error: PostgrestError };
+  if (error) {
+    if (notInstalled(error)) throw new EditLockNotInstalledError(whenFailed);
+    throw new Error(error.message ?? whenFailed);
+  }
+  return data;
+}
+
+/**
+ * Build the adapter from an authenticated PostgREST context.
+ *
+ * The calls run as the signed-in user's own client, so `is_staff` and RLS
+ * apply exactly as they do everywhere else — this never holds privileged
+ * credentials.
+ */
+export function createSupabaseEditLockAdapter(
+  context: PlatformAuthContext,
+): EditLockAdapter {
+  return {
+    assertStaff: () => assertStaff(context),
+
+    async acquire(input: EditLockAcquireInput) {
+      return asEditLockState(
+        await rpc(
+          context,
+          "cms_acquire_edit_lock",
+          {
+            _resource_type: input.resourceType,
+            _resource_id: input.resourceId,
+            _session_id: input.sessionId,
+            _ttl_seconds: input.ttlSeconds,
+            _steal: input.steal,
+          },
+          input.steal
+            ? "Could not take over the editing lock"
+            : "Could not acquire the editing lock",
+        ),
+      );
+    },
+
+    async status(input: EditLockStatusInput) {
+      return asEditLockState(
+        await rpc(
+          context,
+          "cms_edit_lock_status",
+          {
+            _resource_type: input.resourceType,
+            _resource_id: input.resourceId,
+            _session_id: input.sessionId,
+          },
+          "Could not read the editing lock",
+        ),
+      );
+    },
+
+    async release(input: EditLockReleaseInput) {
+      return Boolean(
+        await rpc(
+          context,
+          "cms_release_edit_lock",
+          {
+            _resource_type: input.resourceType,
+            _resource_id: input.resourceId,
+            _session_id: input.sessionId,
+          },
+          "Could not release the editing lock",
+        ),
+      );
+    },
+
+    async list() {
+      const data = await rpc(
+        context,
+        "cms_list_edit_locks",
+        {},
+        "Could not list editing locks",
+      );
+      return Array.isArray(data) ? (data as EditLockRow[]) : [];
+    },
+  };
+}

package/src/server/edit-locks-core.ts

@@ -0,0 +1,286 @@
+/**
+ * Host-agnostic editing locks.
+ *
+ * This module owns the *domain*: what an editor is allowed to ask for, how
+ * long a lock may live, and — the point of the whole feature — that a write to
+ * a resource somebody else is holding must be refused by the server rather
+ * than by a disabled button.
+ *
+ * It owns none of the storage. Every database touch goes through
+ * `EditLockAdapter`, which a host implements with whatever it already uses:
+ * ordinary PostgreSQL through `pg`, a query builder, a stored function, or the
+ * prebuilt PostgREST adapter in `edit-lock-supabase-adapter`. Nothing here
+ * knows which.
+ *
+ * One rule an adapter must honour: taking a lock has to be a single atomic
+ * statement. Two editors opening the same page at the same instant contend on
+ * one unique index and exactly one wins. Doing that as "read, decide, write"
+ * would leave a window where both win.
+ */
+import {
+  clampTtl,
+  FREE_EDIT_LOCK,
+  isBlocked,
+  lockedSaveMessage,
+  type EditLockRef,
+  type EditLockState,
+} from "../cms/edit-lock";
+import {
+  EditLockNotInstalledError,
+  hasEditLockAdapter,
+  type EditLockAdapter,
+  type EditLockHostContext,
+  type EditLockRow,
+} from "./edit-lock-adapter";
+import { createSupabaseEditLockAdapter } from "./edit-lock-supabase-adapter";
+import { type PlatformAuthContext } from "./guards";
+
+/**
+ * Either a host that carries its own lock storage, or — still supported — a
+ * PostgREST-shaped auth context, which is wrapped in the prebuilt adapter.
+ */
+export type EditLockContext = EditLockHostContext | PlatformAuthContext;
+
+export type EditLockRequest = EditLockRef & {
+  /** Identifies one tab across reloads. */
+  sessionId: string;
+  ttlSeconds?: number;
+};
+
+const EDIT_LOCKED_MESSAGE_PREFIX = "edit_locked: ";
+
+/** Server refusal raised when somebody else is holding the resource. */
+export class EditLockedError extends Error {
+  readonly code = "edit_locked" as const;
+  readonly state: EditLockState;
+  constructor(state: EditLockState) {
+    // TanStack Start deliberately serializes only Error.message. Keep the
+    // stable code in that field too, so a direct server-function response is
+    // recognisable after the custom `code` property crosses the wire.
+    super(`${EDIT_LOCKED_MESSAGE_PREFIX}${lockedSaveMessage(state)}`);
+    this.name = "EditLockedError";
+    this.state = state;
+  }
+}
+
+export type EditLockFailure = {
+  code?: "edit_locked";
+  message?: string;
+  state?: EditLockState;
+};
+
+/** True before or after an editing-lock failure crosses the server boundary. */
+export function isEditLockedError(error: unknown): error is EditLockFailure {
+  if (error instanceof EditLockedError) return true;
+  if (!error || typeof error !== "object") return false;
+  const candidate = error as { code?: unknown; message?: unknown };
+  return (
+    candidate.code === "edit_locked" ||
+    (typeof candidate.message === "string" &&
+      candidate.message.startsWith(EDIT_LOCKED_MESSAGE_PREFIX))
+  );
+}
+
+const FREE = FREE_EDIT_LOCK;
+
+/**
+ * An installation whose database has no lock storage keeps saving exactly as
+ * it did before locks existed, so every read path answers "nothing is locked"
+ * rather than failing the write. Any other error is a real error.
+ */
+function whenMissing<T>(fallback: T) {
+  return (error: unknown): T => {
+    if (error instanceof EditLockNotInstalledError) return fallback;
+    throw error;
+  };
+}
+
+/** The host's storage, or the prebuilt PostgREST bridge for older hosts. */
+function adapterFor(context: EditLockContext): EditLockAdapter {
+  if (hasEditLockAdapter(context)) return context.editLocks;
+  return createSupabaseEditLockAdapter(context);
+}
+
+async function acquire(
+  context: EditLockContext,
+  input: EditLockRequest,
+  steal: boolean,
+): Promise<EditLockState> {
+  const locks = adapterFor(context);
+  await locks.assertStaff();
+  return locks
+    .acquire({
+      resourceType: input.resourceType,
+      resourceId: input.resourceId,
+      sessionId: input.sessionId,
+      ttlSeconds: clampTtl(input.ttlSeconds),
+      steal,
+    })
+    .catch(whenMissing(FREE));
+}
+
+/**
+ * Take the lock, or extend one we already hold.
+ *
+ * The same call serves both because a heartbeat wants exactly this behaviour:
+ * if our lock lapsed while the laptop slept, re-taking it is right precisely
+ * when nobody else claimed it in the meantime — and the reply says plainly
+ * whether we ended up holding it.
+ */
+export function acquireEditLockCore(
+  context: EditLockContext,
+  input: EditLockRequest,
+): Promise<EditLockState> {
+  return acquire(context, input, false);
+}
+
+/** Extend a lock we hold. Identical to acquiring it again; see above. */
+export const renewEditLockCore = acquireEditLockCore;
+
+/**
+ * Take a lock away from whoever holds it.
+ *
+ * The superadmin check belongs to the adapter's storage, not to this module,
+ * so no host can reach the same statement with a laxer rule of its own.
+ */
+export function stealEditLockCore(
+  context: EditLockContext,
+  input: EditLockRequest,
+): Promise<EditLockState> {
+  return acquire(context, input, true);
+}
+
+/** Give a lock back. Only our own, and only from the session that took it. */
+export async function releaseEditLockCore(
+  context: EditLockContext,
+  input: EditLockRef & { sessionId: string },
+): Promise<{ released: boolean }> {
+  const locks = adapterFor(context);
+  await locks.assertStaff();
+  const released = await locks
+    .release({
+      resourceType: input.resourceType,
+      resourceId: input.resourceId,
+      sessionId: input.sessionId,
+    })
+    .catch(whenMissing(false));
+  return { released };
+}
+
+/** Who holds a resource right now. An expired lock reads as free. */
+export async function editLockStatusCore(
+  context: EditLockContext,
+  input: EditLockRef & { sessionId?: string },
+): Promise<EditLockState> {
+  const locks = adapterFor(context);
+  await locks.assertStaff();
+  return locks
+    .status({
+      resourceType: input.resourceType,
+      resourceId: input.resourceId,
+      sessionId: input.sessionId ?? null,
+    })
+    .catch(whenMissing(FREE));
+}
+
+/** Every live lock — what an administrator looks at when an editor is stuck. */
+export async function listEditLocksCore(
+  context: EditLockContext,
+): Promise<EditLockRow[]> {
+  const locks = adapterFor(context);
+  await locks.assertStaff();
+  const rows = await locks.list().catch(whenMissing<EditLockRow[]>([]));
+  return Array.isArray(rows) ? rows : [];
+}
+
+/* ------------------------------------------------------- one host endpoint */
+
+/** What a browser can ask of the lock service. */
+export const EDIT_LOCK_ACTIONS = [
+  "acquire",
+  "renew",
+  "release",
+  "status",
+  "steal",
+] as const;
+
+export type EditLockAction = (typeof EDIT_LOCK_ACTIONS)[number];
+
+export function isEditLockAction(value: unknown): value is EditLockAction {
+  return (
+    typeof value === "string" &&
+    (EDIT_LOCK_ACTIONS as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Every lock call behind one entry point.
+ *
+ * A host otherwise writes five near-identical server functions and wires five
+ * of them into the browser. This is the whole backend: validate with
+ * `editLockSchemas`, dispatch here, return what comes back.
+ *
+ * `steal` is deliberately not gated here — the adapter's storage refuses
+ * anyone but a superadmin — so a host that wants a narrower rule adds its own
+ * check before calling.
+ */
+export async function editLockActionCore(
+  context: EditLockContext,
+  action: EditLockAction,
+  input: EditLockRef & { sessionId: string; ttlSeconds?: number },
+): Promise<EditLockState> {
+  switch (action) {
+    case "acquire":
+      return acquireEditLockCore(context, input);
+    case "renew":
+      return renewEditLockCore(context, input);
+    case "steal":
+      return stealEditLockCore(context, input);
+    case "status":
+      return editLockStatusCore(context, input);
+    case "release": {
+      await releaseEditLockCore(context, input);
+      // The screen only ever asks "may I edit"; after a release the answer is
+      // the same whether the row was ours or had already lapsed.
+      return FREE;
+    }
+  }
+}
+
+/**
+ * Refuse a write to a resource somebody else is holding.
+ *
+ * Called by every save core, which is what makes the lock real: the editor's
+ * read-only banner is a courtesy, this is the rule. Two properties matter.
+ *
+ * It degrades only while there is no live lock. A caller that passes no
+ * `sessionId` keeps working on an unwired or unmigrated installation, but once
+ * any editor holds this resource the bearer id is required — including for
+ * the same user. Otherwise a stale tab could bypass the lock by omitting it.
+ *
+ * It is one read-only round trip, so it can sit at the top of every write path
+ * without changing the resource or extending its lock.
+ */
+export async function assertEditable(
+  context: EditLockContext,
+  input: EditLockRef & { sessionId?: string | null },
+): Promise<EditLockState> {
+  const state = await adapterFor(context)
+    .status({
+      resourceType: input.resourceType,
+      resourceId: input.resourceId,
+      sessionId: input.sessionId ?? null,
+    })
+    .catch(whenMissing(FREE));
+  if (isBlocked(state)) throw new EditLockedError(state);
+  return state;
+}
+
+export type {
+  EditLockAdapter,
+  EditLockHostContext,
+  EditLockRow,
+} from "./edit-lock-adapter";
+export { EditLockNotInstalledError } from "./edit-lock-adapter";
+export { createSupabaseEditLockAdapter } from "./edit-lock-supabase-adapter";
+export type { EditLockRef, EditLockState } from "../cms/edit-lock";

package/src/server/forms-core.ts

@@ -21,6 +21,8 @@ import {
 } from "../forms/field-sets";
 import { EMAIL_RE, evaluateRule, normalizePolicyUrl } from "../forms/conditions";
 import { diffForms, summarizeChanges, type FormAuditChange } from "../forms/form-audit";
+import { EDIT_LOCK_TYPES } from "../cms/edit-lock";
+import { assertEditable } from "./edit-locks-core";
 import { actorEmail, assertStaff, type PlatformAuthContext } from "./guards";
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -357,6 +359,8 @@ export async function snapshotFormCore(
 
 export type SaveFormInput = {
   id?: string;
+  /** Editing session that holds the lock, when the host tracks one. */
+  editSessionId?: string;
   key: string;
   name: string;
   form_type: string;
@@ -371,6 +375,14 @@ export async function saveFormCore(
   data: SaveFormInput,
 ): Promise<{ id: string }> {
   await assertStaff(context);
+  // A form that does not exist yet cannot be held by anyone.
+  if (data.id) {
+    await assertEditable(context, {
+      resourceType: EDIT_LOCK_TYPES.form,
+      resourceId: data.id,
+      sessionId: data.editSessionId,
+    });
+  }
 
   // Never allow a field key that already has answers to disappear.
   let before: Record<string, unknown> | null = null;
@@ -485,8 +497,13 @@ export async function getFormUsageCore(
 }
 
 /** Soft delete: moves the form to the bin. Submissions are never touched. */
-export async function deleteFormCore(context: FormsContext, id: string) {
+export async function deleteFormCore(context: FormsContext, id: string, editSessionId?: string) {
   await assertStaff(context);
+  await assertEditable(context, {
+    resourceType: EDIT_LOCK_TYPES.form,
+    resourceId: id,
+    sessionId: editSessionId,
+  });
   const email = actorEmail(context);
   const { data: form } = await context.supabase
     .from("forms")
@@ -662,9 +679,21 @@ export async function loadFormDefaultsCore(db: FormsDb): Promise<FormDefaults |
 export async function saveFormDefaultsCore(
   context: FormsContext,
   data: Record<string, unknown>,
+  editSessionId?: string,
 ) {
   await assertStaff(context);
-  const patch = { ...data };
+  const { editSessionId: embeddedEditSessionId, ...settings } = data;
+  const lockSessionId =
+    editSessionId ??
+    (typeof embeddedEditSessionId === "string" ? embeddedEditSessionId : undefined);
+  await assertEditable(context, {
+    resourceType: EDIT_LOCK_TYPES.formDefaults,
+    resourceId: "form_settings",
+    sessionId: lockSessionId,
+  });
+  // The shared view puts the session beside the editable fields. Never pass
+  // that transport-only value through to the form_settings update.
+  const patch = { ...settings };
   if (typeof patch["privacy_policy_url"] === "string") {
     patch["privacy_policy_url"] = normalizePolicyUrl(patch["privacy_policy_url"] as string);
   }
@@ -759,6 +788,7 @@ export async function listFormVersionsCore(
 export async function restoreFormVersionCore(
   context: FormsContext,
   versionId: string,
+  editSessionId?: string,
 ): Promise<{ ok: true; carriedFields: string[] }> {
   await assertStaff(context);
   const { data: v, error } = await context.supabase
@@ -775,6 +805,11 @@ export async function restoreFormVersionCore(
     .maybeSingle();
   if (e2) throw new Error(e2.message);
   if (!form) throw new Error("This form no longer exists.");
+  await assertEditable(context, {
+    resourceType: EDIT_LOCK_TYPES.form,
+    resourceId: form.id as string,
+    sessionId: editSessionId,
+  });
 
   // Data safety: keep any field key that already has stored answers.
   const { data: subs } = await context.supabase