@pixel-point/toolcraft 0.0.15 → 0.0.17

package/templates/runtime/source-assets/repository/indexeddb-binary-asset-liveness.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createDefaultIndexedDbOwnerLivenessProvider } from "./indexeddb-binary-asset-liveness";
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("IndexedDB owner liveness provider", () => {
+  it("uses fail-fast Web Locks only when request and query are available", async () => {
+    const held = new Set<string>();
+    const requests: { name: string; options?: { ifAvailable: true } }[] = [];
+    const locks = {
+      async query() {
+        return { held: [...held].map((name) => ({ name })) };
+      },
+      async request(
+        name: string,
+        optionsOrCallback:
+          | { ifAvailable: true }
+          | ((lock: { name: string } | null) => Promise<unknown>),
+        optionalCallback?: (
+          lock: { name: string } | null,
+        ) => Promise<unknown>,
+      ) {
+        const options =
+          typeof optionsOrCallback === "function"
+            ? undefined
+            : optionsOrCallback;
+        const callback =
+          typeof optionsOrCallback === "function"
+            ? optionsOrCallback
+            : optionalCallback!;
+        requests.push({ name, options });
+        if (held.has(name)) {
+          if (options?.ifAvailable) return callback(null);
+          throw new Error("Blocking lock request would wait");
+        }
+        held.add(name);
+        try {
+          return await callback({ name });
+        } finally {
+          held.delete(name);
+        }
+      },
+    };
+    vi.stubGlobal("navigator", { locks });
+    const provider = createDefaultIndexedDbOwnerLivenessProvider();
+    const lease = await provider.acquire("database", "owner");
+    const ownerRequest = requests.find(({ name }) => name.endsWith(":owner"));
+
+    await expect(provider.query("database")).resolves.toEqual(
+      new Set(["owner"]),
+    );
+    await expect(provider.acquire("database", "owner")).rejects.toThrow(
+      /owner.*collision|already held/u,
+    );
+    await lease.release();
+    expect(ownerRequest?.options).toEqual({ ifAvailable: true });
+    await expect(provider.query("database")).resolves.toEqual(new Set());
+
+    const request = vi.fn();
+    vi.stubGlobal("navigator", { locks: { request } });
+    const unavailable = createDefaultIndexedDbOwnerLivenessProvider();
+    const unavailableLease = await unavailable.acquire("database", "owner");
+    await expect(unavailable.query("database")).resolves.toBeNull();
+    expect(request).not.toHaveBeenCalled();
+    await unavailableLease.release();
+  });
+});

package/templates/runtime/source-assets/repository/indexeddb-binary-asset-liveness.ts

