pmtiles-swarm 0.2.0

package/src/mutable.js

@@ -0,0 +1,197 @@
+/**
+ * Updatable torrents, via BEP 46 (Updating Torrents Via DHT Mutable Items).
+ *
+ * A torrent's infohash is a hash of its content, so a rebuilt archive is always
+ * a new torrent — there is no such thing as editing one in place. BEP 46 works
+ * around that with a level of indirection: you publish an ed25519-signed record
+ * into the DHT whose value names the *current* infohash, and hand out the
+ * public key instead of the infohash. Subscribers resolve the key whenever they
+ * check, and follow the archive across rebuilds.
+ *
+ * This is the decentralised sibling of the RSS feed. The feed is easier to
+ * consume (qBittorrent reads RSS today, with no new software) but needs a
+ * server that stays up; the DHT record needs no server but has to be
+ * republished periodically or it expires. Publishing both costs little.
+ *
+ * Built directly on bittorrent-dht's BEP 44 put/get rather than through
+ * WebTorrent's high-level API, which does not expose them — and independent of
+ * the seeding engine, since qBittorrent's WebUI has no way to publish these.
+ *
+ * BEP 44: https://www.bittorrent.org/beps/bep_0044.html
+ * BEP 46: https://www.bittorrent.org/beps/bep_0046.html
+ */
+
+import crypto from 'node:crypto';
+
+/**
+ * An ed25519 keypair identifying a mutable torrent, in the raw 32-byte form
+ * BEP 44 expects.
+ * @typedef {object} PublisherKey
+ * @property {Uint8Array} publicKey - 32-byte raw public key. This is the stable identity you publish.
+ * @property {crypto.KeyObject} privateKey - Signing key. Keep it secret; whoever holds it controls the feed.
+ */
+
+/**
+ * Generates a publishing identity.
+ *
+ * The public key is the permanent address of the archive: it does not change
+ * when the archive is rebuilt, which is the entire point. Back up the private
+ * key — losing it means subscribers can never be moved forward again.
+ * @returns {PublisherKey} - A fresh keypair.
+ */
+export function generatePublisherKey() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+  return { publicKey: rawPublicKey(publicKey), privateKey };
+}
+
+/**
+ * Restores a keypair from a stored private key.
+ * @param {string} pem - PKCS#8 PEM of the ed25519 private key.
+ * @returns {PublisherKey} - The keypair.
+ */
+export function publisherKeyFromPem(pem) {
+  const privateKey = crypto.createPrivateKey(pem);
+  const publicKey = crypto.createPublicKey(privateKey);
+  return { publicKey: rawPublicKey(publicKey), privateKey };
+}
+
+/**
+ * Serialises a private key for storage.
+ * @param {PublisherKey} key - The keypair.
+ * @returns {string} - PKCS#8 PEM.
+ */
+export function publisherKeyToPem(key) {
+  return key.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+}
+
+/**
+ * Extracts the raw 32 bytes of an ed25519 public key.
+ *
+ * Node only exports ed25519 keys as DER or JWK, and BEP 44 wants the bare
+ * bytes; JWK's base64url 'x' is the cleanest route to them.
+ * @param {crypto.KeyObject} publicKey - The key object.
+ * @returns {Uint8Array} - 32 raw bytes.
+ */
+function rawPublicKey(publicKey) {
+  const jwk = publicKey.export({ format: 'jwk' });
+  return new Uint8Array(Buffer.from(jwk.x, 'base64url'));
+}
+
+/**
+ * The magnet URI subscribers use to follow an archive across rebuilds.
+ *
+ * Note this carries no infohash: `xs=urn:btpk:` names the public key, and the
+ * client resolves it through the DHT to whatever infohash is current.
+ * @param {Uint8Array} publicKey - Raw 32-byte public key.
+ * @param {object} [options] - Extra magnet parameters.
+ * @param {string} [options.name] - Display name for the archive.
+ * @param {string[]} [options.trackers] - Tracker announce URLs.
+ * @param {string} [options.salt] - Salt, when one key publishes several archives.
+ * @returns {string} - A BEP 46 magnet URI.
+ */
+export function mutableMagnet(publicKey, options = {}) {
+  const hex = Buffer.from(publicKey).toString('hex');
+  const parts = [`magnet:?xs=urn:btpk:${hex}`];
+  if (options.name) parts.push(`dn=${encodeURIComponent(options.name)}`);
+  if (options.salt) parts.push(`s=${encodeURIComponent(options.salt)}`);
+  for (const tracker of options.trackers ?? []) {
+    parts.push(`tr=${encodeURIComponent(tracker)}`);
+  }
+  return parts.join('&');
+}
+
+/**
+ * Publishes the infohash an archive currently resolves to.
+ *
+ * `seq` must increase on every update — the DHT rejects a record whose sequence
+ * number is not greater than the one it already holds, which is what stops a
+ * replayed old record from rolling subscribers backwards.
+ * @param {object} dht - A bittorrent-dht Client.
+ * @param {PublisherKey} key - The publishing identity.
+ * @param {string} infoHash - Hex infohash the key should now point at.
+ * @param {object} [options] - Publishing options.
+ * @param {number} [options.seq] - Sequence number. Defaults to seconds since the epoch, which is monotonic and needs no stored state.
+ * @param {string} [options.salt] - Salt, when one key publishes several archives.
+ * @returns {Promise<{hash: string, seq: number, nodes: number}>} - Where it landed.
+ */
+export function publishInfoHash(dht, key, infoHash, options = {}) {
+  const seq = options.seq ?? Math.floor(Date.now() / 1000);
+  const value = { ih: Buffer.from(infoHash, 'hex') };
+
+  const request = {
+    k: Buffer.from(key.publicKey),
+    seq,
+    v: value,
+    /**
+     * Signs the buffer bittorrent-dht assembles from salt, seq and value.
+     * @param {Buffer} buffer - The canonical bytes to sign.
+     * @returns {Buffer} - A 64-byte ed25519 signature.
+     */
+    sign: (buffer) => crypto.sign(null, buffer, key.privateKey),
+  };
+  if (options.salt) request.salt = Buffer.from(options.salt);
+
+  return new Promise((resolve, reject) => {
+    dht.put(request, (error, hash, nodes) => {
+      if (error) {
+        reject(
+          new Error(`failed to publish mutable record: ${error.message}`, {
+            cause: error,
+          }),
+        );
+        return;
+      }
+      resolve({ hash: Buffer.from(hash).toString('hex'), seq, nodes });
+    });
+  });
+}
+
+/**
+ * Resolves a public key to the infohash it currently names.
+ * @param {object} dht - A bittorrent-dht Client.
+ * @param {Uint8Array | string} publicKey - Raw or hex public key.
+ * @param {object} [options] - Lookup options.
+ * @param {string} [options.salt] - Salt used when publishing.
+ * @returns {Promise<{infoHash: string, seq: number} | null>} - The current target, or null if nothing is published.
+ */
+export function resolveInfoHash(dht, publicKey, options = {}) {
+  const raw =
+    typeof publicKey === 'string'
+      ? Buffer.from(publicKey, 'hex')
+      : Buffer.from(publicKey);
+  const target = crypto.createHash('sha1');
+  target.update(raw);
+  if (options.salt) target.update(Buffer.from(options.salt));
+
+  return new Promise((resolve, reject) => {
+    dht.get(target.digest(), (error, result) => {
+      if (error) {
+        reject(
+          new Error(`failed to resolve mutable record: ${error.message}`, {
+            cause: error,
+          }),
+        );
+        return;
+      }
+      if (!result?.v) {
+        resolve(null);
+        return;
+      }
+      const ih = result.v.ih ?? result.v;
+      resolve({
+        infoHash: Buffer.from(ih).toString('hex'),
+        seq: result.seq ?? 0,
+      });
+    });
+  });
+}
+
+/**
+ * Extracts the public key from a BEP 46 magnet URI.
+ * @param {string} magnet - A magnet URI.
+ * @returns {string | null} - Hex public key, or null if it is not a mutable magnet.
+ */
+export function publicKeyFromMagnet(magnet) {
+  const match = /xs=urn:btpk:([a-f0-9]{64})/i.exec(magnet ?? '');
+  return match ? match[1].toLowerCase() : null;
+}

