bun-torrent 0.0.1-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikola Nedeljkovic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# bun-torrent

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "bun-torrent",
+    "version": "0.0.1-beta",
+    "type": "module",
+    "module": "src/index.ts",
+    "license": "MIT",
+    "description": "A minimal Bun-native BitTorrent download-only client.",
+    "keywords": [
+        "bun",
+        "bittorrent",
+        "torrent",
+        "download",
+        "typescript"
+    ],
+    "scripts": {
+        "test": "bun test",
+        "typecheck": "tsc --noEmit",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "format": "prettier . --write",
+        "format:check": "prettier . --check",
+        "check": "bun run typecheck && bun run lint && bun run format:check && bun test",
+        "app": "bun src/app.ts"
+    },
+    "engines": {
+        "bun": ">=1.3.0"
+    },
+    "files": [
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "exports": {
+        ".": {
+            "types": "./src/index.ts",
+            "default": "./src/index.ts"
+        }
+    },
+    "sideEffects": false,
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@types/bun": "latest",
+        "eslint": "^10.3.0",
+        "globals": "^17.6.0",
+        "prettier": "3.8.3",
+        "typescript": "^5",
+        "typescript-eslint": "^8.59.3"
+    }
+}

package/src/app.ts

@@ -0,0 +1,65 @@
+import { bytesToHex } from '@utils/buffers';
+import type { TorrentMetadata } from '@torrent/index';
+import { Client } from './client';
+
+type InspectSummary = {
+    announce?: string;
+    announceList: string[][];
+    infoHash: string;
+    name: string;
+    pieceLength: number;
+    piecesTotal: number;
+    length: number;
+    files: Array<{
+        path: string;
+        length: number;
+        offset: number;
+    }>;
+    filesTotal: number;
+};
+
+const summarizeTorrent = (metadata: TorrentMetadata): InspectSummary => ({
+    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 inspectStdin = async (): Promise<void> => {
+    const input = new Uint8Array(await Bun.stdin.arrayBuffer());
+
+    if (input.byteLength === 0) {
+        console.error('Usage: bun src/app.ts < file.torrent');
+        process.exitCode = 1;
+        return;
+    }
+
+    try {
+        const client = new Client();
+        const metadata = await client.inspect({ torrentFile: input });
+        console.log(JSON.stringify(summarizeTorrent(metadata), null, 2));
+    } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+};
+
+if (import.meta.main) {
+    const command = Bun.argv[2];
+
+    if (command === 'inspect') {
+        await inspectStdin();
+    } else {
+        console.error('Usage: bun src/app.ts inspect < file.torrent');
+        process.exitCode = 1;
+    }
+}

package/src/client.error.ts

@@ -0,0 +1,12 @@
+import { BunTorrentError } from '@utils/errors';
+
+export enum ClientErrorCode {
+    INVALID_FILE_SELECTION = 'CLIENT_INVALID_FILE_SELECTION',
+    UNSUPPORTED_TORRENT_FILE_INPUT = 'CLIENT_UNSUPPORTED_TORRENT_FILE_INPUT',
+}
+
+export class ClientError extends BunTorrentError {
+    constructor(code: ClientErrorCode, message: string) {
+        super(message, code);
+    }
+}

package/src/client.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from 'bun:test';
+
+import { encodeBencode, toBValue } from '@torrent/index';
+import { Client, DEFAULT_CLIENT_CONFIG } from './client';
+import { ClientError, ClientErrorCode } from './client.error';
+
+const makeTorrent = ({ announce }: { announce?: string } = {}): Uint8Array => {
+    const root: {
+        announce?: string;
+        info: {
+            length: number;
+            name: string;
+            'piece length': number;
+            pieces: Uint8Array;
+        };
+    } = {
+        info: {
+            length: 12345,
+            name: 'file.bin',
+            'piece length': 16384,
+            pieces: new Uint8Array(20),
+        },
+    };
+
+    if (announce !== undefined) root.announce = announce;
+
+    return encodeBencode(toBValue(root));
+};
+
+describe('Client.inspect', () => {
+    test('inspects torrent metadata from Uint8Array input', async () => {
+        const client = new Client();
+        const metadata = await client.inspect({
+            torrentFile: makeTorrent({ announce: 'https://tracker.test/announce' }),
+        });
+
+        expect(metadata.name).toBe('file.bin');
+        expect(metadata.length).toBe(12345);
+        expect(metadata.files).toEqual([{ path: ['file.bin'], length: 12345, offset: 0 }]);
+    });
+
+    test('inspects torrent metadata from ArrayBuffer input', async () => {
+        const client = new Client();
+        const torrent = makeTorrent({ announce: 'https://tracker.test/announce' });
+        const arrayBuffer = torrent.buffer.slice(
+            torrent.byteOffset,
+            torrent.byteOffset + torrent.byteLength,
+        ) as ArrayBuffer;
+        const metadata = await client.inspect({ torrentFile: arrayBuffer });
+
+        expect(metadata.name).toBe('file.bin');
+        expect(metadata.pieces).toHaveLength(1);
+    });
+
+    test('inspects torrent metadata from file path input', async () => {
+        const path = '/private/tmp/bun-torrent-client-inspect.torrent';
+        await Bun.write(path, makeTorrent({ announce: 'https://tracker.test/announce' }));
+
+        const client = new Client();
+        const metadata = await client.inspect({ torrentFile: path });
+
+        expect(metadata.name).toBe('file.bin');
+        expect(metadata.announce).toBe('https://tracker.test/announce');
+    });
+
+    test('rejects unsupported torrent file input with a client error', async () => {
+        const client = new Client();
+
+        expect(
+            client.inspect({ torrentFile: null as unknown as Uint8Array }),
+        ).rejects.toMatchObject({
+            code: ClientErrorCode.UNSUPPORTED_TORRENT_FILE_INPUT,
+        });
+        expect(
+            client.inspect({ torrentFile: null as unknown as Uint8Array }),
+        ).rejects.toBeInstanceOf(ClientError);
+    });
+});
+
+describe('Client.download', () => {
+    test('exposes default download configuration', () => {
+        expect(DEFAULT_CLIENT_CONFIG).toEqual({
+            maxInFlightRequestsPerPeer: 20,
+            progressEvents: 'piece',
+            requestTimeoutMs: 15_000,
+            speedSampleIntervalMs: 500,
+        });
+    });
+
+    test('returns an empty torrent instead of rejecting when no trackers are available', async () => {
+        const states: string[] = [];
+        const client = new Client();
+
+        const torrent = await client.download(
+            { torrentFile: makeTorrent() },
+            { onChangeState: (state) => states.push(state) },
+        );
+
+        expect(states).toEqual(['parsing', 'tracking', 'connecting', 'downloading']);
+        expect(torrent.stats).toMatchObject({
+            peers: 0,
+            connections: 0,
+            failedConnections: 0,
+        });
+        await torrent.done;
+    });
+
+    test('rejects unknown selected files', async () => {
+        const client = new Client();
+
+        await expect(
+            client.download({ torrentFile: makeTorrent() }, { files: ['missing.bin'] }),
+        ).rejects.toMatchObject({
+            code: ClientErrorCode.INVALID_FILE_SELECTION,
+        });
+    });
+});

package/src/client.ts

@@ -0,0 +1,185 @@
+import { createPeerId } from '@peer/peer-id';
+import { openPeerPool } from '@peer/pool';
+import { DownloadManager, type DownloadProgressEventMode } from '@torrent/download';
+import { parseTorrent } from '@torrent/parser/';
+import { Torrent } from '@torrent/session/index';
+import type { TorrentMetadata } from '@torrent/types';
+import { ClientError, ClientErrorCode } from './client.error';
+import { trackPeers, TrackerError, TrackerErrorCode } from './tracker';
+import type { TorrentFileSelection } from '@torrent/file-selection';
+import { getUnknownSelectedFiles, normalizeTorrentFileSelection } from '@torrent/file-selection';
+
+export enum DownloadState {
+    PARSING = 'parsing',
+    TRACKING = 'tracking',
+    CONNECTING = 'connecting',
+    DOWNLOADING = 'downloading',
+}
+
+export type ClientConfig = {
+    files?: TorrentFileSelection;
+    maxInFlightRequestsPerPeer?: number;
+    outputDirectory?: string;
+    progressEvents?: DownloadProgressEventMode;
+    requestTimeoutMs?: number;
+    speedSampleIntervalMs?: number;
+};
+
+export const DEFAULT_CLIENT_CONFIG = {
+    maxInFlightRequestsPerPeer: 20,
+    progressEvents: 'piece',
+    requestTimeoutMs: 15_000,
+    speedSampleIntervalMs: 500,
+} as const satisfies Required<
+    Pick<
+        ClientConfig,
+        | 'maxInFlightRequestsPerPeer'
+        | 'progressEvents'
+        | 'requestTimeoutMs'
+        | 'speedSampleIntervalMs'
+    >
+>;
+
+export class Client {
+    private readonly peerId: Uint8Array;
+
+    constructor(private readonly config: ClientConfig = {}) {
+        this.peerId = createPeerId();
+    }
+
+    public async download(
+        input: {
+            torrentFile: string | Uint8Array | ArrayBuffer;
+        },
+        options: DownloadOptions = {},
+    ): Promise<Torrent> {
+        options.onChangeState?.(DownloadState.PARSING);
+        const meta = await this.inspect(input);
+        const downloadConfig = resolveDownloadConfig(this.config, options);
+        assertValidFileSelection(meta, downloadConfig.files);
+
+        options.onChangeState?.(DownloadState.TRACKING);
+        const peers = await this.trackPeers(meta, options);
+
+        options.onChangeState?.(DownloadState.CONNECTING);
+        const pool = await openPeerPool(peers, {
+            infoHash: meta.infoHash,
+            peerId: this.peerId,
+            targetConnections: 20,
+            totalPieces: meta.pieces.length,
+            minConnections: options.minConnections ?? 0,
+            maxConnecting: 30,
+            timeoutMs: 5_000,
+        });
+
+        options.onChangeState?.(DownloadState.DOWNLOADING);
+        return new Torrent(
+            meta,
+            pool,
+            new DownloadManager({
+                metadata: meta,
+                files: downloadConfig.files,
+                outputDirectory: downloadConfig.outputDirectory,
+                peerPool: pool,
+                maxInFlightRequestsPerPeer: downloadConfig.maxInFlightRequestsPerPeer,
+                progressEvents: downloadConfig.progressEvents,
+                requestTimeoutMs: downloadConfig.requestTimeoutMs,
+                speedSampleIntervalMs: downloadConfig.speedSampleIntervalMs,
+            }),
+            normalizeTorrentFileSelection(downloadConfig.files),
+        );
+    }
+
+    public async inspect(input: {
+        torrentFile: string | Uint8Array | ArrayBuffer;
+    }): Promise<TorrentMetadata> {
+        const bytes = await readTorrentFile(input.torrentFile);
+        return parseTorrent(bytes);
+    }
+
+    private async trackPeers(meta: TorrentMetadata, options: DownloadOptions): Promise<PeerInfo[]> {
+        try {
+            return await trackPeers({
+                meta,
+                peerId: this.peerId,
+                announcePort: options.announcePort,
+                timeoutMs: 5_000,
+            });
+        } catch (error) {
+            if (isNonFatalTrackerError(error)) return [];
+            throw error;
+        }
+    }
+}
+
+export type DownloadOptions = {
+    announcePort?: number;
+    files?: TorrentFileSelection;
+    maxInFlightRequestsPerPeer?: number;
+    minConnections?: number;
+    onChangeState?: (state: DownloadState) => unknown;
+    outputDirectory?: string;
+    progressEvents?: DownloadProgressEventMode;
+    requestTimeoutMs?: number;
+    speedSampleIntervalMs?: number;
+};
+
+type ResolvedDownloadConfig = Required<ClientConfig>;
+
+type PeerInfo = Awaited<ReturnType<typeof trackPeers>>[number];
+
+const isNonFatalTrackerError = (error: unknown): error is TrackerError =>
+    error instanceof TrackerError &&
+    (error.code === TrackerErrorCode.ANNOUNCE_FAILED ||
+        error.code === TrackerErrorCode.NO_PEERS ||
+        error.code === TrackerErrorCode.NO_SUPPORTED_TRACKERS);
+
+const resolveDownloadConfig = (
+    config: ClientConfig,
+    options: DownloadOptions,
+): ResolvedDownloadConfig => ({
+    files: options.files ?? config.files ?? null,
+    maxInFlightRequestsPerPeer:
+        options.maxInFlightRequestsPerPeer ??
+        config.maxInFlightRequestsPerPeer ??
+        DEFAULT_CLIENT_CONFIG.maxInFlightRequestsPerPeer,
+    outputDirectory: options.outputDirectory ?? config.outputDirectory ?? process.cwd(),
+    progressEvents:
+        options.progressEvents ?? config.progressEvents ?? DEFAULT_CLIENT_CONFIG.progressEvents,
+    requestTimeoutMs:
+        options.requestTimeoutMs ??
+        config.requestTimeoutMs ??
+        DEFAULT_CLIENT_CONFIG.requestTimeoutMs,
+    speedSampleIntervalMs:
+        options.speedSampleIntervalMs ??
+        config.speedSampleIntervalMs ??
+        DEFAULT_CLIENT_CONFIG.speedSampleIntervalMs,
+});
+
+const assertValidFileSelection = (
+    metadata: TorrentMetadata,
+    files: TorrentFileSelection | undefined,
+): void => {
+    const unknownFiles = getUnknownSelectedFiles(metadata, files);
+    if (unknownFiles.length === 0) return;
+
+    throw new ClientError(
+        ClientErrorCode.INVALID_FILE_SELECTION,
+        `Unknown torrent file selection: ${unknownFiles.join(', ')}`,
+    );
+};
+
+export type TorrentFileInput = string | Uint8Array | ArrayBuffer;
+
+export const readTorrentFile = async (input: TorrentFileInput): Promise<Uint8Array> => {
+    if (typeof input === 'string') return await Bun.file(input).bytes();
+    if (input instanceof Uint8Array) return input;
+    if (input instanceof ArrayBuffer) return new Uint8Array(input);
+
+    throw new ClientError(
+        ClientErrorCode.UNSUPPORTED_TORRENT_FILE_INPUT,
+        'Unsupported torrent file input',
+    );
+};
+
+export { Client as TorrentClient };

package/src/index.test.ts

@@ -0,0 +1,7 @@
+import { expect, test } from 'bun:test';
+
+import * as api from './index';
+
+test('public entrypoint loads', () => {
+    expect(api).toBeDefined();
+});

package/src/index.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2026 Nikola Nedeljkovic
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './client';
+export { ClientError, ClientErrorCode } from './client.error';
+
+export {
+    BencodeDecodeError,
+    BencodeDecodeErrorCode,
+    BencodeEncodeError,
+    BencodeEncodeErrorCode,
+    computeInfoHash,
+    decodeBencode,
+    encodeBencode,
+    parseTorrent,
+    Torrent,
+    TorrentState,
+    toBValue,
+    TorrentParseError,
+    TorrentParseErrorCode,
+    type TorrentFileSelection,
+    type TorrentMetadata,
+} from '@torrent/index';
+export {
+    connectToPeers,
+    createPeerId,
+    decodeHandshake,
+    decodePeerMessage,
+    encodePeerMessage,
+    encodeHandshake,
+    HandshakeErrorCode,
+    PeerMessageError,
+    PeerMessageErrorCode,
+    PeerMessageId,
+    PeerHandshakeError,
+    PeerPoolError,
+    PeerPoolErrorCode,
+    PeerPool,
+    PeerSession,
+    PeerSessionError,
+    PeerSessionErrorCode,
+    openPeerPool,
+    type PeerHandshake,
+} from '@peer/index';
+export { TrackerError, TrackerErrorCode } from './tracker';
+export type {
+    BitfieldMessage,
+    CancelMessage,
+    ChokeMessage,
+    HaveMessage,
+    InterestedMessage,
+    KeepAliveMessage,
+    NotInterestedMessage,
+    PeerMessage,
+    PieceMessage,
+    RequestMessage,
+    UnchokeMessage,
+    PeerConnectionSession,
+    PeerPoolOptions,
+    PeerSessionConnectOptions,
+} from '@peer/index';
+
+export { BunTorrentError } from '@utils/errors';
+export type {
+    BBytes,
+    BDict,
+    BInteger,
+    BList,
+    BValue,
+    BencodeInput,
+    TorrentFiles,
+    TorrentStats,
+    TorrentStateChange,
+} from '@torrent/index';

package/src/peer/__tests__/peer-id.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from 'bun:test';
+
+import { PEER_ID_LENGTH, PEER_ID_PREFIX } from '../consts';
+import { createPeerId } from '../peer-id';
+
+const textDecoder = new TextDecoder();
+
+describe('createPeerId', () => {
+    test('creates a 20-byte peer id', () => {
+        expect(createPeerId().byteLength).toBe(PEER_ID_LENGTH);
+    });
+
+    test('uses the bun-torrent peer id prefix', () => {
+        expect(textDecoder.decode(createPeerId()).startsWith(PEER_ID_PREFIX)).toBe(true);
+    });
+
+    test('uses an alphanumeric suffix', () => {
+        const peerId = textDecoder.decode(createPeerId());
+        const suffix = peerId.slice(PEER_ID_PREFIX.length);
+
+        expect(suffix).toMatch(/^[A-Za-z0-9]+$/);
+        expect(suffix.length).toBe(PEER_ID_LENGTH - PEER_ID_PREFIX.length);
+    });
+});

package/src/peer/availability.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from 'bun:test';
+
+import { createPeerPieceAvailability, PeerPieceAvailability } from './availability';
+
+describe('PeerPieceAvailability', () => {
+    test('starts with no pieces when no bitfield is provided', () => {
+        const availability = new PeerPieceAvailability(3);
+
+        expect(availability.hasPiece(0)).toBe(false);
+        expect(availability.hasPiece(1)).toBe(false);
+        expect(availability.hasPiece(2)).toBe(false);
+        expect(availability.toPieceIndexes()).toEqual([]);
+    });
+
+    test('reads peer bitfields using most-significant-bit ordering', () => {
+        const availability = new PeerPieceAvailability(10, {
+            bitfield: new Uint8Array([0b1010_0001, 0b1000_0000]),
+        });
+
+        expect(availability.toPieceIndexes()).toEqual([0, 2, 7, 8]);
+        expect(availability.hasPiece(9)).toBe(false);
+    });
+
+    test('ignores spare bits beyond totalPieces', () => {
+        const availability = createPeerPieceAvailability(3, new Uint8Array([0xff]));
+
+        expect(availability.toPieceIndexes()).toEqual([0, 1, 2]);
+        expect(availability.hasPiece(3)).toBe(false);
+    });
+
+    test('marks pieces from have messages', () => {
+        const availability = new PeerPieceAvailability(4);
+
+        availability.markHave(2);
+        availability.markHave(10);
+        availability.markHave(-1);
+
+        expect(availability.toPieceIndexes()).toEqual([2]);
+    });
+
+    test('replaces availability from a new bitfield', () => {
+        const availability = new PeerPieceAvailability(4, {
+            bitfield: new Uint8Array([0b1000_0000]),
+        });
+
+        availability.setBitfield(new Uint8Array([0b0101_0000]));
+
+        expect(availability.toPieceIndexes()).toEqual([1, 3]);
+    });
+});