bun-torrent 0.0.1-beta

package/src/torrent/bencode/encoder.ts

@@ -0,0 +1,86 @@
+import { compareBytes, concatBytes } from '@utils/buffers';
+import { BencodeEncodeError, BencodeEncodeErrorCode } from './encoder.error';
+import { FLAG, type BValue } from './types';
+
+export const encodeBencode = (input: BValue): Uint8Array => {
+    const encoder = createEncoder({ input });
+    return encoder.encode();
+};
+
+const IDENTIFIERS = {
+    integer: new Uint8Array([FLAG.INTEGER]),
+    delimiter: new Uint8Array([FLAG.STR_DELIMITER]),
+    list: new Uint8Array([FLAG.LIST]),
+    dictionary: new Uint8Array([FLAG.DICTIONARY]),
+    end: new Uint8Array([FLAG.END]),
+} as const;
+
+const createEncoder = ({ input }: { input: BValue }) => {
+    const textEncoder = new TextEncoder('utf-8');
+    const buffer: Array<Uint8Array> = [];
+
+    const pushAscii = (value: string): void => {
+        buffer.push(textEncoder.encode(value));
+    };
+
+    const encodeInteger = (value: number): void => {
+        if (!Number.isInteger(value))
+            fail(BencodeEncodeErrorCode.INVALID_INTEGER, 'Bencode integer must be an integer');
+        if (!Number.isSafeInteger(value))
+            fail(BencodeEncodeErrorCode.UNSAFE_INTEGER, 'Bencode integer must be safe');
+        if (Object.is(value, -0))
+            fail(BencodeEncodeErrorCode.NEGATIVE_ZERO, 'Bencode integer cannot be -0');
+
+        buffer.push(IDENTIFIERS.integer);
+        pushAscii(String(value));
+        buffer.push(IDENTIFIERS.end);
+    };
+
+    const encodeBytes = (data: Uint8Array): void => {
+        pushAscii(String(data.byteLength));
+        buffer.push(IDENTIFIERS.delimiter, data);
+    };
+
+    const encodeList = (list: BValue[]): void => {
+        buffer.push(IDENTIFIERS.list);
+        for (const value of list) {
+            encodeValue(value);
+        }
+        buffer.push(IDENTIFIERS.end);
+    };
+
+    const encodeDictionary = (dict: Map<string, BValue>): void => {
+        buffer.push(IDENTIFIERS.dictionary);
+
+        const entries = [...dict.entries()].sort(([left], [right]) =>
+            compareBytes(textEncoder.encode(left), textEncoder.encode(right)),
+        );
+
+        for (const [key, value] of entries) {
+            encodeBytes(textEncoder.encode(key));
+            encodeValue(value);
+        }
+
+        buffer.push(IDENTIFIERS.end);
+    };
+
+    const encodeValue = (value: BValue): void => {
+        if (typeof value === 'number') return encodeInteger(value);
+        if (value instanceof Uint8Array) return encodeBytes(value);
+        if (Array.isArray(value)) return encodeList(value);
+        if (value instanceof Map) return encodeDictionary(value);
+
+        return fail(BencodeEncodeErrorCode.UNSUPPORTED_VALUE, 'Unsupported bencode value');
+    };
+
+    const encode = (): Uint8Array => {
+        encodeValue(input);
+        return concatBytes(buffer);
+    };
+
+    const fail = (code: BencodeEncodeErrorCode, message: string): never => {
+        throw new BencodeEncodeError(code, message);
+    };
+
+    return { encode };
+};

package/src/torrent/bencode/index.ts

@@ -0,0 +1,9 @@
+export { decodeBencode } from './decoder';
+export { encodeBencode } from './encoder';
+export { toBValue } from './utils';
+
+export { BencodeDecodeError, BencodeDecodeErrorCode } from './decoder.error';
+export { BencodeEncodeError, BencodeEncodeErrorCode } from './encoder.error';
+
+export type { BBytes, BDict, BInteger, BList, BValue } from './types';
+export type { BencodeInput } from './utils';