package/src/origin.js

@@ -0,0 +1,205 @@
+/**
+ * Watching the source an archive was built from.
+ *
+ * A torrent describes a fixed set of bytes. If the file it was built from is
+ * later replaced — a nightly build overwriting `planet-latest.pmtiles`, say —
+ * the torrent does not become invalid, but it stops describing what the source
+ * now holds, and any web seed pointing at that source becomes actively harmful:
+ * peers fetch from it, fail hash verification, and eventually ban it.
+ *
+ * Detecting that is cheap. A HEAD request comparing ETag, Last-Modified and
+ * length catches essentially every real update for an HTTP origin, and a stat
+ * does the same for a local file. Neither needs the archive re-read.
+ *
+ * What to do about it is a judgement call, so this only reports. Rebuilding
+ * means re-hashing — and for a remote archive, re-downloading — which is not
+ * something to start behind an operator's back.
+ */
+
+import fs from 'node:fs/promises';
+
+/**
+ * A fingerprint of the source, cheap enough to take repeatedly.
+ * @typedef {object} OriginFingerprint
+ * @property {string} type - 'http' or 'file'.
+ * @property {string} location - URL or path.
+ * @property {number} [size] - Byte length, when known.
+ * @property {string} [etag] - HTTP ETag.
+ * @property {string} [lastModified] - HTTP Last-Modified, or file mtime as ISO.
+ * @property {string} checkedAt - ISO timestamp of this check.
+ */
+
+/**
+ * Fingerprints an archive's source without reading its contents.
+ * @param {object} source - Catalog source: {type, location}.
+ * @returns {Promise<OriginFingerprint | null>} - The fingerprint, or null if it cannot be taken.
+ */
+export async function fingerprintOrigin(source) {
+  if (!source?.location) return null;
+  const checkedAt = new Date().toISOString();
+
+  if (source.type === 'http') {
+    // HEAD first; some origins (notably S3-compatible ones behind a CDN) do
+    // not answer HEAD, in which case a ranged GET of one byte gets the same
+    // headers for the same negligible cost.
+    let response = await fetch(source.location, { method: 'HEAD' }).catch(
+      () => null,
+    );
+    if (!response?.ok) {
+      response = await fetch(source.location, {
+        headers: { range: 'bytes=0-0' },
+      }).catch(() => null);
+    }
+    if (!response?.ok) return null;
+
+    // A ranged response reports the range length, so prefer content-range.
+    const contentRange = response.headers.get('content-range');
+    const total = contentRange
+      ? Number(contentRange.split('/')[1])
+      : Number(response.headers.get('content-length') ?? 0);
+
+    return {
+      type: 'http',
+      location: source.location,
+      size: Number.isFinite(total) && total > 0 ? total : undefined,
+      etag: response.headers.get('etag') ?? undefined,
+      lastModified: response.headers.get('last-modified') ?? undefined,
+      checkedAt,
+    };
+  }
+
+  if (source.type === 'file') {
+    const stat = await fs.stat(source.location).catch(() => null);
+    if (!stat) return null;
+    return {
+      type: 'file',
+      location: source.location,
+      size: stat.size,
+      lastModified: new Date(stat.mtimeMs).toISOString(),
+      checkedAt,
+    };
+  }
+
+  // Adopted torrents and magnets have no origin to watch.
+  return null;
+}
+
+/**
+ * The result of comparing a fresh fingerprint against a stored one.
+ * @typedef {object} OriginCheck
+ * @property {string} infoHash - The archive checked.
+ * @property {'unchanged' | 'changed' | 'missing' | 'unknown'} status - What was found.
+ * @property {string} [reason] - Which validator differed.
+ * @property {OriginFingerprint} [fingerprint] - The fresh fingerprint.
+ */
+
+/**
+ * Compares a stored fingerprint against the source as it is now.
+ *
+ * Any single differing validator is treated as a change. A false positive costs
+ * a warning; a false negative means continuing to advertise a web seed that
+ * serves bytes failing hash verification, so this errs toward reporting.
+ * @param {object} entry - The catalog entry.
+ * @returns {Promise<OriginCheck>} - What was found.
+ */
+export async function checkOrigin(entry) {
+  const stored = entry.origin;
+  if (!stored) {
+    // Nothing recorded to compare against; take a baseline for next time.
+    const fingerprint = await fingerprintOrigin(entry.source);
+    return fingerprint
+      ? { infoHash: entry.infoHash, status: 'unknown', fingerprint }
+      : { infoHash: entry.infoHash, status: 'unknown' };
+  }
+
+  const fresh = await fingerprintOrigin(entry.source);
+  if (!fresh) {
+    return {
+      infoHash: entry.infoHash,
+      status: 'missing',
+      reason: `source is no longer reachable: ${entry.source?.location}`,
+    };
+  }
+
+  const differences = [];
+  if (stored.etag && fresh.etag && stored.etag !== fresh.etag) {
+    differences.push(`etag ${stored.etag} -> ${fresh.etag}`);
+  }
+  if (
+    stored.lastModified &&
+    fresh.lastModified &&
+    stored.lastModified !== fresh.lastModified
+  ) {
+    differences.push(`last-modified ${stored.lastModified} -> ${fresh.lastModified}`);
+  }
+  if (stored.size && fresh.size && stored.size !== fresh.size) {
+    differences.push(`size ${stored.size} -> ${fresh.size}`);
+  }
+
+  if (differences.length === 0) {
+    return { infoHash: entry.infoHash, status: 'unchanged', fingerprint: fresh };
+  }
+
+  // A modification time that moves while size and ETag stay put is weak
+  // evidence: a touch, a restored backup, or a re-upload of identical bytes all
+  // do it. Confirm against the archive's own header before calling it a change,
+  // because the consequence of being wrong is re-hashing — or re-downloading —
+  // the whole archive.
+  const mtimeOnly =
+    differences.length === 1 && differences[0].startsWith('last-modified');
+  if (mtimeOnly && entry.pmtiles) {
+    const confirmed = await contentLooksDifferent(entry);
+    if (confirmed === false) {
+      return {
+        infoHash: entry.infoHash,
+        status: 'unchanged',
+        reason: 'modification time moved but the archive header is identical',
+        fingerprint: fresh,
+      };
+    }
+  }
+
+  return {
+    infoHash: entry.infoHash,
+    status: 'changed',
+    reason: differences.join('; '),
+    fingerprint: fresh,
+  };
+}
+
+/**
+ * Re-reads the archive's header to see whether its structure actually changed.
+ *
+ * Reads only the header and root directory, so it costs a few kilobytes even
+ * against a multi-terabyte archive. A rebuilt archive essentially always shifts
+ * these offsets; identical ones mean the bytes are almost certainly the same.
+ * @param {object} entry - The catalog entry, carrying the stored summary.
+ * @returns {Promise<boolean | null>} - True if different, false if identical, null if undeterminable.
+ */
+async function contentLooksDifferent(entry) {
+  try {
+    const { probePMTiles } = await import('./pmtiles-probe.js');
+    const fresh = await probePMTiles(entry.source.location);
+    const stored = entry.pmtiles;
+
+    const fields = [
+      'tileCount',
+      'minZoom',
+      'maxZoom',
+      'format',
+      'specVersion',
+    ];
+    for (const field of fields) {
+      // eslint-disable-next-line security/detect-object-injection -- field comes from the constant list above
+      if (stored[field] !== undefined && stored[field] !== fresh[field]) {
+        return true;
+      }
+    }
+    const sameBounds =
+      JSON.stringify(stored.bounds ?? []) === JSON.stringify(fresh.bounds ?? []);
+    return !sameBounds;
+  } catch {
+    // Cannot tell; let the caller fall back to the validator comparison.
+    return null;
+  }
+}