@@ -0,0 +1,156 @@
+export type IndexedDbOwnerLivenessLease = {
+  release: () => Promise<void>;
+};
+
+export type IndexedDbOwnerLivenessSnapshot = ReadonlySet<string> | null;
+
+export type IndexedDbOwnerLivenessProvider = {
+  acquire: (
+    scope: string,
+    ownerId: string,
+  ) => Promise<IndexedDbOwnerLivenessLease>;
+  query: (scope: string) => Promise<IndexedDbOwnerLivenessSnapshot>;
+  runExclusive: <Result>(
+    scope: string,
+    operation: () => Promise<Result>,
+  ) => Promise<Result>;
+};
+
+type WebLock = { name?: string };
+
+type WebLockRequest = {
+  <Result>(
+    name: string,
+    callback: (lock: WebLock | null) => Promise<Result>,
+  ): Promise<Result>;
+  <Result>(
+    name: string,
+    options: { ifAvailable: true },
+    callback: (lock: WebLock | null) => Promise<Result>,
+  ): Promise<Result>;
+};
+
+type WebLockManager = {
+  query: () => Promise<{
+    held?: readonly { name?: string | null }[];
+  }>;
+  request: WebLockRequest;
+};
+
+const unavailableOwnerLocks = new Set<string>();
+
+function ownerLockPrefix(scope: string): string {
+  return `toolcraft-binary-assets:${scope.length}:${scope}:`;
+}
+
+function coordinationLockName(scope: string): string {
+  return `toolcraft-binary-assets-coordinate:${scope.length}:${scope}`;
+}
+
+export function createIndexedDbOwnerCollisionError(
+  scope: string,
+  ownerId: string,
+): Error {
+  return new Error(
+    `IndexedDB binary asset owner collision: owner "${ownerId}" is already held for database "${scope}"`,
+  );
+}
+
+function createUnavailableProvider(): IndexedDbOwnerLivenessProvider {
+  return {
+    async acquire(scope, ownerId) {
+      const key = `${ownerLockPrefix(scope)}${ownerId}`;
+      if (unavailableOwnerLocks.has(key)) {
+        throw createIndexedDbOwnerCollisionError(scope, ownerId);
+      }
+      unavailableOwnerLocks.add(key);
+      let released = false;
+      return {
+        release: async () => {
+          if (released) return;
+          released = true;
+          unavailableOwnerLocks.delete(key);
+        },
+      };
+    },
+    async query() {
+      return null;
+    },
+    async runExclusive(_scope, operation) {
+      return operation();
+    },
+  };
+}
+
+function getWebLockManager(): WebLockManager | null {
+  const navigatorValue = globalThis.navigator as
+    | { locks?: Partial<WebLockManager> }
+    | undefined;
+  const locks = navigatorValue?.locks;
+  if (
+    typeof locks?.request !== "function" ||
+    typeof locks.query !== "function"
+  ) {
+    return null;
+  }
+  return locks as WebLockManager;
+}
+
+export function createDefaultIndexedDbOwnerLivenessProvider(): IndexedDbOwnerLivenessProvider {
+  const locks = getWebLockManager();
+  if (!locks) return createUnavailableProvider();
+
+  return {
+    async acquire(scope, ownerId) {
+      let markAcquired!: () => void;
+      let rejectAcquisition!: (error: unknown) => void;
+      let releaseLock!: () => void;
+      const acquired = new Promise<void>((resolve, reject) => {
+        markAcquired = resolve;
+        rejectAcquisition = reject;
+      });
+      const hold = new Promise<void>((resolve) => {
+        releaseLock = resolve;
+      });
+      const request = locks.request(
+        `${ownerLockPrefix(scope)}${ownerId}`,
+        { ifAvailable: true },
+        async (lock) => {
+          if (!lock) {
+            throw createIndexedDbOwnerCollisionError(scope, ownerId);
+          }
+          markAcquired();
+          await hold;
+        },
+      );
+      void request.catch(rejectAcquisition);
+      await acquired;
+
+      let released = false;
+      return {
+        release: async () => {
+          if (released) return;
+          released = true;
+          releaseLock();
+          await request;
+        },
+      };
+    },
+    async query(scope) {
+      const prefix = ownerLockPrefix(scope);
+      const snapshot = await locks.query();
+      return new Set(
+        (snapshot.held ?? [])
+          .map((lock) => lock.name)
+          .filter(
+            (name): name is string =>
+              typeof name === "string" && name.startsWith(prefix),
+          )
+          .map((name) => name.slice(prefix.length)),
+      );
+    },
+    runExclusive(scope, operation) {
+      return locks.request(coordinationLockName(scope), () => operation());
+    },
+  };
+}

package/templates/runtime/source-assets/repository/indexeddb-binary-asset-metadata.ts

