@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/matrix/user-homeserver.ts

@@ -64,16 +64,22 @@ const IID_SERVICES_QUERY = `
   }
 `;
 
+/** Upper bound on one Blocksync lookup unless the caller passes its own signal. */
+export const BLOCKSYNC_LOOKUP_TIMEOUT_MS = 5_000;
+
 /**
- * Resolve a user's Matrix server name from Blocksync. Returns null when the
- * DID is unknown or carries no MatrixHomeServer service; throws on transport
- * failure so callers can decide whether to fall back.
+ * What Blocksync knows about a DID's homeserver: `indexed: false` when it
+ * has no record of the DID (not indexed yet, or unknown), otherwise the
+ * server its document names (null for none). Throws on transport failure —
+ * including no answer within `BLOCKSYNC_LOOKUP_TIMEOUT_MS`, or `signal`
+ * aborting first — so callers can decide whether to fall back.
  */
-export async function fetchUserMatrixServerName(
+export async function fetchUserMatrixHomeServer(
   blocksyncGraphqlUrl: string,
   userDid: string,
   fetchImpl: typeof fetch = fetch,
-): Promise<string | null> {
+  signal: AbortSignal = AbortSignal.timeout(BLOCKSYNC_LOOKUP_TIMEOUT_MS),
+): Promise<{ indexed: false } | { indexed: true; serverName: string | null }> {
   const res = await fetchImpl(blocksyncGraphqlUrl, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
@@ -81,6 +87,7 @@ export async function fetchUserMatrixServerName(
       query: IID_SERVICES_QUERY,
       variables: { id: userDid },
     }),
+    signal,
   });
   if (!res.ok) {
     throw new Error(
@@ -98,9 +105,161 @@ export async function fetchUserMatrixServerName(
     );
   }
   const node = body.data?.iids?.nodes?.[0];
-  if (!node) return null;
+  if (!node) return { indexed: false };
   const services: DidService[] = Array.isArray(node.service)
     ? node.service
     : [];
-  return matrixServerNameFromServices(services);
+  return { indexed: true, serverName: matrixServerNameFromServices(services) };
+}
+
+/**
+ * Resolve a user's Matrix server name from Blocksync. Returns null when the
+ * DID is unknown or carries no MatrixHomeServer service; throws like
+ * `fetchUserMatrixHomeServer`.
+ */
+export async function fetchUserMatrixServerName(
+  blocksyncGraphqlUrl: string,
+  userDid: string,
+  fetchImpl: typeof fetch = fetch,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  const answer = await fetchUserMatrixHomeServer(
+    blocksyncGraphqlUrl,
+    userDid,
+    fetchImpl,
+    signal,
+  );
+  return answer.indexed ? answer.serverName : null;
+}
+
+/**
+ * How long "the DID document names no homeserver" is served from the cache.
+ * Short: a user who registers one (or whose registration Blocksync indexes
+ * late) must not be held to the default for the full TTL.
+ */
+export const UNREGISTERED_CACHE_TTL_MS = 5 * 60_000;
+
+/** A resolved server name as the gateway caches it (`hs:<did>` in its storage). */
+export interface CachedUserServerName {
+  serverName: string;
+  /** When Blocksync answered (epoch ms). */
+  at: number;
+  /**
+   * Blocksync answered that the DID document names no homeserver;
+   * `serverName` is then the default it stood for when cached. Served for
+   * `UNREGISTERED_CACHE_TTL_MS` only.
+   */
+  unregistered?: true;
+}
+
+/**
+ * Where a `lookupUserServerName` answer came from:
+ * - `cache` — a cached Blocksync answer younger than the TTL;
+ * - `blocksync` — Blocksync answered just now (and the answer was cached);
+ * - `stale` — Blocksync failed and an EXPIRED cached answer was used;
+ * - `unregistered` — the DID document names no homeserver, or Blocksync has
+ *   no record of the DID yet: the default;
+ * - `unconfigured` — no Blocksync URL is configured: the default.
+ */
+export type UserServerNameSource =
+  | 'cache'
+  | 'blocksync'
+  | 'stale'
+  | 'unregistered'
+  | 'unconfigured';
+
+export interface UserServerNameLookup {
+  serverName: string;
+  source: UserServerNameSource;
+  /** The Blocksync failure a `stale` answer stands in for. */
+  error?: unknown;
+}
+
+export interface UserServerNameLookupDeps {
+  blocksyncGraphqlUrl: string | undefined;
+  /** The answer for a DID that names no homeserver (the oracle's own server). */
+  defaultServerName: string;
+  /** How long a Blocksync answer is served from the cache without asking again. */
+  ttlMs: number;
+  readCache(userDid: string): Promise<CachedUserServerName | undefined>;
+  writeCache(userDid: string, entry: CachedUserServerName): Promise<void>;
+  now?: () => number;
+  fetchImpl?: typeof fetch;
+  /** Ends the Blocksync request early; without one it is bounded by `BLOCKSYNC_LOOKUP_TIMEOUT_MS`. */
+  signal?: AbortSignal;
+}
+
+/** Blocksync could not be asked and nothing was ever cached: there is no answer to give. */
+export class UserServerNameUnavailableError extends Error {
+  constructor(userDid: string, cause: unknown) {
+    super(
+      `could not resolve ${userDid}'s homeserver from Blocksync and nothing is cached`,
+      { cause },
+    );
+    this.name = 'UserServerNameUnavailableError';
+  }
+}
+
+/**
+ * The server a user's DID document registers, through a TTL cache over
+ * Blocksync. A failed Blocksync request is not an answer: it is served from
+ * the cached entry even when that has expired — a homeserver registration
+ * rarely changes, while treating the failure as "the oracle's own server"
+ * would make every user registered elsewhere look foreign for as long as
+ * Blocksync is down. With nothing cached it throws
+ * `UserServerNameUnavailableError`, and each caller decides: the sender check
+ * gives no verdict, the room-alias lookup falls back to the oracle's server.
+ * "Registers no homeserver" is an answer too, cached for the short
+ * `UNREGISTERED_CACHE_TTL_MS` (a DID without the service is a normal case,
+ * not one to ask about on every message). A DID Blocksync has no record of
+ * gets the default without anything being cached: it may be indexed any
+ * moment.
+ */
+export async function lookupUserServerName(
+  userDid: string,
+  deps: UserServerNameLookupDeps,
+): Promise<UserServerNameLookup> {
+  const now = deps.now ?? Date.now;
+  const cached = await deps.readCache(userDid);
+  if (
+    cached &&
+    now() - cached.at <
+      (cached.unregistered ? UNREGISTERED_CACHE_TTL_MS : deps.ttlMs)
+  )
+    return cached.unregistered
+      ? { serverName: deps.defaultServerName, source: 'unregistered' }
+      : { serverName: cached.serverName, source: 'cache' };
+  if (!deps.blocksyncGraphqlUrl)
+    return { serverName: deps.defaultServerName, source: 'unconfigured' };
+  let answer: Awaited<ReturnType<typeof fetchUserMatrixHomeServer>>;
+  try {
+    answer = await fetchUserMatrixHomeServer(
+      deps.blocksyncGraphqlUrl,
+      userDid,
+      deps.fetchImpl,
+      deps.signal,
+    );
+  } catch (err) {
+    if (cached)
+      return {
+        serverName: cached.unregistered
+          ? deps.defaultServerName
+          : cached.serverName,
+        source: 'stale',
+        error: err,
+      };
+    throw new UserServerNameUnavailableError(userDid, err);
+  }
+  if (!answer.indexed)
+    return { serverName: deps.defaultServerName, source: 'unregistered' };
+  if (!answer.serverName) {
+    await deps.writeCache(userDid, {
+      serverName: deps.defaultServerName,
+      at: now(),
+      unregistered: true,
+    });
+    return { serverName: deps.defaultServerName, source: 'unregistered' };
+  }
+  await deps.writeCache(userDid, { serverName: answer.serverName, at: now() });
+  return { serverName: answer.serverName, source: 'blocksync' };
 }