package/src/pmtiles-probe.js

@@ -0,0 +1,94 @@
+import { FetchSource, PMTiles } from 'pmtiles';
+import { NodeFileSource } from './file-source.js';
+
+/**
+ * Reads the facts about an archive that a subscriber needs in order to decide
+ * whether they want it: coverage, zoom range, tile type, size.
+ *
+ * This is what makes a map RSS feed more useful than a generic torrent feed —
+ * an item can say "raster webp, z0-14, covering Switzerland, 36 GiB" instead of
+ * just a filename, so a consumer can filter before committing to a download.
+ */
+
+/** Maps PMTiles tile type numbers onto names and content types. */
+const TILE_TYPES = {
+  0: { format: 'unknown', contentType: 'application/octet-stream' },
+  1: { format: 'pbf', contentType: 'application/x-protobuf' },
+  2: { format: 'png', contentType: 'image/png' },
+  3: { format: 'jpeg', contentType: 'image/jpeg' },
+  4: { format: 'webp', contentType: 'image/webp' },
+  5: { format: 'avif', contentType: 'image/avif' },
+};
+
+/**
+ * Summary of an archive, as stored in the catalog and published in the feed.
+ * @typedef {object} PMTilesSummary
+ * @property {number} specVersion - PMTiles spec version.
+ * @property {string} format - Tile format: pbf, png, jpeg, webp, avif.
+ * @property {string} contentType - Matching content type.
+ * @property {number} minZoom - Lowest zoom present.
+ * @property {number} maxZoom - Highest zoom present.
+ * @property {number[]} bounds - [minLon, minLat, maxLon, maxLat].
+ * @property {number[]} center - [lon, lat, zoom].
+ * @property {number} tileCount - Addressed tile count.
+ * @property {boolean} clustered - Whether tiles are stored in Hilbert order.
+ * @property {string} [name] - Name from the archive metadata.
+ * @property {string} [description] - Description from the archive metadata.
+ * @property {string} [attribution] - Attribution from the archive metadata.
+ * @property {object[]} [vectorLayers] - Vector layer definitions, for pbf archives.
+ */
+
+/**
+ * Reads an archive's header and metadata.
+ *
+ * Only the header and directory are read, not the tile data, so this is cheap
+ * even for a multi-terabyte archive — and it works against an HTTP URL without
+ * downloading it.
+ * @param {string} location - Local path or http(s) URL.
+ * @returns {Promise<PMTilesSummary>} - The summary.
+ */
+export async function probePMTiles(location) {
+  const isHttp = /^https?:\/\//i.test(location);
+  const source = isHttp ? new FetchSource(location) : new NodeFileSource(location);
+
+  try {
+    const archive = new PMTiles(source);
+    const header = await archive.getHeader();
+    const metadata = (await archive.getMetadata()) ?? {};
+
+    const type = TILE_TYPES[header.tileType] ?? TILE_TYPES[0];
+
+    // An archive with no bounds set reports all zeroes; treat that as global
+    // rather than as a point at null island.
+    const hasBounds = !(
+      header.minLon === 0 &&
+      header.minLat === 0 &&
+      header.maxLon === 0 &&
+      header.maxLat === 0
+    );
+
+    return {
+      specVersion: header.specVersion,
+      format: type.format,
+      contentType: type.contentType,
+      minZoom: header.minZoom,
+      maxZoom: header.maxZoom,
+      bounds: hasBounds
+        ? [header.minLon, header.minLat, header.maxLon, header.maxLat]
+        : [-180, -85.051129, 180, 85.051129],
+      center: [
+        header.centerLon,
+        header.centerLat,
+        header.centerZoom || Math.round(header.maxZoom / 2),
+      ],
+      tileCount: header.numAddressedTiles,
+      clustered: header.clustered,
+      name: metadata.name,
+      description: metadata.description,
+      attribution: metadata.attribution,
+      vectorLayers: metadata.vector_layers,
+    };
+  } finally {
+    source.close?.();
+  }
+}

