@abloatai/humans 0.37.0

package/src/local/stores/openIDBWithTimeout.ts

@@ -0,0 +1,195 @@
+/**
+ * The error raised when opening an IndexedDB database does not complete in a
+ * bounded time. {@link openIDBWithTimeout} throws it in two situations: another
+ * browser tab is holding an older version of the database open and blocking the
+ * upgrade (`reason: 'blocked'`), or the open request produced no result at all
+ * within the timeout (`reason: 'timeout'`).
+ *
+ * The native open request can otherwise hang indefinitely — when a blocking tab
+ * never closes its connection, neither the success nor the error callback fires,
+ * and any code awaiting the open waits forever. Turning that into a thrown error
+ * lets the surrounding application show a recoverable failure instead of an
+ * unbreakable spinner.
+ */
+export class IDBOpenTimeoutError extends Error {
+  /**
+   * A stable identifier for this failure, independent of the message text. When
+   * this error is wrapped into an {@link AbloError} by `toAbloError`, the string
+   * code is preserved, so error handlers can recognize a wedged-storage failure
+   * and offer a recovery path rather than matching on the message.
+   */
+  readonly code = 'storage_open_timeout';
+
+  constructor(
+    public readonly dbName: string,
+    public readonly reason: 'blocked' | 'timeout',
+    message: string,
+  ) {
+    super(message);
+    this.name = 'IDBOpenTimeoutError';
+  }
+}
+
+/**
+ * Returns true when a caught value is the storage-open-timeout failure. It
+ * detects the failure by its stable `code`, so it still matches after the error
+ * has been wrapped into an {@link AbloError} or another error type.
+ */
+export function isStorageOpenTimeout(err: unknown): boolean {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    (err as { code?: unknown }).code === 'storage_open_timeout'
+  );
+}
+
+export interface OpenIDBOptions {
+  /** Called inside `onupgradeneeded` — mirrors `IDBOpenDBRequest.onupgradeneeded`. */
+  onUpgrade?: (request: IDBOpenDBRequest, event: IDBVersionChangeEvent) => void;
+  /** Max milliseconds to wait for the open request to resolve. Default 10_000. */
+  timeoutMs?: number;
+  /**
+   * Called when another context — a new tab, a page reload after a deploy, or
+   * this package's own {@link deleteIDBWithTimeout} recovery — needs to upgrade
+   * or delete the database and fires a `versionchange` event on this connection.
+   * The connection is always closed first, which is what lets the other
+   * context's upgrade or delete proceed instead of blocking on this one. Provide
+   * this callback to react after that close, for example to prompt the user to
+   * reload. Any error it throws is ignored.
+   */
+  onVersionChange?: () => void;
+}
+
+export function openIDBWithTimeout(
+  name: string,
+  version: number | undefined,
+  options: OpenIDBOptions = {},
+): Promise<IDBDatabase> {
+  const timeoutMs = options.timeoutMs ?? 10_000;
+
+  return new Promise((resolve, reject) => {
+    const request = version === undefined
+      ? indexedDB.open(name)
+      : indexedDB.open(name, version);
+    let settled = false;
+    const settle = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
+
+    if (options.onUpgrade) {
+      request.onupgradeneeded = (event) => {
+        options.onUpgrade!(request, event);
+      };
+    }
+
+    request.onsuccess = () => {
+      // If we already timed out or were blocked and rejected, this is a late
+      // success: the native open eventually completed after we gave up. The
+      // resulting connection is orphaned — nothing up the stack holds it, so
+      // nothing will close it. A leaked open connection holds an IndexedDB lock
+      // that wedges every later open or delete of this database name, so close
+      // it here to keep a timed-out attempt from poisoning the store.
+      if (settled) {
+        try {
+          request.result.close();
+        } catch {
+          // Best-effort — a half-open connection may already be unusable.
+        }
+        return;
+      }
+      const db = request.result;
+      // Required resilience handler per the IndexedDB specification: close this
+      // connection as soon as any other context wants to upgrade or delete the
+      // database. Without it, a connection that ignores `versionchange` blocks
+      // the other context's request indefinitely — a common cause of a database
+      // that stays wedged across reloads. Closing here makes the store release
+      // itself.
+      db.onversionchange = () => {
+        try {
+          db.close();
+        } catch {
+          // Already closing/closed — nothing to do.
+        }
+        try {
+          options.onVersionChange?.();
+        } catch {
+          // A consumer reaction must never break the close.
+        }
+      };
+      settle(() => { resolve(db); });
+    };
+    request.onerror = () => { settle(() => { reject(request.error); }); };
+
+    // The critical handler: another tab is blocking us. Native API leaves
+    // the request pending indefinitely; we fail fast with a clear error so
+    // the UI can tell the user to close other tabs.
+    request.onblocked = () => {
+      settle(() =>
+        { reject(
+          new IDBOpenTimeoutError(
+            name,
+            'blocked',
+            `IndexedDB \"${name}\" open blocked — another tab is holding an ` +
+              `older version. Close other Ablo tabs and reload.`,
+          ),
+        ); },
+      );
+    };
+
+    // Catch-all timeout: even without `onblocked`, some browsers in some
+    // storage states hang without firing any event. Bounded wait →
+    // deterministic error.
+    const timer = setTimeout(() => {
+      settle(() =>
+        { reject(
+          new IDBOpenTimeoutError(
+            name,
+            'timeout',
+            `IndexedDB \"${name}\" open did not resolve within ${timeoutMs}ms. ` +
+              `Storage may be in a bad state — clearing site data and reloading ` +
+              `usually fixes this.`,
+          ),
+        ); },
+      );
+    }, timeoutMs);
+  });
+}
+
+/**
+ * Deletes an IndexedDB database within a bounded time — the delete counterpart
+ * to {@link openIDBWithTimeout}. It is used to recover from a wedged backing
+ * store: when opening a database times out, the caller can delete it and start
+ * fresh, which is safe for any database whose contents can be rebuilt on the
+ * next load.
+ *
+ * Like an open request, a native delete can hang indefinitely — it fires a
+ * blocked event and waits when another connection still holds the database, and
+ * on a truly stuck store it fires no event at all. Both cases become a bounded,
+ * resolved result here, so the caller never spins.
+ *
+ * Resolves to `true` on a clean delete and `false` when the delete was blocked
+ * or timed out. Either way the caller can decide whether to retry the open; a
+ * delete that did nothing leaves the store no worse off.
+ */
+export function deleteIDBWithTimeout(
+  name: string,
+  timeoutMs = 5_000,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (value: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const request = indexedDB.deleteDatabase(name);
+    request.onsuccess = () => { settle(true); };
+    request.onerror = () => { settle(false); };
+    request.onblocked = () => { settle(false); };
+    const timer = setTimeout(() => { settle(false); }, timeoutMs);
+  });
+}