package/src/owner-store/ixo-vfs-store.ts

@@ -24,7 +24,9 @@
  * `POST /upload` + `PATCH /upload/:id` (tus, larger files), `GET
  * /files/:id/content` (bytes, streamed), `POST /batch/delete`, `POST
  * /batch/move`. The file is never `PUT` (a new VERSION, capped at 50 by the
- * VFS): every flush uploads to a temp path and swaps it in — see `save()`.
+ * VFS): every flush uploads to a temp path and swaps it in with moves — see
+ * `save()`. The VFS refuses to move onto an occupied path (per-item 409
+ * "Destination occupied"), so the old file is moved aside first.
  *
  * Two VFS semantics this store must respect:
  *   - `/.oracles` is a dot-folder, so the file is HIDDEN by the VFS dotfile
@@ -38,7 +40,8 @@
  *     `stat()` lists under the short literal `/.oracles` prefix and matches
  *     the exact path client-side.
  */
-import { abilityCovers, type WorkersUcanService } from '../do/ucan-service';
+import { abilityCovers } from '../core/runtime-context';
+import { type WorkersUcanService } from '../do/ucan-service';
 import { isNetworkError, withRetry } from './retry';
 import { tusUpload } from './tus-upload';
 import {
@@ -135,6 +138,12 @@ export class VfsRequestError extends Error {
  * once complete; anything still carrying the infix is a crashed flush.
  */
 export const TEMP_PATH_INFIX = '.uploading-';
+/**
+ * The previous file is moved to `<path>.replaced-<ts>` while the new one
+ * moves into place, and deleted once it has. Anything still carrying the
+ * infix is a complete earlier copy a crashed or failed swap left behind.
+ */
+export const ASIDE_PATH_INFIX = '.replaced-';
 /** tus part size: a multiple of 64 KiB, ≥ 5 MiB (the VFS minimum) — and the peak upload buffer. */
 export const TUS_PART_BYTES = 5 * 1024 * 1024;
 /** Gzipped files up to one part go through the single-request `POST /files`. */
@@ -205,7 +214,7 @@ export class IxoVfsOwnerStore implements OwnerStore {
   }
 
   async head(): Promise<{ etag: string } | null> {
-    const stat = await this.statPath(this.path);
+    const stat = await this.ownerCopy();
     return stat ? { etag: this.etagOf(stat) } : null;
   }
 
@@ -216,7 +225,7 @@ export class IxoVfsOwnerStore implements OwnerStore {
    * on the first one.
    */
   async load(): Promise<OwnerCopy | null> {
-    const stat = await this.statPath(this.path);
+    const stat = await this.ownerCopy();
     if (!stat) return null;
     const res = await this.request(
       'fs/read',
@@ -231,24 +240,29 @@ export class IxoVfsOwnerStore implements OwnerStore {
   }
 
   /**
-   * Atomic replace, always delete + re-create, never a new version:
+   * Replace the file by moves, never a new version, and never leave the
+   * user without a complete upstream copy:
    *
-   *   1. drop stale `.uploading-*` temp files a crashed flush left behind;
-   *   2. take the gzipped length from `hints` (the object measured it in the
+   *   1. take the gzipped length from `hints` (the object measured it in the
    *      same pass as its checksum) or, without a hint, count it in a pass
    *      of its own (the VFS needs `Upload-Length` at session creation —
    *      `Upload-Defer-Length` is not supported — and gzip output is
    *      deterministic for identical input);
-   *   3. upload gzip → a TEMP path next to the real one: one `POST /files`
+   *   2. upload gzip → a TEMP path next to the real one: one `POST /files`
    *      when it fits in a single part, else a tus session in 5 MiB parts
    *      (`tusUpload`, resumable per part);
-   *   4. delete the old file at the real path, then `batch/move` the temp
-   *      file into place.
+   *   3. move the old file aside (`.replaced-<ts>`), then the temp file
+   *      into place; when that move fails for good, the old file is moved
+   *      back before the error is thrown;
+   *   4. only once the new file is at the path: delete the old copy and any
+   *      leftovers of earlier flushes (`.uploading-` / `.replaced-` files).
+   *      A leftover may be the only complete copy (a swap that failed after
+   *      the old file was moved aside), so none is deleted earlier.
    *
-   * Every request is retried with backoff; a step that still fails throws,
-   * the working copy stays dirty and the next tick starts over (the temp
-   * file is cleaned up then). Peak memory is one part (5 MiB) plus fixed
-   * overhead, whatever the file size.
+   * The path is empty only between the two moves. Every request is retried
+   * with backoff; a step that still fails throws, the working copy stays
+   * dirty and the next tick starts over. Peak memory is one part (5 MiB)
+   * plus fixed overhead, whatever the file size.
    */
   async save(
     snapshot: FileSnapshot,
@@ -256,20 +270,12 @@ export class IxoVfsOwnerStore implements OwnerStore {
   ): Promise<SaveResult> {
     const listing = await this.listOracleFiles();
     const existing = listing.filter((f) => f.path === this.path);
-    const stale = listing.filter((f) =>
-      f.path.startsWith(`${this.path}${TEMP_PATH_INFIX}`),
-    );
-    if (stale.length > 0) {
-      await this.batchDelete(stale.map((f) => f.id)).catch((err: unknown) => {
-        console.warn(
-          `[owner-store] could not delete ${stale.length} stale temp upload(s): ${describe(err)}`,
-        );
-      });
-    }
+    const leftovers = listing.filter((f) => this.isLeftover(f.path));
 
     const gzLength =
       hints.gzippedLength ?? (await countStream(gzipStream(snapshot.open())));
-    const tempPath = `${this.path}${TEMP_PATH_INFIX}${Date.now().toString(36)}`;
+    const stamp = Date.now().toString(36);
+    const tempPath = `${this.path}${TEMP_PATH_INFIX}${stamp}`;
     const uploaded =
       gzLength <= SINGLE_SHOT_MAX_BYTES
         ? await this.uploadSingleShot(tempPath, snapshot)
@@ -281,27 +287,100 @@ export class IxoVfsOwnerStore implements OwnerStore {
       );
     }
 
-    if (existing.length > 0) {
-      await withRetry(() => this.batchDelete(existing.map((f) => f.id)), {
+    const aside: VfsFileStat[] = [];
+    for (const [i, file] of existing.entries()) {
+      const asidePath = `${this.path}${ASIDE_PATH_INFIX}${stamp}${i > 0 ? `-${i}` : ''}`;
+      await this.moveWithRetry(
+        file.id,
+        asidePath,
+        'moving the previous state file aside',
+      );
+      aside.push({ ...file, path: asidePath });
+    }
+    try {
+      await this.moveIntoPlace(tempId, stamp, aside);
+    } catch (error) {
+      await this.restoreAside(aside);
+      throw error;
+    }
+
+    const stale = [...leftovers, ...aside].filter((f) => f.id !== tempId);
+    if (stale.length > 0) {
+      await withRetry(() => this.batchDelete(stale.map((f) => f.id)), {
         isRetryable: isRetryableRequest,
         ...this.retryOptions(),
-        onRetry: (err, attempt, delay) =>
-          console.warn(
-            `[owner-store] delete of the previous state file failed (${describe(err)}) — retry ${attempt} in ${delay} ms`,
-          ),
+      }).catch((err: unknown) => {
+        console.warn(
+          `[owner-store] could not delete ${stale.length} earlier cop${stale.length === 1 ? 'y' : 'ies'} of ${this.path} (the next flush retries): ${describe(err)}`,
+        );
       });
     }
+    const etag =
+      uploaded.contentHash ??
+      (await this.statPath(this.path))?.checksum ??
+      tempId;
+    return { etag, bytes: gzLength };
+  }
+
+  /**
+   * The file at the path or, when a swap failed after moving the previous
+   * file aside (and could not put it back), the newest set-aside copy — the
+   * last complete file this store landed. Never an `.uploading-` temp: its
+   * swap did not finish, so it is not the owner copy. `save()` removes the
+   * set-aside copies only after its own file is at the path.
+   */
+  private async ownerCopy(): Promise<VfsFileStat | null> {
+    const listing = await this.listOracleFiles();
+    const exact = listing.find((f) => f.path === this.path);
+    if (exact) return exact;
+    const prefix = `${this.path}${ASIDE_PATH_INFIX}`;
+    let newest: { file: VfsFileStat; at: number } | null = null;
+    for (const file of listing) {
+      if (!file.path.startsWith(prefix)) continue;
+      // `<stamp>` or `<stamp>-<n>`: the stamp is the save's base-36 time.
+      const at = Number.parseInt(
+        file.path.slice(prefix.length).split('-')[0] ?? '',
+        36,
+      );
+      if (!Number.isFinite(at)) continue;
+      if (newest === null || at > newest.at) newest = { file, at };
+    }
+    return newest?.file ?? null;
+  }
+
+  /** A crashed or failed flush's temp upload or set-aside copy of this file. */
+  private isLeftover(path: string): boolean {
+    return (
+      path.startsWith(`${this.path}${TEMP_PATH_INFIX}`) ||
+      path.startsWith(`${this.path}${ASIDE_PATH_INFIX}`)
+    );
+  }
+
+  /**
+   * Move the uploaded temp file to the real path. A "Destination occupied"
+   * answer means something still sits there (a concurrent or crashed
+   * flush): it is moved aside too (`aside` collects it, so a failure
+   * restores it and success deletes it) and the move retried.
+   */
+  private async moveIntoPlace(
+    tempId: string,
+    stamp: string,
+    aside: VfsFileStat[],
+  ): Promise<void> {
     await withRetry(
       async () => {
         try {
           await this.move(tempId, this.path);
         } catch (err) {
-          // Someone (a crashed earlier flush) still occupies the path: clear it
-          // and let the retry move again.
           if (err instanceof VfsRequestError && err.status === 409) {
             const occupant = await this.statPath(this.path);
-            if (occupant && occupant.id !== tempId)
-              await this.batchDelete([occupant.id]);
+            // An earlier attempt committed but its answer was lost.
+            if (occupant?.id === tempId) return;
+            if (occupant) {
+              const asidePath = `${this.path}${ASIDE_PATH_INFIX}${stamp}-o${aside.length}`;
+              await this.move(occupant.id, asidePath);
+              aside.push({ ...occupant, path: asidePath });
+            }
           }
           throw err;
         }
@@ -317,11 +396,61 @@ export class IxoVfsOwnerStore implements OwnerStore {
           ),
       },
     );
-    const etag =
-      uploaded.contentHash ??
-      (await this.statPath(this.path))?.checksum ??
-      tempId;
-    return { etag, bytes: gzLength };
+  }
+
+  /**
+   * The new file could not be moved into place: put the previous one back
+   * so the path keeps a complete copy. Best effort — if this fails too the
+   * set-aside copy stays where it is, and the next flush (which only
+   * deletes leftovers after its own file landed) cleans it up.
+   */
+  private async restoreAside(aside: VfsFileStat[]): Promise<void> {
+    const previous = aside[0];
+    if (previous === undefined) return;
+    try {
+      await this.moveWithRetry(
+        previous.id,
+        this.path,
+        'restoring the previous state file',
+      );
+    } catch (err) {
+      console.error(
+        `[owner-store] ${this.path} is empty: the previous copy stays at ${previous.path} until the next flush (${describe(err)})`,
+      );
+    }
+  }
+
+  private async moveWithRetry(
+    id: string,
+    destinationPath: string,
+    what: string,
+  ): Promise<void> {
+    await withRetry(
+      async () => {
+        try {
+          await this.move(id, destinationPath);
+        } catch (err) {
+          // The VFS checks the file's version on every move: a retry of a
+          // move that committed but lost its answer gets a 409 although the
+          // file is already where it was sent.
+          if (
+            err instanceof VfsRequestError &&
+            err.status === 409 &&
+            (await this.statPath(destinationPath))?.id === id
+          )
+            return;
+          throw err;
+        }
+      },
+      {
+        isRetryable: isRetryableRequest,
+        ...this.retryOptions(),
+        onRetry: (err, attempt, delay) =>
+          console.warn(
+            `[owner-store] ${what} failed (${describe(err)}) — retry ${attempt} in ${delay} ms`,
+          ),
+      },
+    );
   }
 
   /** ≤ one part: buffer the gzip once and `POST /files` it (retried as a whole). */
@@ -386,9 +515,7 @@ export class IxoVfsOwnerStore implements OwnerStore {
   async remove(): Promise<void> {
     const listing = await this.listOracleFiles();
     const mine = listing.filter(
-      (f) =>
-        f.path === this.path ||
-        f.path.startsWith(`${this.path}${TEMP_PATH_INFIX}`),
+      (f) => f.path === this.path || this.isLeftover(f.path),
     );
     if (mine.length === 0) return;
     await this.batchDelete(mine.map((f) => f.id));

package/src/owner-store/migrating-store.ts

@@ -20,12 +20,13 @@
  *            Matrix copy so no second copy of the user's history lingers.
  */
 import { VfsNoDelegationError } from './ixo-vfs-store';
-import type {
-  FileSnapshot,
-  OwnerCopy,
-  OwnerStore,
-  SaveHints,
-  SaveResult,
+import {
+  NotSqliteFileError,
+  type FileSnapshot,
+  type OwnerCopy,
+  type OwnerStore,
+  type SaveHints,
+  type SaveResult,
 } from './types';
 
 export interface MigratingOwnerStoreOptions {
@@ -77,13 +78,22 @@ export class MigratingOwnerStore implements OwnerStore {
     }
     if (fromVfs) return fromVfs;
 
-    const fromLegacy = await this.legacy.load().catch((err) => {
+    // A legacy read that FAILS is not "no legacy copy": a new, empty working
+    // copy would hide the user's history and, once a turn dirtied it, be
+    // flushed to VFS as their system of record. So the failure propagates
+    // and the boot retries. The one exception is a copy proven unusable (its
+    // whole header arrived and is not SQLite): no retry can load it.
+    let fromLegacy: OwnerCopy | null;
+    try {
+      fromLegacy = await this.legacy.load();
+    } catch (err) {
+      if (!(err instanceof NotSqliteFileError && err.proven)) throw err;
       this.log(
-        'warn',
-        `[owner-store] legacy Matrix load failed: ${err instanceof Error ? err.message : String(err)}`,
+        'error',
+        `[owner-store] legacy Matrix copy is unusable, treating it as absent: ${err.message}`,
       );
-      return null;
-    });
+      fromLegacy = null;
+    }
     if (!fromLegacy) {
       // Without a delegation VFS could not be READ, so "no legacy copy" is
       // not "no file": an existing user whose grant lapsed would otherwise
@@ -146,18 +156,24 @@ export class MigratingOwnerStore implements OwnerStore {
     // Only fall through to legacy when VFS positively has no file.
     const vfs = await this.primary.head();
     if (vfs) return vfs;
-    return this.legacy.head().catch(() => null);
+    return this.legacy.head();
   }
 
-  /** The legacy Matrix copy regardless of what VFS holds (see `OwnerStore.loadLegacy`). */
+  /**
+   * The legacy Matrix copy regardless of what VFS holds (see
+   * `OwnerStore.loadLegacy`). Null means there is none, or one proven
+   * unusable; a read that failed throws, so the caller can tell "absent"
+   * from "unknown" and look again later.
+   */
   async loadLegacy(): Promise<OwnerCopy | null> {
     try {
       const copy = await this.legacy.load();
       return copy ? { ...copy, fromLegacy: true } : null;
     } catch (err) {
+      if (!(err instanceof NotSqliteFileError && err.proven)) throw err;
       this.log(
-        'warn',
-        `[owner-store] legacy Matrix load failed: ${err instanceof Error ? err.message : String(err)}`,
+        'error',
+        `[owner-store] legacy Matrix copy is unusable, treating it as absent: ${err.message}`,
       );
       return null;
     }

package/src/owner-store/types.ts

@@ -189,6 +189,23 @@ const SQLITE_HEADER_BYTES = 16;
  * again as it writes; this is what lets a store reject a corrupt or foreign
  * upload before anything downstream starts.
  */
+/**
+ * A stream that does not open with the SQLite header. `proven` when the whole
+ * header arrived and differs: those bytes will never load. A shorter read may
+ * be a transfer cut short, so it proves nothing about the stored file.
+ */
+export class NotSqliteFileError extends Error {
+  readonly proven: boolean;
+
+  constructor(what: string, headerBytesRead: number) {
+    super(
+      `${what} is not a SQLite file (${headerBytesRead} header byte(s) read)`,
+    );
+    this.name = 'NotSqliteFileError';
+    this.proven = headerBytesRead >= SQLITE_HEADER_BYTES;
+  }
+}
+
 export async function assertSqliteStream(
   stream: ReadableStream<Uint8Array>,
   what: string,
@@ -196,9 +213,7 @@ export async function assertSqliteStream(
   const { head, rest } = await peekStream(stream, SQLITE_HEADER_BYTES);
   if (isSqliteFile(head)) return rest;
   await rest.cancel(`${what} is not a SQLite file`).catch(() => undefined);
-  throw new Error(
-    `${what} is not a SQLite file (${head.byteLength} header byte(s) read)`,
-  );
+  throw new NotSqliteFileError(what, head.byteLength);
 }
 
 function concat(parts: Uint8Array[]): Uint8Array {