package/src/read-engine.js

@@ -0,0 +1,175 @@
+/**
+ * Bridges the seeding engine onto the read engine pmtiles-torrent expects.
+ *
+ * The two interfaces answer different questions about the same torrent —
+ * "how is this doing in the swarm" versus "give me these bytes" — and both are
+ * satisfied by one client. Running a second client for the read side would mean
+ * two sessions on two ports contending for the same save path, so the bridge
+ * always reuses what the seeding engine already has open.
+ */
+
+/** libtorrent piece priorities. 0 means "do not fetch". */
+const LT_PRIORITY = { critical: 7, high: 4, normal: 1 };
+
+/**
+ * A TorrentEngine over the libtorrent sidecar the seed engine already runs.
+ *
+ * pmtiles-torrent ships its own LibtorrentEngine, but that one spawns and owns
+ * a sidecar. Here the sidecar belongs to the seeding engine and is already
+ * holding the torrent, so this speaks to it through the seed engine rather than
+ * starting a rival session.
+ * @implements {import('pmtiles-torrent').TorrentEngine}
+ */
+export class LibtorrentReadEngine {
+  #engine;
+  #infoHash;
+  #info = null;
+  #pending = null;
+  #pieceTimeoutMs;
+
+  /**
+   * @param {object} engine - The seeding LibtorrentEngine.
+   * @param {string} infoHash - Torrent to read from.
+   * @param {object} [options] - Per-piece timeout.
+   */
+  constructor(engine, infoHash, options = {}) {
+    this.#engine = engine;
+    this.#infoHash = infoHash;
+    this.#pieceTimeoutMs = options.pieceTimeoutMs ?? 120000;
+  }
+
+  /**
+   * A stable key available before metadata arrives.
+   * @returns {string} - Cache key for PMTiles.
+   */
+  get key() {
+    return `torrent:${this.#infoHash}`;
+  }
+
+  /**
+   * Resolves once torrent metadata is available.
+   * @returns {Promise<object>} - Piece geometry and file extent.
+   */
+  ready() {
+    // Idempotent by contract, and PMTiles calls it on every read.
+    this.#pending ??= (async () => {
+      const info = await this.#engine.info(this.#infoHash);
+      this.#info = info;
+      return info;
+    })().catch((error) => {
+      this.#pending = null;
+      throw error;
+    });
+    return this.#pending;
+  }
+
+  /**
+   * Reads a byte range from the archive.
+   *
+   * The source above only ever asks for whole pieces clipped to the file, so a
+   * range that straddles a piece boundary is a caller bug and is reported
+   * rather than quietly stitched together.
+   * @param {number} offset - Byte offset into the archive file.
+   * @param {number} length - Byte count.
+   * @param {object} [options] - Abort signal and priority.
+   * @returns {Promise<Uint8Array>} - Exactly `length` bytes.
+   */
+  async readRange(offset, length, options = {}) {
+    const info = this.#info ?? (await this.ready());
+    const globalStart = info.fileOffset + offset;
+    const first = Math.floor(globalStart / info.pieceLength);
+    const last = Math.floor((globalStart + length - 1) / info.pieceLength);
+    if (first !== last) {
+      throw new Error(
+        `read of ${length}B at ${offset} spans pieces ${first}-${last}; ` +
+          'the source is expected to split reads on piece boundaries',
+      );
+    }
+
+    if (options.signal?.aborted) throw abortError();
+    const piece = await this.#engine.readPiece(this.#infoHash, first, {
+      deadlineMs: 0,
+      timeoutMs: this.#pieceTimeoutMs,
+    });
+    if (options.signal?.aborted) throw abortError();
+
+    const within = globalStart - first * info.pieceLength;
+    const slice = piece.subarray(within, within + length);
+    if (slice.byteLength !== length) {
+      throw new Error(
+        `short read: wanted ${length}B at ${offset}, got ${slice.byteLength}B`,
+      );
+    }
+    return slice;
+  }
+
+  /**
+   * Raises a range's priority so it downloads in the background.
+   * @param {number} offset - Byte offset into the archive file.
+   * @param {number} length - Byte count.
+   * @param {string} priority - critical, high or normal.
+   * @returns {void}
+   */
+  hint(offset, length, priority) {
+    const range = this.#pieceRange(offset, length);
+    if (!range) return;
+    this.#engine
+      .setPriority(
+        this.#infoHash,
+        range.first,
+        range.last,
+        LT_PRIORITY[priority] ?? 1,
+      )
+      .catch(() => {});
+  }
+
+  /**
+   * Drops a range back to priority 0, so it stops competing for bandwidth.
+   * @param {number} offset - Byte offset into the archive file.
+   * @param {number} length - Byte count.
+   * @returns {void}
+   */
+  unhint(offset, length) {
+    const range = this.#pieceRange(offset, length);
+    if (!range) return;
+    this.#engine
+      .setPriority(this.#infoHash, range.first, range.last, 0)
+      .catch(() => {});
+  }
+
+  /**
+   * Releases the reader. The sidecar belongs to the seeding engine and keeps
+   * running — the torrent is still being seeded.
+   * @returns {void}
+   */
+  destroy() {
+    this.#pending = null;
+    this.#info = null;
+  }
+
+  /**
+   * Maps a file-relative byte range onto torrent-global piece indices.
+   * @param {number} offset - Byte offset into the archive file.
+   * @param {number} length - Byte count.
+   * @returns {{first: number, last: number} | null} - Piece range, or null before metadata.
+   */
+  #pieceRange(offset, length) {
+    const info = this.#info;
+    if (!info || length <= 0) return null;
+    const start = info.fileOffset + offset;
+    return {
+      first: Math.floor(start / info.pieceLength),
+      last: Math.floor((start + length - 1) / info.pieceLength),
+    };
+  }
+}
+
+/**
+ * Builds the abort rejection PMTiles and the source layer expect.
+ * @returns {Error} - An AbortError.
+ */
+function abortError() {
+  const error = new Error('The operation was aborted.');
+  error.name = 'AbortError';
+  return error;
+}