pmtiles-swarm 0.2.0

package/src/engines/qbittorrent.js

@@ -0,0 +1,320 @@
+/**
+ * A SeedEngine driving qBittorrent over its WebUI API (v2).
+ *
+ * qBittorrent is libtorrent underneath, so it handles multi-terabyte libraries,
+ * hybrid v1+v2 torrents and resume data far better than anything we would
+ * write. What it does not expose is piece-level control — only per-file
+ * priorities — which is why random-access reads still go through
+ * pmtiles-torrent rather than here.
+ *
+ * API reference: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)
+ */
+
+/** Map qBittorrent's many states onto the handful we report. */
+const STATE_MAP = {
+  error: 'error',
+  missingFiles: 'error',
+  uploading: 'seeding',
+  pausedUP: 'paused',
+  stoppedUP: 'paused',
+  queuedUP: 'stalled',
+  stalledUP: 'seeding',
+  checkingUP: 'checking',
+  forcedUP: 'seeding',
+  allocating: 'checking',
+  downloading: 'downloading',
+  metaDL: 'downloading',
+  pausedDL: 'paused',
+  stoppedDL: 'paused',
+  queuedDL: 'stalled',
+  stalledDL: 'downloading',
+  checkingDL: 'checking',
+  forcedDL: 'downloading',
+  checkingResumeData: 'checking',
+  moving: 'checking',
+  unknown: 'error',
+};
+
+/**
+ * Options for the qBittorrent engine.
+ * @typedef {object} QBittorrentEngineOptions
+ * @property {string} url - Base URL of the WebUI, e.g. http://172.16.1.49:9091
+ * @property {string} [username] - WebUI username. Omit if auth is bypassed for this host.
+ * @property {string} [password] - WebUI password.
+ * @property {number} [timeoutMs] - Per-request timeout. Default 15s.
+ */
+
+/**
+ * Drives a qBittorrent instance.
+ * @implements {import('./types.js').SeedEngine}
+ */
+export class QBittorrentEngine {
+  #options;
+  #cookie = null;
+
+  /**
+   * Creates the engine.
+   * @param {QBittorrentEngineOptions} options - Connection details.
+   */
+  constructor(options) {
+    if (!options?.url) throw new Error('qBittorrent engine requires a url');
+    this.name = 'qbittorrent';
+    this.#options = { timeoutMs: 15000, ...options };
+  }
+
+  /**
+   * Logs in, or confirms that auth is not required.
+   * @returns {Promise<void>} - Resolves when usable.
+   */
+  async connect() {
+    // qBittorrent can be configured to bypass auth for local subnets, in which
+    // case there is no session cookie and requests just work.
+    if (!this.#options.username) {
+      await this.#request('/api/v2/app/version');
+      return;
+    }
+
+    const body = new URLSearchParams({
+      username: this.#options.username,
+      password: this.#options.password ?? '',
+    });
+    const response = await this.#fetch('/api/v2/auth/login', {
+      method: 'POST',
+      body,
+    });
+    const text = (await response.text()).trim();
+    if (text !== 'Ok.') {
+      throw new Error(
+        `qBittorrent login rejected (${response.status}): ${text || 'no reason given'}`,
+      );
+    }
+    const setCookie = response.headers.get('set-cookie');
+    if (setCookie) this.#cookie = setCookie.split(';')[0];
+  }
+
+  /**
+   * Adds a torrent.
+   * @param {import('./types.js').AddRequest} request - What to add.
+   * @returns {Promise<string>} - The infohash.
+   */
+  async add(request) {
+    const form = new FormData();
+    if (request.torrentFile) {
+      form.append(
+        'torrents',
+        new Blob([request.torrentFile], { type: 'application/x-bittorrent' }),
+        'archive.torrent',
+      );
+    } else if (request.magnet) {
+      form.append('urls', request.magnet);
+    } else {
+      throw new Error('add requires either torrentFile or magnet');
+    }
+
+    if (request.savePath) form.append('savepath', request.savePath);
+    if (request.category) form.append('category', request.category);
+    if (request.paused) form.append('paused', 'true');
+
+    // Cache mode needs piece-level selection, and qBittorrent's WebUI exposes
+    // only per-file priorities — for a single-file archive that is all or
+    // nothing. Adding it stopped is the closest honest approximation: the
+    // torrent is registered and can be read on demand by a client that does
+    // have piece-level control, without this engine pulling the whole archive.
+    if (request.mode === 'cache') form.append('stopped', 'true');
+    // The data is already on disk; qBittorrent still verifies it, but this
+    // stops it trying to download what it already has.
+    if (request.seedOnly) form.append('skip_checking', 'false');
+
+    const response = await this.#request('/api/v2/torrents/add', {
+      method: 'POST',
+      body: form,
+    });
+    const text = (await response.text()).trim();
+    if (text && text !== 'Ok.') {
+      throw new Error(`qBittorrent refused the torrent: ${text}`);
+    }
+
+    const infoHash = await this.#infoHashOf(request);
+    if (!infoHash) {
+      throw new Error(
+        'torrent was accepted but its infohash could not be determined',
+      );
+    }
+    return infoHash;
+  }
+
+  /**
+   * Removes a torrent.
+   * @param {string} infoHash - The torrent to remove.
+   * @param {{deleteData?: boolean}} [options] - Whether to delete the data too.
+   * @returns {Promise<void>} - Resolves once removed.
+   */
+  async remove(infoHash, options = {}) {
+    const body = new URLSearchParams({
+      hashes: infoHash.toLowerCase(),
+      deleteFiles: options.deleteData ? 'true' : 'false',
+    });
+    await this.#request('/api/v2/torrents/delete', { method: 'POST', body });
+  }
+
+  /**
+   * Lists every torrent qBittorrent holds.
+   * @returns {Promise<import('./types.js').TorrentStatus[]>} - Normalised statuses.
+   */
+  async list() {
+    const response = await this.#request('/api/v2/torrents/info');
+    const rows = await response.json();
+    return rows.map((row) => this.#normalise(row));
+  }
+
+  /**
+   * One torrent's state.
+   * @param {string} infoHash - The torrent to look up.
+   * @returns {Promise<import('./types.js').TorrentStatus | null>} - Its status, or null.
+   */
+  async get(infoHash) {
+    const response = await this.#request(
+      `/api/v2/torrents/info?hashes=${encodeURIComponent(infoHash.toLowerCase())}`,
+    );
+    const rows = await response.json();
+    return rows.length > 0 ? this.#normalise(rows[0]) : null;
+  }
+
+  /**
+   * Per-peer detail for a torrent.
+   * @param {string} infoHash - The torrent to inspect.
+   * @returns {Promise<object[]>} - One entry per connected peer.
+   */
+  async peers(infoHash) {
+    const response = await this.#request(
+      `/api/v2/sync/torrentPeers?hash=${encodeURIComponent(infoHash.toLowerCase())}&rid=0`,
+    );
+    const body = await response.json();
+    return Object.entries(body.peers ?? {}).map(([address, peer]) => ({
+      address,
+      client: peer.client,
+      country: peer.country,
+      progress: peer.progress,
+      downloadSpeed: peer.dl_speed,
+      uploadSpeed: peer.up_speed,
+      flags: peer.flags,
+      connection: peer.connection,
+    }));
+  }
+
+  /**
+   * Drops the session. qBittorrent itself keeps running.
+   * @returns {Promise<void>} - Resolves immediately.
+   */
+  async destroy() {
+    this.#cookie = null;
+  }
+
+  /**
+   * Normalises a qBittorrent torrent record.
+   * @param {object} row - A row from /torrents/info.
+   * @returns {import('./types.js').TorrentStatus} - Normalised status.
+   */
+  #normalise(row) {
+    return {
+      infoHash: row.hash,
+      name: row.name,
+      size: row.total_size ?? row.size,
+      progress: row.progress,
+      // eslint-disable-next-line security/detect-object-injection -- state comes from qBittorrent and falls back
+      state: STATE_MAP[row.state] ?? 'error',
+      peers: row.num_leechs ?? 0,
+      seeds: row.num_seeds ?? 0,
+      downloadSpeed: row.dlspeed ?? 0,
+      uploadSpeed: row.upspeed ?? 0,
+      downloaded: row.downloaded ?? 0,
+      uploaded: row.uploaded ?? 0,
+      ratio: row.ratio ?? 0,
+      category: row.category || undefined,
+      savePath: row.save_path,
+    };
+  }
+
+  /**
+   * Works out the infohash of something we just added.
+   *
+   * qBittorrent's add endpoint returns only "Ok.", so for a magnet we read the
+   * hash out of the URI, and for a torrent file we look for the newest torrent
+   * that was not there before.
+   * @param {import('./types.js').AddRequest} request - What was added.
+   * @returns {Promise<string | null>} - The infohash, if it can be determined.
+   */
+  async #infoHashOf(request) {
+    if (request.magnet) {
+      const match = /xt=urn:btih:([a-z0-9]+)/i.exec(request.magnet);
+      if (match) return match[1].toLowerCase();
+    }
+    if (request.torrentFile) {
+      const { default: parseTorrent } = await import('parse-torrent');
+      const parsed = await parseTorrent(request.torrentFile);
+      return parsed?.infoHash ?? null;
+    }
+    return null;
+  }
+
+  /**
+   * Issues an authenticated request, retrying once through a fresh login if
+   * the session has expired.
+   * @param {string} path - API path.
+   * @param {object} [init] - Fetch options.
+   * @returns {Promise<Response>} - The response.
+   */
+  async #request(path, init = {}) {
+    let response = await this.#fetch(path, init);
+    if (response.status === 403 && this.#options.username) {
+      this.#cookie = null;
+      await this.connect();
+      response = await this.#fetch(path, init);
+    }
+    if (!response.ok) {
+      throw new Error(
+        `qBittorrent ${path} failed: ${response.status} ${response.statusText}`,
+      );
+    }
+    return response;
+  }
+
+  /**
+   * Raw fetch against the WebUI, carrying the session cookie.
+   * @param {string} path - API path.
+   * @param {object} [init] - Fetch options.
+   * @returns {Promise<Response>} - The response.
+   */
+  async #fetch(path, init = {}) {
+    const headers = new Headers(init.headers ?? {});
+    if (this.#cookie) headers.set('cookie', this.#cookie);
+    // qBittorrent rejects cross-origin requests unless Referer matches.
+    headers.set('Referer', this.#options.url);
+
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      this.#options.timeoutMs,
+    );
+    try {
+      return await fetch(new URL(path, this.#options.url), {
+        ...init,
+        headers,
+        signal: controller.signal,
+        redirect: 'manual',
+      });
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        throw new Error(
+          `qBittorrent ${path} timed out after ${this.#options.timeoutMs}ms`,
+        );
+      }
+      throw new Error(
+        `qBittorrent ${path} unreachable at ${this.#options.url}: ${error.message}`,
+        { cause: error },
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}

package/src/engines/types.js

@@ -0,0 +1,59 @@
+/**
+ * The seeding-engine abstraction.
+ *
+ * This is the distribution counterpart to the read-side engine in
+ * pmtiles-torrent: that one answers "give me these bytes", this one answers
+ * "hold this archive in the swarm and tell me how it is doing".
+ *
+ * Keeping it behind an interface is what lets qBittorrent do the bulk seeding
+ * — it is libtorrent underneath, handles multi-terabyte libraries, and speaks
+ * BitTorrent v2 — while an embedded WebTorrent client covers the things it
+ * cannot: serving browser peers over WebRTC, and running with no external
+ * dependency at all.
+ */
+
+/**
+ * Live state of one torrent, normalised across engines.
+ * @typedef {object} TorrentStatus
+ * @property {string} infoHash - Hex v1 infohash.
+ * @property {string} name - Display name.
+ * @property {number} size - Total bytes.
+ * @property {number} progress - Fraction complete, 0 to 1.
+ * @property {string} state - Normalised state: 'seeding' | 'downloading' | 'cache' | 'stalled' | 'checking' | 'paused' | 'error'. 'cache' means joined and seeding what it holds, but fetching nothing on its own.
+ * @property {number} peers - Connected non-seeding peers.
+ * @property {number} seeds - Connected seeds.
+ * @property {number} downloadSpeed - Bytes per second.
+ * @property {number} uploadSpeed - Bytes per second.
+ * @property {number} downloaded - Bytes downloaded this session and before.
+ * @property {number} uploaded - Bytes uploaded.
+ * @property {number} ratio - Share ratio.
+ * @property {string} [category] - Engine-side category, where supported.
+ * @property {string} [savePath] - Where the data lives.
+ */
+
+/**
+ * What to add to the swarm. Either a torrent file or a magnet must be given.
+ * @typedef {object} AddRequest
+ * @property {Uint8Array} [torrentFile] - Raw .torrent contents.
+ * @property {string} [magnet] - Magnet URI.
+ * @property {string} [savePath] - Directory holding (or to hold) the data.
+ * @property {string} [category] - Category to file it under.
+ * @property {boolean} [seedOnly] - The data is already complete locally; skip downloading.
+ * @property {boolean} [paused] - Add without starting.
+ * @property {'mirror' | 'cache'} [mode] - 'mirror' downloads the whole archive and becomes a full seeder. 'cache' joins the swarm but downloads nothing up front, leaving a tile server to pull byte ranges on demand — the difference between spending 72 GiB of disk and spending what is actually viewed. Cache mode needs piece-level control, so it is only honoured by engines that have it.
+ */
+
+/**
+ * A seeding backend.
+ * @typedef {object} SeedEngine
+ * @property {string} name - Short identifier, e.g. 'qbittorrent'.
+ * @property {() => Promise<void>} connect - Establishes the connection, or throws.
+ * @property {(request: AddRequest) => Promise<string>} add - Adds a torrent, resolving with its infohash.
+ * @property {(infoHash: string, options?: {deleteData?: boolean}) => Promise<void>} remove - Removes a torrent.
+ * @property {() => Promise<TorrentStatus[]>} list - Lists everything the engine holds.
+ * @property {(infoHash: string) => Promise<TorrentStatus | null>} get - One torrent's state.
+ * @property {(infoHash: string) => Promise<object[]>} [peers] - Per-peer detail, where the engine exposes it.
+ * @property {() => Promise<void>} destroy - Releases resources.
+ */
+
+export {};

package/src/engines/webtorrent.js

@@ -0,0 +1,264 @@
+/**
+ * A SeedEngine backed by an embedded WebTorrent client.
+ *
+ * Covers the two things qBittorrent cannot: serving browser peers over WebRTC,
+ * and running with no external dependency at all. It is a weaker bulk seeder
+ * than libtorrent and is BitTorrent v1 only, so for a multi-terabyte library
+ * prefer the qBittorrent engine and run this alongside as the browser bridge.
+ *
+ * Written against WebTorrent's public API (MIT, Copyright (c) Feross
+ * Aboukhadijeh and WebTorrent, LLC). See NOTICE.md.
+ */
+
+/**
+ * Options for the embedded engine.
+ * @typedef {object} WebTorrentEngineOptions
+ * @property {string} savePath - Default directory for torrent data.
+ * @property {object} [clientOptions] - Options passed to new WebTorrent().
+ * @property {number} [readyTimeoutMs] - How long to wait for metadata. Default 300s, because a magnet must complete a BEP 9 exchange first.
+ */
+
+/**
+ * Seeds through an in-process WebTorrent client.
+ * @implements {import('./types.js').SeedEngine}
+ */
+export class WebTorrentSeedEngine {
+  #options;
+  #client = null;
+
+  /**
+   * Creates the engine.
+   * @param {WebTorrentEngineOptions} options - Save path and client options.
+   */
+  constructor(options) {
+    if (!options?.savePath) {
+      throw new Error('WebTorrent engine requires a savePath');
+    }
+    this.name = 'webtorrent';
+    this.#options = { readyTimeoutMs: 300000, ...options };
+  }
+
+  /**
+   * The underlying client, once connected.
+   * @returns {object | null} - The WebTorrent client.
+   */
+  get client() {
+    return this.#client;
+  }
+
+  /**
+   * Starts the client.
+   * @returns {Promise<void>} - Resolves once running.
+   */
+  async connect() {
+    if (this.#client) return;
+    const WebTorrent = await loadWebTorrent();
+    this.#client = new WebTorrent({
+      maxConns: this.#options.maxConnections,
+      ...this.#options.clientOptions,
+    });
+    this.#client.on('error', (error) => {
+      console.error(`[webtorrent] client error: ${error.message}`);
+    });
+  }
+
+  /**
+   * Adds a torrent and waits for its metadata.
+   * @param {import('./types.js').AddRequest} request - What to add.
+   * @returns {Promise<string>} - The infohash.
+   */
+  async add(request) {
+    await this.connect();
+    const id = request.torrentFile ?? request.magnet;
+    if (!id) throw new Error('add requires either torrentFile or magnet');
+
+    const addOptions = {
+      path: request.savePath ?? this.#options.savePath,
+      // Cache mode selects nothing, so joining a 72 GiB archive costs nothing
+      // until something actually reads from it. Mirror mode takes the lot.
+      deselect: request.mode === 'cache',
+    };
+
+    const timeoutMs = this.#options.readyTimeoutMs;
+    const torrent = await new Promise((resolve, reject) => {
+      let settled = false;
+      /**
+       * Settles once, clearing the timer.
+       * @param {() => void} fn - The settle action.
+       * @returns {void}
+       */
+      const finish = (fn) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        fn();
+      };
+      const timer = setTimeout(
+        () =>
+          finish(() =>
+            reject(
+              new Error(
+                `timed out after ${timeoutMs}ms waiting for torrent metadata`,
+              ),
+            ),
+          ),
+        timeoutMs,
+      );
+
+      let added;
+      try {
+        added = this.#client.add(id, addOptions, (t) =>
+          finish(() => resolve(t)),
+        );
+      } catch (error) {
+        finish(() => reject(error));
+        return;
+      }
+      added.once('error', (error) => {
+        // A duplicate is not fatal: the callback still fires with the torrent
+        // the client already holds.
+        if (/duplicate torrent/i.test(error?.message ?? '')) return;
+        finish(() => reject(error));
+      });
+    });
+
+    if (request.paused) torrent.pause();
+    return torrent.infoHash;
+  }
+
+  /**
+   * Removes a torrent.
+   * @param {string} infoHash - The torrent to remove.
+   * @param {{deleteData?: boolean}} [options] - Whether to delete the data too.
+   * @returns {Promise<void>} - Resolves once removed.
+   */
+  async remove(infoHash, options = {}) {
+    if (!this.#client) return;
+    await new Promise((resolve) => {
+      this.#client.remove(
+        infoHash,
+        { destroyStore: Boolean(options.deleteData) },
+        () => resolve(),
+      );
+    });
+  }
+
+  /**
+   * Lists every torrent the client holds.
+   * @returns {Promise<import('./types.js').TorrentStatus[]>} - Normalised statuses.
+   */
+  async list() {
+    if (!this.#client) return [];
+    return this.#client.torrents.map((torrent) => this.#normalise(torrent));
+  }
+
+  /**
+   * One torrent's state.
+   * @param {string} infoHash - The torrent to look up.
+   * @returns {Promise<import('./types.js').TorrentStatus | null>} - Its status, or null.
+   */
+  async get(infoHash) {
+    if (!this.#client) return null;
+    const torrent = this.#client.get(infoHash);
+    return torrent ? this.#normalise(torrent) : null;
+  }
+
+  /**
+   * Per-peer detail for a torrent.
+   * @param {string} infoHash - The torrent to inspect.
+   * @returns {Promise<object[]>} - One entry per connected peer.
+   */
+  async peers(infoHash) {
+    const torrent = this.#client?.get(infoHash);
+    if (!torrent) return [];
+    return torrent.wires.map((wire) => ({
+      address: wire.remoteAddress
+        ? `${wire.remoteAddress}:${wire.remotePort}`
+        : 'unknown',
+      client: wire.peerExtendedHandshake?.v ?? 'unknown',
+      progress: torrent.pieces.length
+        ? countBits(wire.peerPieces, torrent.pieces.length) /
+          torrent.pieces.length
+        : 0,
+      downloadSpeed: wire.downloadSpeed(),
+      uploadSpeed: wire.uploadSpeed(),
+      connection: wire.type ?? 'tcp',
+    }));
+  }
+
+  /**
+   * Shuts the client down, announcing 'stopped' to trackers.
+   * @returns {Promise<void>} - Resolves once destroyed.
+   */
+  async destroy() {
+    if (!this.#client) return;
+    const client = this.#client;
+    this.#client = null;
+    await new Promise((resolve) => client.destroy(() => resolve()));
+  }
+
+  /**
+   * Normalises a WebTorrent torrent.
+   * @param {object} torrent - The torrent.
+   * @returns {import('./types.js').TorrentStatus} - Normalised status.
+   */
+  #normalise(torrent) {
+    const seeds = torrent.wires.filter((w) => w.isSeeder).length;
+    return {
+      infoHash: torrent.infoHash,
+      name: torrent.name,
+      size: torrent.length ?? 0,
+      progress: torrent.progress ?? 0,
+      state: torrent.paused
+        ? 'paused'
+        : torrent.done
+          ? 'seeding'
+          : torrent.numPeers > 0
+            ? 'downloading'
+            : 'stalled',
+      peers: Math.max(0, torrent.numPeers - seeds),
+      seeds,
+      downloadSpeed: torrent.downloadSpeed ?? 0,
+      uploadSpeed: torrent.uploadSpeed ?? 0,
+      downloaded: torrent.downloaded ?? 0,
+      uploaded: torrent.uploaded ?? 0,
+      ratio: torrent.ratio ?? 0,
+      savePath: torrent.path,
+    };
+  }
+}
+
+/**
+ * Counts set bits in a peer's bitfield.
+ * @param {object} bitfield - A BitField instance.
+ * @param {number} pieces - Total piece count.
+ * @returns {number} - How many pieces the peer has.
+ */
+function countBits(bitfield, pieces) {
+  if (!bitfield) return 0;
+  let count = 0;
+  for (let i = 0; i < pieces; i++) if (bitfield.get(i)) count++;
+  return count;
+}
+
+/**
+ * Loads WebTorrent lazily, so it stays an optional dependency.
+ * @returns {Promise<new (opts?: object) => object>} - The constructor.
+ */
+async function loadWebTorrent() {
+  try {
+    const specifier = 'webtorrent';
+    const mod = await import(specifier);
+    const ctor = mod.default ?? mod;
+    if (typeof ctor !== 'function') {
+      throw new Error('webtorrent module did not export a constructor');
+    }
+    return ctor;
+  } catch (error) {
+    throw new Error(
+      "The webtorrent engine needs the optional dependency 'webtorrent'. " +
+        `Install it, or use the qbittorrent engine instead. (${error.message})`,
+      { cause: error },
+    );
+  }
+}