package/src/local/stores/persistenceCleanup.ts

@@ -0,0 +1,43 @@
+import { AbloConnectionError } from '@abloatai/transaction/errors';
+import type { DatabaseInfo } from './DatabaseManager.js';
+import { deleteIDBWithTimeout } from './openIDBWithTimeout.js';
+import { v1PersistenceDatabaseNameForDeletion } from './v1PersistenceDeletion.js';
+
+type DeleteDatabase = (name: string) => Promise<boolean>;
+
+/** Exact data-store names that can contain the current identity's state. */
+export function persistenceDatabaseNamesForDeletion(
+  current: DatabaseInfo | null,
+): string[] {
+  if (!current) return ['ablo-sync'];
+  return [
+    current.name,
+    v1PersistenceDatabaseNameForDeletion(
+      current.userId,
+      current.workspaceId,
+      current.userVersion ?? 1,
+    ),
+    // Retired pre-identity store. It cannot be attributed safely, so any
+    // terminal cleanup removes it rather than attempting to reuse its data.
+    'ablo-sync',
+  ];
+}
+
+/** Delete authenticated IndexedDB state after its owners have closed handles. */
+export async function purgeIndexedDbPersistence(
+  current: DatabaseInfo | null,
+  deleteDatabase: DeleteDatabase = deleteIDBWithTimeout,
+): Promise<void> {
+  const failed = new Set<string>();
+
+  for (const name of persistenceDatabaseNamesForDeletion(current)) {
+    if (!(await deleteDatabase(name))) failed.add(name);
+  }
+
+  if (failed.size > 0) {
+    throw new AbloConnectionError(
+      `Could not remove authenticated local data from: ${[...failed].join(', ')}`,
+      { code: 'db_cleanup_failed' },
+    );
+  }
+}

package/src/local/stores/persistenceIdentity.ts