@@ -0,0 +1,242 @@
+import {
+  LEASES_STORE,
+  METADATA_STORE,
+  deleteStagedLeaseRows,
+  leaseMetadataKey,
+  ownerMetadataKey,
+  requestResult,
+  type IndexedDbLeaseMetadata,
+  type IndexedDbOwnerMetadata,
+  type IndexedDbRepositoryMetadata,
+} from "./indexeddb-binary-asset-storage";
+import type { IndexedDbOwnerLivenessSnapshot } from "./indexeddb-binary-asset-liveness";
+
+export type IndexedDbRepositoryMetadataContext = {
+  now: () => number;
+  ownerId: string;
+  ownerTtlMs: number;
+  staleLeaseMs: number;
+};
+
+export class StaleIndexedDbLeaseError extends Error {}
+
+function isLeaseMetadata(
+  value: IndexedDbRepositoryMetadata | undefined,
+): value is IndexedDbLeaseMetadata {
+  return value?.kind === "lease";
+}
+
+function isOwnerMetadata(
+  value: IndexedDbRepositoryMetadata | undefined,
+): value is IndexedDbOwnerMetadata {
+  return value?.kind === "owner";
+}
+
+export async function maintainIndexedDbRepositoryMetadata(
+  context: IndexedDbRepositoryMetadataContext,
+  transaction: IDBTransaction,
+  liveOwnerIds: IndexedDbOwnerLivenessSnapshot,
+  protectedLeaseId?: string,
+): Promise<number> {
+  const now = context.now();
+  const metadataStore = transaction.objectStore(METADATA_STORE);
+  const leaseStore = transaction.objectStore(LEASES_STORE);
+  const ownerKey = ownerMetadataKey(context.ownerId);
+  const owner = (await requestResult(
+    metadataStore.get(ownerKey),
+  )) as IndexedDbOwnerMetadata | undefined;
+  metadataStore.put({
+    expiresAt: now + context.ownerTtlMs,
+    key: ownerKey,
+    kind: "owner",
+    ownerId: context.ownerId,
+    reachableRefs: isOwnerMetadata(owner) ? owner.reachableRefs : null,
+    updatedAt: now,
+  } satisfies IndexedDbOwnerMetadata);
+
+  if (protectedLeaseId) {
+    const lease = (await requestResult(
+      metadataStore.get(leaseMetadataKey(protectedLeaseId)),
+    )) as IndexedDbLeaseMetadata | undefined;
+    if (
+      !isLeaseMetadata(lease) ||
+      lease.ownerId !== context.ownerId ||
+      lease.leaseId !== protectedLeaseId
+    ) {
+      throw new StaleIndexedDbLeaseError(
+        `IndexedDB binary asset lease "${protectedLeaseId}" is stale or expired`,
+      );
+    }
+    metadataStore.put({
+      ...lease,
+      expiresAt: now + context.staleLeaseMs,
+      updatedAt: now,
+    } satisfies IndexedDbLeaseMetadata);
+  }
+
+  const metadata = (await requestResult(
+    metadataStore.getAll(),
+  )) as IndexedDbRepositoryMetadata[];
+  const activeLeaseOwnerIds = new Set<string>();
+  for (const record of metadata) {
+    if (!isLeaseMetadata(record)) continue;
+    if (
+      record.leaseId === protectedLeaseId ||
+      record.expiresAt > now ||
+      record.ownerId === context.ownerId ||
+      liveOwnerIds === null ||
+      liveOwnerIds.has(record.ownerId)
+    ) {
+      activeLeaseOwnerIds.add(record.ownerId);
+      continue;
+    }
+    await deleteStagedLeaseRows(leaseStore, record.leaseId);
+    metadataStore.delete(record.key);
+  }
+
+  for (const record of metadata) {
+    if (
+      isOwnerMetadata(record) &&
+      record.ownerId !== context.ownerId &&
+      record.expiresAt <= now &&
+      !activeLeaseOwnerIds.has(record.ownerId) &&
+      liveOwnerIds !== null &&
+      !liveOwnerIds.has(record.ownerId)
+    ) {
+      metadataStore.delete(record.key);
+    }
+  }
+  return now;
+}
+
+export async function heartbeatIndexedDbRepositoryMetadata(
+  context: IndexedDbRepositoryMetadataContext,
+  transaction: IDBTransaction,
+): Promise<void> {
+  const now = context.now();
+  const metadataStore = transaction.objectStore(METADATA_STORE);
+  const ownerKey = ownerMetadataKey(context.ownerId);
+  const owner = (await requestResult(
+    metadataStore.get(ownerKey),
+  )) as IndexedDbOwnerMetadata | undefined;
+  metadataStore.put({
+    expiresAt: now + context.ownerTtlMs,
+    key: ownerKey,
+    kind: "owner",
+    ownerId: context.ownerId,
+    reachableRefs: isOwnerMetadata(owner) ? owner.reachableRefs : null,
+    updatedAt: now,
+  } satisfies IndexedDbOwnerMetadata);
+
+  const metadata = (await requestResult(
+    metadataStore.getAll(),
+  )) as IndexedDbRepositoryMetadata[];
+  for (const record of metadata) {
+    if (isLeaseMetadata(record) && record.ownerId === context.ownerId) {
+      metadataStore.put({
+        ...record,
+        expiresAt: now + context.staleLeaseMs,
+        updatedAt: now,
+      } satisfies IndexedDbLeaseMetadata);
+    }
+  }
+}
+
+export async function invalidateIndexedDbOwnerReachability(
+  context: IndexedDbRepositoryMetadataContext,
+  transaction: IDBTransaction,
+): Promise<void> {
+  const metadataStore = transaction.objectStore(METADATA_STORE);
+  const key = ownerMetadataKey(context.ownerId);
+  const owner = (await requestResult(
+    metadataStore.get(key),
+  )) as IndexedDbOwnerMetadata | undefined;
+  if (!isOwnerMetadata(owner)) return;
+  metadataStore.put({
+    ...owner,
+    reachableRefs: null,
+    updatedAt: context.now(),
+  } satisfies IndexedDbOwnerMetadata);
+}
+
+export async function removeIndexedDbRepositoryOwner(
+  context: IndexedDbRepositoryMetadataContext,
+  transaction: IDBTransaction,
+): Promise<void> {
+  const metadataStore = transaction.objectStore(METADATA_STORE);
+  const leaseStore = transaction.objectStore(LEASES_STORE);
+  const metadata = (await requestResult(
+    metadataStore.getAll(),
+  )) as IndexedDbRepositoryMetadata[];
+
+  for (const record of metadata) {
+    if (isLeaseMetadata(record) && record.ownerId === context.ownerId) {
+      await deleteStagedLeaseRows(leaseStore, record.leaseId);
+      metadataStore.delete(record.key);
+    }
+  }
+  metadataStore.delete(ownerMetadataKey(context.ownerId));
+}
+
+export async function publishAndUnionIndexedDbReachability(
+  context: IndexedDbRepositoryMetadataContext,
+  transaction: IDBTransaction,
+  reachableRefs: ReadonlySet<string>,
+  liveOwnerIds: IndexedDbOwnerLivenessSnapshot,
+): Promise<ReadonlySet<string> | null> {
+  const now = await maintainIndexedDbRepositoryMetadata(
+    context,
+    transaction,
+    liveOwnerIds,
+  );
+  const metadataStore = transaction.objectStore(METADATA_STORE);
+  const owner = (await requestResult(
+    metadataStore.get(ownerMetadataKey(context.ownerId)),
+  )) as IndexedDbOwnerMetadata;
+  metadataStore.put({
+    ...owner,
+    reachableRefs: [...reachableRefs].sort(),
+    updatedAt: now,
+  } satisfies IndexedDbOwnerMetadata);
+
+  const metadata = (await requestResult(
+    metadataStore.getAll(),
+  )) as IndexedDbRepositoryMetadata[];
+  const ownerById = new Map(
+    metadata
+      .filter((record): record is IndexedDbOwnerMetadata =>
+        isOwnerMetadata(record),
+      )
+      .map((record) => [record.ownerId, record]),
+  );
+  const activeOwnerIds = new Set(
+    [...ownerById.values()]
+      .filter(
+        (record) =>
+          record.ownerId === context.ownerId ||
+          record.expiresAt > now ||
+          liveOwnerIds === null ||
+          liveOwnerIds.has(record.ownerId),
+      )
+      .map((record) => record.ownerId),
+  );
+  for (const record of metadata) {
+    if (
+      isLeaseMetadata(record) &&
+      (record.ownerId === context.ownerId ||
+        record.expiresAt > now ||
+        liveOwnerIds === null ||
+        liveOwnerIds.has(record.ownerId))
+    ) {
+      activeOwnerIds.add(record.ownerId);
+    }
+  }
+
+  const union = new Set<string>();
+  for (const activeOwnerId of activeOwnerIds) {
+    const activeOwner = ownerById.get(activeOwnerId);
+    if (!activeOwner || activeOwner.reachableRefs === null) return null;
+    for (const ref of activeOwner.reachableRefs) union.add(ref);
+  }
+  return union;
+}

