bun-torrent 0.0.6 → 0.0.8

package/README.md

@@ -2,7 +2,7 @@
 
 A minimal Bun-native BitTorrent download-only client written in TypeScript.
 
-`bun-torrent` can parse `.torrent` files and tracker-backed magnet links, announce to HTTP and UDP trackers, connect to peers, download pieces, validate piece hashes, and write the downloaded files to disk. The public API is intentionally small: create a `Client`, inspect a torrent when you need metadata, then call `download()`.
+`bun-torrent` can parse `.torrent` files and magnet links, announce to HTTP and UDP trackers, discover peers through the BitTorrent DHT, connect to peers, download pieces, validate piece hashes, and write the downloaded files to disk. The public API is intentionally small: create a `Client`, inspect a torrent when you need metadata, then call `download()`.
 
 It has no runtime dependencies.
 
@@ -57,6 +57,17 @@ await torrent.done;
 
 `download()` returns a `Torrent` instance and starts the download immediately.
 
+## Runnable Example Files
+
+Runnable example files are available in `examples/`:
+
+```bash
+bun examples/download-torrent.ts ./example.torrent ./downloads
+bun examples/magnet-dht.ts "magnet:?xt=urn:btih:..." ./downloads
+```
+
+The magnet example works with tracker-backed and trackerless magnets. It uses the default in-memory DHT node and closes the client before exiting.
+
 ## Client Setup
 
 ```ts
@@ -78,6 +89,7 @@ const client = new Client({
 
 Client options:
 
+- `dht`: optional DHT peer discovery implementation, or `false` to disable DHT. By default, the client creates an in-memory DHT node.
 - `outputDirectory`: directory where downloaded files are written. Defaults to `process.cwd()`.
 - `files`: optional default file selection for downloads.
 - `targetConnections`: preferred number of connected peers. Defaults to `20`.
@@ -109,9 +121,11 @@ console.log(metadata.files);
 
 Torrent file input can be a file path, `Uint8Array`, or `ArrayBuffer`.
 
+Call `client.close()` when the client should stop accepting work and close active torrents and its DHT socket.
+
 ## Magnet Links
 
-Magnet links are supported when they include at least one HTTP, HTTPS, or UDP tracker through the `tr` parameter. Metadata is fetched from peers with the `ut_metadata` extension before the normal download flow starts.
+Magnet links are supported with or without trackers. If `tr` parameters are present, the client asks those trackers first. If no tracker returns peers, or the magnet is trackerless, the client falls back to DHT peer discovery. Metadata is fetched from peers with the `ut_metadata` extension before the normal download flow starts.
 
 ```ts
 const magnet =