@@ -0,0 +1,83 @@
+import { AbloConnectionError } from '@abloatai/transaction/errors';
+
+/**
+ * The complete authenticated plane that owns one local replica. The same
+ * participant can have different data in a project, sandbox, or environment;
+ * those replicas must never share a namespace.
+ */
+export interface PersistenceIdentity {
+  readonly participantId: string;
+  readonly participantKind: string;
+  readonly organizationId: string;
+  readonly projectId: string | null;
+  readonly environment: 'sandbox' | 'production' | null;
+  readonly sandboxId: string | null;
+}
+
+export interface PersistedIdentityMetadata {
+  readonly namespaceVersion?: number;
+  readonly userId: string;
+  readonly workspaceId: string;
+  readonly participantKind?: string;
+  readonly projectId?: string | null;
+  readonly environment?: 'sandbox' | 'production' | null;
+  readonly sandboxId?: string | null;
+}
+
+export const PERSISTENCE_NAMESPACE_VERSION = 2;
+
+function canonicalIdentity(
+  identity: PersistenceIdentity,
+  userVersion: number,
+): string {
+  return JSON.stringify([
+    PERSISTENCE_NAMESPACE_VERSION,
+    identity.projectId,
+    identity.environment,
+    identity.sandboxId,
+    identity.organizationId,
+    identity.participantKind,
+    identity.participantId,
+    userVersion,
+  ]);
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  const cryptoProvider = Reflect.get(globalThis, 'crypto') as Crypto | undefined;
+  const subtle = cryptoProvider?.subtle;
+  if (!subtle) {
+    throw new AbloConnectionError(
+      'Secure local persistence requires Web Crypto SHA-256 support.',
+      { code: 'db_secure_hash_unavailable' },
+    );
+  }
+  const digest = await subtle.digest('SHA-256', new TextEncoder().encode(value));
+  return Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('');
+}
+
+/** Collision-resistant IndexedDB name for one authenticated data plane. */
+export async function persistenceDatabaseName(
+  identity: PersistenceIdentity,
+  userVersion = 1,
+): Promise<string> {
+  const digest = await sha256Hex(canonicalIdentity(identity, userVersion));
+  return `ablo_v${PERSISTENCE_NAMESPACE_VERSION}_${digest}`;
+}
+
+/** Defense-in-depth check after namespace lookup and before persisted reads. */
+export function persistenceIdentityMatches(
+  info: PersistedIdentityMetadata,
+  identity: PersistenceIdentity,
+): boolean {
+  return (
+    info.namespaceVersion === PERSISTENCE_NAMESPACE_VERSION &&
+    info.userId === identity.participantId &&
+    info.workspaceId === identity.organizationId &&
+    info.participantKind === identity.participantKind &&
+    (info.projectId ?? null) === identity.projectId &&
+    (info.environment ?? null) === identity.environment &&
+    (info.sandboxId ?? null) === identity.sandboxId
+  );
+}

package/src/local/stores/syncAction.ts

@@ -0,0 +1,21 @@
+/**
+ * The persisted local action record consumed by `SyncActionStore`. It is a
+ * client materialization artifact, not a transaction-layer wire shape: the
+ * authoritative broadcast vocabulary is the settlement core's delta wire
+ * schema, while this one adds the local `__class` discriminator IndexedDB uses.
+ */
+
+import { z } from 'zod';
+import { syncDeltaActionSchema } from '@abloatai/transaction/wire/delta';
+
+export const syncActionSchema = z.object({
+  id: z.number(),
+  modelName: z.string(),
+  modelId: z.string(),
+  action: syncDeltaActionSchema,
+  data: z.unknown(),
+  __class: z.literal('SyncAction').default('SyncAction'),
+});
+
+export type SyncAction = z.infer<typeof syncActionSchema>;
+export type SyncActionType = SyncAction['action'];

package/src/local/stores/v1PersistenceDeletion.ts

@@ -0,0 +1,21 @@
+/**
+ * Migration-only knowledge of the removed v1 IndexedDB namespace. Nothing in
+ * this module may be used to open or hydrate data; it exists only to find and
+ * delete stores created by clients before persistence namespace v2.
+ *
+ * Remove after the v1 cleanup support window.
+ */
+
+export function v1PersistenceDatabaseNameForDeletion(
+  participantId: string,
+  organizationId: string,
+  userVersion: number,
+): string {
+  const combined = `${participantId}:${organizationId}:${userVersion}`;
+  let hash = 0;
+  for (let index = 0; index < combined.length; index++) {
+    hash = (hash << 5) - hash + combined.charCodeAt(index);
+    hash &= hash;
+  }
+  return `ablo_${Math.abs(hash).toString(16).padStart(8, '0')}`;
+}