package/templates/runtime/source-assets/repository/indexeddb-binary-asset-options.ts

@@ -0,0 +1,130 @@
+import {
+  IndexedDbBinaryAssetRepositoryLifecycle,
+  defaultIndexedDbHeartbeatScheduler,
+  type IndexedDbHeartbeatScheduler,
+} from "./indexeddb-binary-asset-lifecycle";
+import {
+  createDefaultIndexedDbOwnerLivenessProvider,
+  type IndexedDbOwnerLivenessProvider,
+} from "./indexeddb-binary-asset-liveness";
+import type { IndexedDbRepositoryMetadataContext } from "./indexeddb-binary-asset-metadata";
+
+export const DEFAULT_OWNER_TTL_MS = 30_000;
+export const DEFAULT_STALE_LEASE_MS = 5 * 60_000;
+
+export type IndexedDbToolcraftBinaryAssetRepositoryOptions = {
+  databaseName?: string;
+  heartbeatIntervalMs?: number;
+  heartbeatScheduler?: IndexedDbHeartbeatScheduler;
+  idFactory?: () => string;
+  indexedDB?: IDBFactory;
+  now?: () => number;
+  ownerLivenessProvider?: IndexedDbOwnerLivenessProvider;
+  ownerTtlMs?: number;
+  staleLeaseMs?: number;
+};
+
+export type IndexedDbRepositoryTiming = {
+  heartbeatIntervalMs: number;
+  ownerTtlMs: number;
+  staleLeaseMs: number;
+};
+
+function defaultIdFactory(): string {
+  const randomUUID = globalThis.crypto?.randomUUID;
+  if (typeof randomUUID !== "function") {
+    throw new Error(
+      "IndexedDB binary asset repository requires crypto.randomUUID or an idFactory option",
+    );
+  }
+  return randomUUID.call(globalThis.crypto);
+}
+
+export function resolveIndexedDbRepositoryIdFactory(
+  idFactory: (() => string) | undefined,
+): () => string {
+  return idFactory ?? defaultIdFactory;
+}
+
+export function createIndexedDbRepositoryIdentity(
+  idFactory: () => string,
+  kind: string,
+): string {
+  const identity = idFactory();
+  if (identity.length === 0 || identity.trim() !== identity) {
+    throw new Error(`${kind} id factory must return a non-empty trimmed string`);
+  }
+  return identity;
+}
+
+export function validateIndexedDbRepositoryDuration(
+  value: number,
+  name: string,
+): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a positive finite number`);
+  }
+  return value;
+}
+
+export function resolveIndexedDbRepositoryTiming(options: {
+  heartbeatIntervalMs?: number;
+  ownerTtlMs?: number;
+  staleLeaseMs?: number;
+}): IndexedDbRepositoryTiming {
+  const ownerTtlMs = validateIndexedDbRepositoryDuration(
+    options.ownerTtlMs ?? DEFAULT_OWNER_TTL_MS,
+    "ownerTtlMs",
+  );
+  const staleLeaseMs = validateIndexedDbRepositoryDuration(
+    options.staleLeaseMs ?? DEFAULT_STALE_LEASE_MS,
+    "staleLeaseMs",
+  );
+  const heartbeatIntervalMs = validateIndexedDbRepositoryDuration(
+    options.heartbeatIntervalMs ?? Math.min(ownerTtlMs, staleLeaseMs) / 3,
+    "heartbeatIntervalMs",
+  );
+  if (
+    heartbeatIntervalMs >= ownerTtlMs ||
+    heartbeatIntervalMs >= staleLeaseMs
+  ) {
+    throw new Error(
+      "heartbeatIntervalMs must be shorter than ownerTtlMs and staleLeaseMs",
+    );
+  }
+
+  return { heartbeatIntervalMs, ownerTtlMs, staleLeaseMs };
+}
+
+export function createIndexedDbRepositorySetup(
+  options: IndexedDbToolcraftBinaryAssetRepositoryOptions,
+): {
+  idFactory: () => string;
+  lifecycle: IndexedDbBinaryAssetRepositoryLifecycle;
+  ownerId: string;
+} {
+  const indexedDB = options.indexedDB ?? globalThis.indexedDB;
+  if (!indexedDB) {
+    throw new Error("IndexedDB is unavailable for the binary asset repository");
+  }
+
+  const idFactory = resolveIndexedDbRepositoryIdFactory(options.idFactory);
+  const ownerId = createIndexedDbRepositoryIdentity(idFactory, "owner");
+  const timing = resolveIndexedDbRepositoryTiming(options);
+  const metadataContext: IndexedDbRepositoryMetadataContext = {
+    now: options.now ?? Date.now,
+    ownerId,
+    ownerTtlMs: timing.ownerTtlMs,
+    staleLeaseMs: timing.staleLeaseMs,
+  };
+  const lifecycle = new IndexedDbBinaryAssetRepositoryLifecycle(
+    indexedDB,
+    options.databaseName ?? "toolcraft-binary-assets",
+    metadataContext,
+    options.heartbeatScheduler ?? defaultIndexedDbHeartbeatScheduler,
+    timing.heartbeatIntervalMs,
+    options.ownerLivenessProvider ??
+      createDefaultIndexedDbOwnerLivenessProvider(),
+  );
+  return { idFactory, lifecycle, ownerId };
+}