package/src/torrent/bencode/types.ts

@@ -0,0 +1,15 @@
+export type BValue = BBytes | BInteger | BList | BDict;
+
+export type BBytes = Uint8Array;
+export type BInteger = number;
+export type BList = BValue[];
+export type BDict = Map<string, BValue>;
+
+export enum FLAG {
+    INTEGER = 0x69,
+    MINUS = 0x2d,
+    LIST = 0x6c,
+    DICTIONARY = 0x64,
+    END = 0x65,
+    STR_DELIMITER = 0x3a,
+}

package/src/torrent/bencode/utils.ts

@@ -0,0 +1,17 @@
+import type { BValue } from './types';
+
+export type BencodeInput =
+    | number
+    | string
+    | Uint8Array
+    | BencodeInput[]
+    | { readonly [key: string]: BencodeInput };
+
+export const toBValue = (input: BencodeInput): BValue => {
+    if (typeof input === 'number') return input;
+    if (typeof input === 'string') return new TextEncoder('utf-8').encode(input);
+    if (input instanceof Uint8Array) return input;
+    if (Array.isArray(input)) return input.map(toBValue);
+
+    return new Map(Object.entries(input).map(([key, value]) => [key, toBValue(value)]));
+};

package/src/torrent/download/index.ts

@@ -0,0 +1,9 @@
+export { DownloadManager } from './manager';
+export type {
+    DownloadManagerOptions,
+    DownloadPeerPool,
+    DownloadPeerSession,
+    DownloadProgress,
+    DownloadProgressEventMode,
+    DownloadProgressListener,
+} from './manager';

package/src/torrent/download/manager.test.ts