@@ -134,13 +148,42 @@ const torrent = await client.download(
 await torrent.done;
 ```
 
+Trackerless magnets use the same API. Keep the same `Client` instance if you inspect first and download later, because the default DHT node keeps discovered peers in memory for the current process.
+
+```ts
+import { Client } from 'bun-torrent';
+
+const client = new Client({
+    outputDirectory: './downloads',
+});
+
+const magnet = 'magnet:?xt=urn:btih:0123456789abcdef0123456789abcdef01234567';
+
+try {
+    const metadata = await client.inspect({ magnet });
+
+    console.log(metadata.name);
+    console.log(metadata.files);
+
+    const torrent = await client.download({ meta: metadata });
+
+    torrent.on('progress', (progress) => {
+        console.log(`${(progress.percent * 100).toFixed(2)}%`, progress.speed);
+    });
+
+    await torrent.done;
+} finally {
+    client.close();
+}
+```
+
 Supported magnet fields:
 
 - `xt=urn:btih:<infoHash>`: required. Hex-encoded 40-character info hashes and base32 32-character info hashes are supported.
 - `dn`: optional display name.
-- `tr`: optional tracker URL. Multiple `tr` parameters are supported.
+- `tr`: optional tracker URL. Multiple `tr` parameters are supported, but trackerless magnets can resolve through DHT.
 
-Trackerless magnets are not supported yet because DHT peer discovery is not implemented. A magnet without `tr` currently fails during inspection with a DHT-not-implemented error.
+The default DHT node is in-memory. It keeps a routing table and a short-lived peer cache for the current process, so a magnet `inspect()` can populate peers that a later `download({ meta })` call can reuse on the same `Client` instance. The DHT state is not persisted to disk.
 
 ## Download Options
 
@@ -181,7 +224,7 @@ Download options:
 - `speedSampleIntervalMs`: override speed sample interval.
 - `onChangeState`: receives client setup states: `parsing`, `tracking`, `connecting`, `downloading`.
 
-Tracker announce failures are treated as non-fatal. If no tracker responds, the client can still continue with an empty peer list instead of throwing during tracking.
+Tracker announce failures are treated as non-fatal. If trackers are missing or do not return peers, the client falls back to DHT when it is enabled. With DHT disabled, the client can still continue with an empty peer list instead of throwing during tracking when `minConnections` is `0`.
 
 ## Selecting Files
 

package/dist/app.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/app.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env bun
+import { bytesToHex } from './utils/buffers';
+import { formatBytes } from './utils/formats';
+import { Client } from './client';
+const summarizeTorrent = (metadata) => ({
+    announce: metadata.announce,
+    announceList: metadata.announceList,
+    infoHash: bytesToHex(metadata.infoHash),
+    name: metadata.name,
+    pieceLength: metadata.pieceLength,
+    piecesTotal: metadata.pieces.length,
+    length: metadata.length,
+    files: metadata.files.map((file) => ({
+        path: file.path.join('/'),
+        length: file.length,
+        offset: file.offset,
+    })),
+    filesTotal: metadata.files.length,
+});
+const usage = () => {
+    console.error('Usage:');
+    console.error('  bunx bun-torrent inspect <file.torrent>');
+    console.error('  bunx bun-torrent inspect <magnet-uri>');
+    console.error('  bunx bun-torrent inspect < file.torrent');
+    console.error('  bunx bun-torrent download <file.torrent|magnet-uri> [output-directory]');
+};
+const inspect = async (input) => {
+    const client = new Client();
+    try {
+        const metadata = input ? await inspectArgument(client, input) : await inspectStdin(client);
+        console.log(JSON.stringify(summarizeTorrent(metadata), null, 2));
+    }
+    finally {
+        client.close();
+    }
+};
+const resolveInput = (input) => {
+    if (input.startsWith('magnet:')) {
+        return { magnet: input };
+    }
+    return { torrentFile: input };
+};
+const inspectArgument = async (client, input) => {
+    return await client.inspect(resolveInput(input));
+};
+const inspectStdin = async (client) => {
+    const input = new Uint8Array(await Bun.stdin.arrayBuffer());
+    if (input.byteLength === 0) {
+        throw new Error('Expected torrent file bytes on stdin');
+    }
+    return await client.inspect({ torrentFile: input });
+};
+const download = async (input, outputDirectory = './downloads') => {
+    if (!input) {
+        throw new Error('Expected file.torrent or magnet URI');
+    }
+    const client = new Client({ outputDirectory });
+    let state = 'starting';
+    let progress = null;
+    let stats = null;
+    const render = () => renderProgressLine(state, progress, stats);
+    try {
+        render();
+        const torrent = await client.download(resolveInput(input), {
+            progressEvents: 'block',
+            onChangeState: (nextState) => {
+                state = nextState;
+                render();
+            },
+        });
+        progress = torrent.progress;
+        stats = torrent.stats;
+        render();
+        torrent.on('progress', (nextProgress) => {
+            progress = nextProgress;
+            render();
+        });
+        torrent.on('peer', (nextStats) => {
+            stats = nextStats;
+            render();
+        });
+        await torrent.done;
+        state = 'completed';
+        progress = torrent.progress;
+        stats = torrent.stats;
+        render();
+        process.stdout.write('\nDownload complete\n');
+    }
+    finally {
+        client.close();
+    }
+};
+const renderProgressLine = (state, progress, stats) => {
+    const bar = progress ? progressBar(progress.percent) : progressBar(0);
+    const percent = progress ? `${(progress.percent * 100).toFixed(2).padStart(6)}%` : '  0.00%';
+    const downloaded = progress ? formatBytes(progress.downloadedBytes) : '0.0 B';
+    const total = progress ? formatBytes(progress.totalBytes) : '?';
+    const speed = progress?.speed ?? '0.0 Bps';
+    const pieces = progress
+        ? `pieces=${progress.completedPieces}/${progress.totalPieces}`
+        : 'pieces=?/?';
+    const peers = stats ? `peers=${stats.connections}/${stats.peers}` : 'peers=0/0';
+    const line = `${state.padEnd(11)} ${bar} ${percent} ${downloaded}/${total} ${speed} ${pieces} ${peers}`;
+    process.stdout.write(`\r${line}\x1b[K`);
+};
+const progressBar = (percent) => {
+    const width = 28;
+    const normalized = Math.min(1, Math.max(0, percent));
+    const filled = Math.round(normalized * width);
+    return `[${'#'.repeat(filled)}${'-'.repeat(width - filled)}]`;
+};
+if (import.meta.main) {
+    const command = Bun.argv[2];
+    const input = Bun.argv[3];
+    const outputDirectory = Bun.argv[4];
+    try {
+        switch (command) {
+            case 'inspect':
+                await inspect(input);
+                break;
+            case 'download':
+                await download(input, outputDirectory);
+                break;
+            default:
+                usage();
+                process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        if (command === 'download')
+            process.stdout.write('\n');
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -2,24 +2,61 @@ import { type DownloadProgressEventMode } from './torrent/download';
 import { Torrent } from './torrent/session/index';
 import type { TorrentMetadata } from './torrent/types';
 import type { TorrentFileSelection } from './torrent/file-selection';
+import type { PeerInfo } from './tracker/types';
+/**
+ * Setup phases reported through {@link DownloadOptions.onChangeState} before download starts.
+ *
+ * The values are emitted in order: `parsing` → `tracking` → `connecting` → `downloading`.
+ * Once `downloading` fires, progress events take over via {@link Torrent.on}.
+ */
 export declare enum DownloadState {
     PARSING = "parsing",
     TRACKING = "tracking",
     CONNECTING = "connecting",
     DOWNLOADING = "downloading"
 }
+/**
+ * Minimal DHT contract used by {@link Client} for peer discovery.
+ *
+ * Implement this to swap the default in-memory DHT for a persistent or
+ * shared implementation. `close` is called from {@link Client.close}.
+ */
+export type ClientDht = {
+    lookupPeers(infoHash: Uint8Array): Promise<PeerInfo[]>;
+    close?(): void;
+};
+/**
+ * Default options applied to every download started by a {@link Client}.
+ *
+ * All fields are optional. Any field can be overridden per-download via
+ * {@link DownloadOptions}.
+ */
 export type ClientConfig = {
+    /** Custom DHT implementation, or `false` to disable DHT entirely. Defaults to an in-memory {@link DhtClient}. */
+    dht?: ClientDht | false;
+    /** Default file selection for multi-file torrents. `null`/omitted downloads every file. */
     files?: TorrentFileSelection;
+    /** Maximum block requests in flight per peer. Higher values increase throughput but also memory. Defaults to 300. */
     maxInFlightRequestsPerPeer?: number;
+    /** Maximum simultaneous peer connection attempts. Defaults to 30. */
     maxConnecting?: number;
+    /** Minimum connected peers required before download starts. `0` allows downloads to start with no peers. Defaults to 0. */
     minConnections?: number;
+    /** Directory where downloaded files are written. Defaults to `process.cwd()`. */
     outputDirectory?: string;
+    /** Timeout for a single peer TCP connect + handshake, in milliseconds. Defaults to 5000. */
     peerConnectTimeoutMs?: number;
+    /** Granularity of `progress` events: `'piece'` (once per validated piece) or `'block'` (every received block). Defaults to `'piece'`. */
     progressEvents?: DownloadProgressEventMode;
+    /** Timeout for a single block request, in milliseconds. Timed-out requests are retried on other peers. Defaults to 15000. */
     requestTimeoutMs?: number;
+    /** Reserved for future seeding support. Currently only `false` is supported. */
     seed?: false;
+    /** Minimum interval between speed recalculations, in milliseconds. Defaults to 500. */
     speedSampleIntervalMs?: number;
+    /** Preferred number of connected peers. The pool stops opening new connections once this is reached. Defaults to 20. */
     targetConnections?: number;
+    /** Timeout for tracker announce requests, in milliseconds. Defaults to 5000. */
     trackerTimeoutMs?: number;
 };
 type InspectInput = {
@@ -34,32 +71,130 @@ type InspectInput = {
 type DownloadInput = {
     meta: TorrentMetadata;
 } | InspectInput;
+/**
+ * Entry point of the library. Holds shared state (peer id, DHT node) across downloads.
+ *
+ * One `Client` instance can run multiple concurrent downloads. The same client is also
+ * reused across `inspect` → `download` flows so the DHT routing table and peer cache
+ * can warm up once and pay off on subsequent calls.
+ *
+ * Call {@link Client.close} when the client is no longer needed — it closes every
+ * active torrent and the DHT socket. After close, every method throws {@link ClientError}.
+ *
+ * @example
+ * const client = new Client({ outputDirectory: './downloads' });
+ * try {
+ *     const torrent = await client.download({ torrentFile: './example.torrent' });
+ *     await torrent.done;
+ * } finally {
+ *     client.close();
+ * }
+ */
 export declare class Client {
     private readonly config;
     private readonly peerId;
+    private readonly dhtNodeId;
+    private readonly dht?;
+    private readonly torrents;
+    private closed;
+    /**
+     * Build a client with optional defaults that apply to every download.
+     *
+     * The constructor is cheap: it generates a peer id and a DHT node id but does not
+     * open any sockets. The default DHT instance opens its UDP socket lazily on the
+     * first lookup.
+     *
+     * @param config - Defaults applied to downloads started by this client.
+     */
     constructor(config?: ClientConfig);
+    /**
+     * Start downloading a torrent and return a {@link Torrent} that emits progress events.
+     *
+     * The returned promise settles once the client has parsed metadata, discovered peers,
+     * opened the peer pool, and started the download manager. The actual download runs
+     * in the background — `await torrent.done` or listen for the `done` event to wait
+     * for it to finish.
+     *
+     * Tracker failures are non-fatal: if no tracker returns peers, DHT lookup is attempted
+     * when DHT is enabled. With DHT disabled, the download continues with whatever peers
+     * were found provided `minConnections` is `0`.
+     *
+     * @param input - Torrent source: a `.torrent` file path/bytes, a magnet URI, or already-parsed `meta`.
+     * @param options - Per-download overrides for {@link ClientConfig}, plus `announcePort` and `onChangeState`.
+     * @returns A {@link Torrent} whose `done` promise settles when the download finishes or fails.
+     * @throws {ClientError} When the client is closed, the input is unsupported, or file selection is invalid.
+     */
     download(input: DownloadInput, options?: DownloadOptions): Promise<Torrent>;
+    /**
+     * Parse a `.torrent` file or magnet URI and return its metadata without starting a download.
+     *
+     * Useful for showing the file list, computing total size, or letting the user pick
+     * a subset of files before calling {@link Client.download}. For magnet links this
+     * method fetches the info dictionary from a peer using the `ut_metadata` extension,
+     * so it may discover and warm DHT state that a later `download({ meta })` call reuses.
+     *
+     * @param input - Either `{ torrentFile }` (path/bytes/ArrayBuffer) or `{ magnet }` (URI string).
+     * @param options - Optional overrides. `timeout` caps the per-peer metadata fetch for magnets.
+     * @returns Parsed torrent metadata, including computed info hash.
+     * @throws {ClientError} When the client is closed or no input is provided.
+     * @throws {TorrentParseError} When the torrent file or magnet info dictionary cannot be parsed.
+     * @throws {MagnetParseError} When the magnet URI is invalid or no peer returned metadata.
+     */
     inspect(input: InspectInput, options?: {
         timeout?: number;
     }): Promise<TorrentMetadata>;
+    /**
+     * Stop the client, close every active torrent, and release the DHT socket.
+     *
+     * Idempotent — calling close more than once is a no-op. After close, every other
+     * method throws {@link ClientError} with code `CLIENT_CLOSED`.
+     */
+    close(): void;
+    private discoverPeers;
     private trackPeers;
+    private trackTorrent;
+    private assertOpen;
 }
+/**
+ * Per-download overrides passed to {@link Client.download}.
+ *
+ * Every field except `announcePort` and `onChangeState` overrides the matching field
+ * in {@link ClientConfig} for this download only.
+ */
 export type DownloadOptions = {
+    /** Port sent to trackers in announce requests. Defaults to 6881. */
     announcePort?: number;
+    /** Restrict the download to specific files. Selectable by `'a/b.txt'` string or `['a','b.txt']` array. */
     files?: TorrentFileSelection;
+    /** Override {@link ClientConfig.maxInFlightRequestsPerPeer} for this download. */
     maxInFlightRequestsPerPeer?: number;
+    /** Override {@link ClientConfig.maxConnecting} for this download. */
     maxConnecting?: number;
+    /** Override {@link ClientConfig.minConnections} for this download. */
     minConnections?: number;
+    /** Called with each setup phase before download starts. See {@link DownloadState}. */
     onChangeState?: (state: DownloadState) => unknown;
+    /** Override {@link ClientConfig.outputDirectory} for this download. */
     outputDirectory?: string;
+    /** Override {@link ClientConfig.peerConnectTimeoutMs} for this download. */
     peerConnectTimeoutMs?: number;
+    /** Override {@link ClientConfig.progressEvents} for this download. */
     progressEvents?: DownloadProgressEventMode;
+    /** Override {@link ClientConfig.requestTimeoutMs} for this download. */
     requestTimeoutMs?: number;
+    /** Reserved for future seeding support. Currently only `false` is supported. */
     seed?: false;
+    /** Override {@link ClientConfig.speedSampleIntervalMs} for this download. */
     speedSampleIntervalMs?: number;
+    /** Override {@link ClientConfig.targetConnections} for this download. */
     targetConnections?: number;
+    /** Override {@link ClientConfig.trackerTimeoutMs} for this download. */
     trackerTimeoutMs?: number;
 };
+/** Supported torrent file sources. */
 export type TorrentFileInput = string | Uint8Array | ArrayBuffer;
+/**
+ * @internal
+ */
 export declare const readTorrentFile: (input: unknown) => Promise<Uint8Array>;
 export { Client as TorrentClient };

package/dist/client.error.d.ts

@@ -1,8 +1,19 @@
 import { BunTorrentError } from './utils/errors';
+/** Error codes set on {@link ClientError.code}. */
 export declare enum ClientErrorCode {
+    /** {@link Client.download} or {@link Client.inspect} called after {@link Client.close}. */
+    CLOSED = "CLIENT_CLOSED",
+    /** `files` option referenced paths that do not exist in the torrent. */
     INVALID_FILE_SELECTION = "CLIENT_INVALID_FILE_SELECTION",
+    /** Torrent file input was neither a string path, `Uint8Array`, nor `ArrayBuffer`. */
     UNSUPPORTED_TORRENT_FILE_INPUT = "CLIENT_UNSUPPORTED_TORRENT_FILE_INPUT"
 }
+/**
+ * Errors thrown directly by {@link Client}. See {@link ClientErrorCode}.
+ *
+ * Errors from underlying subsystems (parser, tracker, peer pool, DHT) are thrown as
+ * their own classes — this one only wraps client-level failures.
+ */
 export declare class ClientError extends BunTorrentError {
     constructor(code: ClientErrorCode, message: string);
 }

package/dist/client.error.js

@@ -1,9 +1,20 @@
 import { BunTorrentError } from './utils/errors';
+/** Error codes set on {@link ClientError.code}. */
 export var ClientErrorCode;
 (function (ClientErrorCode) {
+    /** {@link Client.download} or {@link Client.inspect} called after {@link Client.close}. */
+    ClientErrorCode["CLOSED"] = "CLIENT_CLOSED";
+    /** `files` option referenced paths that do not exist in the torrent. */
     ClientErrorCode["INVALID_FILE_SELECTION"] = "CLIENT_INVALID_FILE_SELECTION";
+    /** Torrent file input was neither a string path, `Uint8Array`, nor `ArrayBuffer`. */
     ClientErrorCode["UNSUPPORTED_TORRENT_FILE_INPUT"] = "CLIENT_UNSUPPORTED_TORRENT_FILE_INPUT";
 })(ClientErrorCode || (ClientErrorCode = {}));
+/**
+ * Errors thrown directly by {@link Client}. See {@link ClientErrorCode}.
+ *
+ * Errors from underlying subsystems (parser, tracker, peer pool, DHT) are thrown as
+ * their own classes — this one only wraps client-level failures.
+ */
 export class ClientError extends BunTorrentError {
     constructor(code, message) {
         super(message, code);

package/dist/client.error.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.error.js","sourceRoot":"","sources":["../src/client.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,CAAN,IAAY,eAGX;AAHD,WAAY,eAAe;IACvB,2EAAwD,CAAA;IACxD,2FAAwE,CAAA;AAC5E,CAAC,EAHW,eAAe,KAAf,eAAe,QAG1B;AAED,MAAM,OAAO,WAAY,SAAQ,eAAe;IAC5C,YAAY,IAAqB,EAAE,OAAe;QAC9C,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;CACJ"}
+{"version":3,"file":"client.error.js","sourceRoot":"","sources":["../src/client.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,mDAAmD;AACnD,MAAM,CAAN,IAAY,eAOX;AAPD,WAAY,eAAe;IACvB,2FAA2F;IAC3F,2CAAwB,CAAA;IACxB,wEAAwE;IACxE,2EAAwD,CAAA;IACxD,qFAAqF;IACrF,2FAAwE,CAAA;AAC5E,CAAC,EAPW,eAAe,KAAf,eAAe,QAO1B;AAED;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,eAAe;IAC5C,YAAY,IAAqB,EAAE,OAAe;QAC9C,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;CACJ"}