@@ -0,0 +1,393 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { PeerMessage } from '@peer/messages';
+import { createPiecePlanner, type PieceAvailability, type PieceCompletion } from '../pieces';
+import type { TorrentMetadata } from '../types';
+import {
+    DownloadManager,
+    type DownloadManagerOptions,
+    type DownloadPeerPool,
+    type DownloadProgress,
+} from './manager';
+
+const makeMetadata = ({
+    length = 4,
+    pieceLength = 4,
+    pieces = 1,
+}: {
+    length?: number;
+    pieceLength?: number;
+    pieces?: number;
+} = {}): TorrentMetadata => ({
+    announceList: [],
+    infoHash: new Uint8Array(20),
+    name: 'file.bin',
+    pieceLength,
+    pieces: Array.from({ length: pieces }, (_, index) => new Uint8Array(20).fill(index)),
+    length,
+    files: [{ path: ['file.bin'], length, offset: 0 }],
+});
+
+class FakeAvailability implements PieceAvailability {
+    public constructor(private readonly pieces: Set<number>) {}
+
+    public hasPiece(pieceIndex: number): boolean {
+        return this.pieces.has(pieceIndex);
+    }
+}
+
+class FakePeer {
+    public sent: PeerMessage[] = [];
+    public peerAvailability: PieceAvailability;
+
+    private readonly messageListeners = new Set<(message: PeerMessage) => void>();
+    private readonly closeListeners = new Set<() => void>();
+
+    public constructor({
+        choked = true,
+        pieces = [0],
+    }: {
+        choked?: boolean;
+        pieces?: number[];
+    } = {}) {
+        this.choked = choked;
+        this.peerAvailability = new FakeAvailability(new Set(pieces));
+    }
+
+    public choked: boolean;
+
+    public onClose(callback: () => void): () => void {
+        this.closeListeners.add(callback);
+        return () => this.closeListeners.delete(callback);
+    }
+
+    public onMessage(callback: (message: PeerMessage) => void): () => void {
+        this.messageListeners.add(callback);
+        return () => this.messageListeners.delete(callback);
+    }
+
+    public sendMessage(message: PeerMessage): void {
+        this.sent.push(message);
+    }
+
+    public emit(message: PeerMessage): void {
+        if (message.type === 'choke') this.choked = true;
+        if (message.type === 'unchoke') this.choked = false;
+
+        for (const listener of this.messageListeners) listener(message);
+    }
+
+    public close(): void {
+        for (const listener of this.closeListeners) listener();
+    }
+}
+
+class FakePeerPool implements DownloadPeerPool<FakePeer> {
+    private readonly peers: FakePeer[] = [];
+    private readonly listeners = new Set<(peer: FakePeer) => void>();
+
+    public onSession(callback: (session: FakePeer) => void): () => void {
+        this.listeners.add(callback);
+        for (const peer of this.peers) callback(peer);
+
+        return () => {
+            this.listeners.delete(callback);
+        };
+    }
+
+    public add(peer: FakePeer): void {
+        this.peers.push(peer);
+        for (const listener of this.listeners) listener(peer);
+    }
+}
+
+type WriteValidatedPiece = NonNullable<DownloadManagerOptions<FakePeer>['writeValidatedPiece']>;
+
+const makeWriteValidated = ({
+    completions,
+    valid = true,
+}: {
+    completions?: PieceCompletion[];
+    valid?: boolean;
+} = {}): WriteValidatedPiece => {
+    return async (_metadata, piece) => {
+        completions?.push(piece);
+
+        return {
+            pieceIndex: piece.pieceIndex,
+            actualHash: new Uint8Array(20),
+            expectedHash: piece.expectedHash,
+            valid,
+        };
+    };
+};
+
+const nextTick = async (): Promise<void> => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+};
+
+const requestMessages = (peer: FakePeer): Extract<PeerMessage, { type: 'request' }>[] =>
+    peer.sent.filter((message): message is Extract<PeerMessage, { type: 'request' }> => {
+        return message.type === 'request';
+    });
+
+describe('DownloadManager', () => {
+    test('sends interested while choked when the peer has useful pieces', () => {
+        const pool = new FakePeerPool();
+        const manager = new DownloadManager({
+            metadata: makeMetadata(),
+            outputDirectory: '/tmp/download',
+            peerPool: pool,
+            writeValidatedPiece: makeWriteValidated(),
+        });
+        const peer = new FakePeer({ choked: true });
+
+        manager.start();
+        pool.add(peer);
+
+        expect(peer.sent).toEqual([{ type: 'interested' }]);
+    });
+
+    test('requests blocks from an unchoked peer and respects the in-flight limit', () => {
+        const pool = new FakePeerPool();
+        const manager = new DownloadManager({
+            metadata: makeMetadata({ length: 8, pieceLength: 4, pieces: 2 }),
+            outputDirectory: '/tmp/download',
+            peerPool: pool,
+            maxInFlightRequestsPerPeer: 2,
+            writeValidatedPiece: makeWriteValidated(),
+        });
+        const peer = new FakePeer({ choked: false, pieces: [0, 1] });
+
+        manager.start();
+        pool.add(peer);
+
+        expect(peer.sent[0]).toEqual({ type: 'interested' });
+        expect(requestMessages(peer)).toEqual([
+            { type: 'request', pieceIndex: 0, offset: 0, length: 4 },
+            { type: 'request', pieceIndex: 1, offset: 0, length: 4 },
+        ]);
+    });
+
+    test('writes completed pieces and resolves when the torrent is complete', async () => {
+        const completions: PieceCompletion[] = [];
+        const pool = new FakePeerPool();
+        const manager = new DownloadManager({
+            metadata: makeMetadata(),
+            outputDirectory: '/tmp/download',
+            peerPool: pool,
+            writeValidatedPiece: makeWriteValidated({ completions }),
+        });
+        const peer = new FakePeer({ choked: false });
+
+        manager.start();
+        pool.add(peer);
+        peer.emit({ type: 'piece', pieceIndex: 0, offset: 0, block: new Uint8Array([1, 2, 3, 4]) });
+
+        expect(manager.done).resolves.toBeUndefined();
+        expect(completions).toEqual([
+            {
+                pieceIndex: 0,
+                data: new Uint8Array([1, 2, 3, 4]),
+                expectedHash: new Uint8Array(20),
+            },
+        ]);
+    });
+
+    test('reports progress snapshots for completed pieces by default', async () => {
+        const progress: DownloadProgress[] = [];
+        const pool = new FakePeerPool();
+        const metadata = makeMetadata({ length: 4, pieceLength: 4, pieces: 1 });
+        const manager = new DownloadManager({
+            metadata,
+            outputDirectory: '/tmp/download',
+            peerPool: pool,
+            maxInFlightRequestsPerPeer: 2,
+            planner: createPiecePlanner(metadata, { blockLength: 2 }),
+            writeValidatedPiece: makeWriteValidated(),
+        });
+        const peer = new FakePeer({ choked: false });
+
+        manager.onProgress((snapshot) => progress.push(snapshot));
+        manager.start();
+        pool.add(peer);
+
+        peer.emit({ type: 'piece', pieceIndex: 0, offset: 0, block: new Uint8Array([1, 2]) });
+        expect(progress).toEqual([]);
+
+        peer.emit({ type: 'piece', pieceIndex: 0, offset: 2, block: new Uint8Array([3, 4]) });
+        await manager.done;
+
+        expect(progress).toEqual([
+            {
+                totalBytes: 4,
+                receivedBytes: 4,
+                downloadedBytes: 4,
+                totalPieces: 1,
+                completedPieces: 1,
+                percent: 1,
+                speedBytesPerSecond: 0,
+                speed: '0.0 Bps',
+            },
+        ]);
+    });
+
+    test('reports progress snapshots as blocks arrive when configured', async () => {
+        const progress: DownloadProgress[] = [];
+        const pool = new FakePeerPool();
+        const metadata = makeMetadata({ length: 4, pieceLength: 4, pieces: 1 });
+        const manager = new DownloadManager({
+            metadata,
+            outputDirectory: '/tmp/download',
+            peerPool: pool,
+            maxInFlightRequestsPerPeer: 2,
+            progressEvents: 'block',
+            planner: createPiecePlanner(metadata, { blockLength: 2 }),
+            writeValidatedPiece: makeWriteValidated(),
+        });
+        const peer = new FakePeer({ choked: false });
+
+        expect(manager.progress).toEqual({
+            totalBytes: 4,
+            receivedBytes: 0,
+            downloadedBytes: 0,
+            totalPieces: 1,
+            completedPieces: 0,
+            percent: 0,
+            speedBytesPerSecond: 0,
+            speed: '0.0 Bps',
+        });
+
+        manager.onProgress((snapshot) => progress.push(snapshot));
+        manager.start();
+        pool.add(peer);
+
+        peer.emit({ type: 'piece', pieceIndex: 0, offset: 0, block: new Uint8Array([1, 2]) });
+        peer.emit({ type: 'piece', pieceIndex: 0, offset: 2, block: new Uint8Array([3, 4]) });
+        await manager.done;
+
+        expect(progress).toEqual([
+            {
+                totalBytes: 4,
+                receivedBytes: 2,
+                downloadedBytes: 0,
+                totalPieces: 1,
+                completedPieces: 0,
+                percent: 0,
+                speedBytesPerSecond: 0,
+                speed: '0.0 Bps',
+            },
+            {
+                totalBytes: 4,
+                receivedBytes: 4,
+                downloadedBytes: 4,
+                totalPieces: 1,
+                completedPieces: 1,
+                percent: 1,
+                speedBytesPerSecond: 0,
+                speed: '0.0 Bps',
+            },
+        ]);
+    });
+
+    test('updates speed only after the sample interval passes', async () => {
+        const progress: DownloadProgress[] = [];
+        const pool = new FakePeerPool();
+        const metadata = makeMetadata({ length: 4, pieceLength: 4, pieces: 1 });
+        const manager = new DownloadManager({
+            metadata,
+            outputDirectory: '/tmp/download',
+            peerPool: pool,
+            maxInFlightRequestsPerPeer: 2,
+            progressEvents: 'block',
+            speedSampleIntervalMs: 1,
+            planner: createPiecePlanner(metadata, { blockLength: 2 }),
+            writeValidatedPiece: makeWriteValidated(),
+        });
+        const peer = new FakePeer({ choked: false });
+
+        manager.onProgress((snapshot) => progress.push(snapshot));
+        manager.start();
+        pool.add(peer);
+
+        peer.emit({ type: 'piece', pieceIndex: 0, offset: 0, block: new Uint8Array([1, 2]) });
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        peer.emit({ type: 'piece', pieceIndex: 0, offset: 2, block: new Uint8Array([3, 4]) });
+        await manager.done;
+
+        expect(progress[0]!.speedBytesPerSecond).toBe(0);
+        expect(progress[1]!.speedBytesPerSecond).toBeGreaterThan(0);
+        expect(progress[1]!.speed).not.toBe('0.0 Bps');
+    });
+
+    test('retries a piece when validation fails', async () => {
+        const pool = new FakePeerPool();
+        const manager = new DownloadManager({
+            metadata: makeMetadata(),
+            outputDirectory: '/tmp/download',
+            peerPool: pool,
+            writeValidatedPiece: makeWriteValidated({ valid: false }),
+        });
+        const peer = new FakePeer({ choked: false });
+
+        manager.start();
+        pool.add(peer);
+        peer.emit({ type: 'piece', pieceIndex: 0, offset: 0, block: new Uint8Array([1, 2, 3, 4]) });
+        await nextTick();
+
+        expect(requestMessages(peer)).toEqual([
+            { type: 'request', pieceIndex: 0, offset: 0, length: 4 },
+            { type: 'request', pieceIndex: 0, offset: 0, length: 4 },
+        ]);
+    });
+
+    test('returns pending peer requests to the planner when a peer closes', () => {
+        const pool = new FakePeerPool();
+        const manager = new DownloadManager({
+            metadata: makeMetadata({ length: 8, pieceLength: 4, pieces: 2 }),
+            outputDirectory: '/tmp/download',
+            peerPool: pool,
+            writeValidatedPiece: makeWriteValidated(),
+        });
+        const firstPeer = new FakePeer({ choked: false, pieces: [0] });
+        const secondPeer = new FakePeer({ choked: false, pieces: [0] });
+
+        manager.start();
+        pool.add(firstPeer);
+        firstPeer.close();
+        pool.add(secondPeer);
+
+        expect(requestMessages(firstPeer)).toEqual([
+            { type: 'request', pieceIndex: 0, offset: 0, length: 4 },
+        ]);
+        expect(requestMessages(secondPeer)).toEqual([
+            { type: 'request', pieceIndex: 0, offset: 0, length: 4 },
+        ]);
+    });
+
+    test('requeues timed-out requests to other peers first', async () => {
+        const pool = new FakePeerPool();
+        const manager = new DownloadManager({
+            metadata: makeMetadata({ length: 4, pieceLength: 4, pieces: 1 }),
+            outputDirectory: '/tmp/download',
+            peerPool: pool,
+            requestTimeoutMs: 50,
+            writeValidatedPiece: makeWriteValidated(),
+        });
+        const slowPeer = new FakePeer({ choked: false, pieces: [0] });
+        const nextPeer = new FakePeer({ choked: false, pieces: [0] });
+
+        manager.start();
+        pool.add(slowPeer);
+        pool.add(nextPeer);
+        await new Promise((resolve) => setTimeout(resolve, 60));
+
+        expect(requestMessages(slowPeer)).toEqual([
+            { type: 'request', pieceIndex: 0, offset: 0, length: 4 },
+        ]);
+        expect(requestMessages(nextPeer)).toEqual([
+            { type: 'request', pieceIndex: 0, offset: 0, length: 4 },
+        ]);
+        manager.close();
+    });
+});