bun-torrent 0.0.1-beta

package/src/torrent/pieces/utils.ts

@@ -0,0 +1,85 @@
+import type { TorrentMetadata } from '@torrent/types';
+import type { PieceBlock, PieceBlockRequest } from './types';
+import { PiecePlannerError, PiecePlannerErrorCode } from './planner.error';
+
+export const DEFAULT_BLOCK_LENGTH = 16 * 1024;
+
+/**
+ * Return the byte length of a piece, including the usually shorter final piece.
+ *
+ * @param metadata - Parsed torrent metadata.
+ * @param pieceIndex - Zero-based piece index.
+ * @returns The byte length for the requested piece.
+ * @throws {PiecePlannerError} When `pieceIndex` is outside the torrent piece range.
+ */
+export const getPieceLength = (metadata: TorrentMetadata, pieceIndex: number): number => {
+    if (!Number.isInteger(pieceIndex) || pieceIndex < 0 || pieceIndex >= metadata.pieces.length) {
+        throw new PiecePlannerError(
+            PiecePlannerErrorCode.INVALID_PIECE_INDEX,
+            `Unknown piece index: ${pieceIndex}`,
+            pieceIndex,
+        );
+    }
+
+    if (pieceIndex === metadata.pieces.length - 1)
+        return metadata.length - pieceIndex * metadata.pieceLength;
+    return metadata.pieceLength;
+};
+
+/**
+ * Split one piece into protocol request messages with a fixed maximum block size.
+ *
+ * @param pieceIndex - Zero-based piece index.
+ * @param pieceLength - Total byte length of the piece being split.
+ * @param blockLength - Maximum bytes per request. Defaults to `DEFAULT_BLOCK_LENGTH`.
+ * @returns Request messages that cover the piece in order.
+ * @throws {PiecePlannerError} When `pieceLength` or `blockLength` is not a positive integer.
+ */
+export const splitPieceIntoRequests = ({
+    pieceIndex,
+    pieceLength,
+    blockLength = DEFAULT_BLOCK_LENGTH,
+}: {
+    pieceIndex: number;
+    pieceLength: number;
+    blockLength?: number;
+}): PieceBlockRequest[] => {
+    if (!Number.isInteger(pieceLength) || pieceLength <= 0) {
+        throw new PiecePlannerError(
+            PiecePlannerErrorCode.INVALID_PIECE_LENGTH,
+            `Piece length must be a positive integer: ${pieceLength}`,
+            pieceIndex,
+        );
+    }
+
+    if (!Number.isInteger(blockLength) || blockLength <= 0) {
+        throw new PiecePlannerError(
+            PiecePlannerErrorCode.INVALID_BLOCK_LENGTH,
+            `Block length must be a positive integer: ${blockLength}`,
+            pieceIndex,
+        );
+    }
+
+    const n = Math.ceil(pieceLength / blockLength);
+    const blocks = new Array<PieceBlockRequest>(n);
+    for (let i = 0; i < n; i++)
+        blocks[i] = {
+            type: 'request',
+            pieceIndex,
+            offset: blockLength * i,
+            length: i === n - 1 ? pieceLength - blockLength * i : blockLength,
+        };
+    return blocks;
+};
+
+/**
+ * Check whether a received block exactly satisfies a pending request.
+ *
+ * @param block - Received peer piece message.
+ * @param request - Request the block is expected to satisfy.
+ * @returns True when piece index, offset, and byte length all match.
+ */
+export const isValidBlockForRequest = (block: PieceBlock, request: PieceBlockRequest): boolean =>
+    block.pieceIndex === request.pieceIndex &&
+    block.offset === request.offset &&
+    block.block.byteLength === request.length;

package/src/torrent/pieces/validation.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'bun:test';
+
+import { sha1 } from '@utils/sha1';
+import { validatePiece } from './validation';
+
+describe('validatePiece', () => {
+    test('accepts a piece when its SHA-1 hash matches', () => {
+        const data = new Uint8Array([1, 2, 3, 4]);
+        const result = validatePiece({
+            pieceIndex: 2,
+            data,
+            expectedHash: sha1(data),
+        });
+
+        expect(result).toMatchObject({
+            pieceIndex: 2,
+            valid: true,
+        });
+        expect(result.actualHash).toEqual(result.expectedHash);
+    });
+
+    test('rejects a piece when its SHA-1 hash does not match', () => {
+        const result = validatePiece({
+            pieceIndex: 1,
+            data: new Uint8Array([1, 2, 3, 4]),
+            expectedHash: sha1(new Uint8Array([4, 3, 2, 1])),
+        });
+
+        expect(result.valid).toBe(false);
+        expect(result.actualHash).not.toEqual(result.expectedHash);
+    });
+});

package/src/torrent/pieces/validation.ts

@@ -0,0 +1,27 @@
+import { compareBytes } from '@utils/buffers';
+import { sha1 } from '@utils/sha1';
+import type { PieceCompletion } from './types';
+
+export type PieceValidationResult = {
+    pieceIndex: number;
+    actualHash: Uint8Array;
+    expectedHash: Uint8Array;
+    valid: boolean;
+};
+
+/**
+ * Validate an assembled piece against the expected torrent metadata hash.
+ *
+ * @param piece - Completed piece returned by the planner.
+ * @returns Validation result containing both actual and expected SHA-1 hashes.
+ */
+export const validatePiece = (piece: PieceCompletion): PieceValidationResult => {
+    const actualHash = sha1(piece.data);
+
+    return {
+        pieceIndex: piece.pieceIndex,
+        actualHash,
+        expectedHash: piece.expectedHash,
+        valid: compareBytes(actualHash, piece.expectedHash) === 0,
+    };
+};

package/src/torrent/session/index.ts

@@ -0,0 +1,195 @@
+import type { DownloadProgress, DownloadProgressListener } from '../download';
+import type { TorrentFile, TorrentMetadata } from '../types';
+
+export type TorrentStats = {
+    peers: number;
+    connections: number;
+    connecting: number;
+    connectionAttempts: number;
+    failedConnections: number;
+    targetConnections: number;
+};
+
+export enum TorrentState {
+    DOWNLOADING = 'downloading',
+    COMPLETED = 'completed',
+    FAILED = 'failed',
+    CLOSED = 'closed',
+}
+
+export type TorrentStateChange = {
+    previous: TorrentState;
+    state: TorrentState;
+};
+
+export type TorrentEventMap = {
+    close: [];
+    done: [];
+    error: [error: unknown];
+    peer: [session: unknown];
+    progress: [progress: DownloadProgress];
+    state: [change: TorrentStateChange];
+};
+
+export type TorrentEventName = keyof TorrentEventMap;
+
+export type TorrentEventListener<TEvent extends TorrentEventName> = (
+    ...args: TorrentEventMap[TEvent]
+) => void;
+
+export type TorrentFiles = {
+    included: TorrentFile[];
+    excluded: TorrentFile[];
+};
+
+type TorrentPeerPool = {
+    readonly done: Promise<unknown>;
+    readonly totalPeers: number;
+    readonly size: number;
+    readonly connecting: number;
+    readonly attempted: number;
+    readonly failed: number;
+    readonly targetConnections: number;
+    onSession(callback: (session: unknown) => void): () => void;
+    close(): void;
+};
+
+type TorrentDownloadManager = {
+    readonly done: Promise<void>;
+    readonly progress: DownloadProgress;
+    onProgress(listener: DownloadProgressListener): () => void;
+    start(): void;
+    close(): void;
+};
+
+export class Torrent {
+    public readonly done: Promise<void>;
+    private readonly listeners = new Map<TorrentEventName, Set<(...args: unknown[]) => void>>();
+    private currentState = TorrentState.DOWNLOADING;
+    private lastError: unknown;
+
+    public constructor(
+        public readonly metadata: TorrentMetadata,
+        private readonly peerPool: TorrentPeerPool,
+        private readonly downloadManager?: TorrentDownloadManager,
+        private readonly selectedFiles?: Set<string> | null,
+    ) {
+        this.downloadManager?.onProgress((progress) => this.emit('progress', progress));
+        this.downloadManager?.start();
+        this.done = downloadManager?.done ?? peerPool.done.then(() => undefined);
+        void this.done.then(
+            () => {
+                if (this.currentState === TorrentState.CLOSED) return;
+
+                this.setState(TorrentState.COMPLETED);
+                this.emit('done');
+            },
+            (error) => {
+                if (this.currentState === TorrentState.CLOSED) return;
+
+                this.lastError = error;
+                this.setState(TorrentState.FAILED);
+                this.emit('error', error);
+            },
+        );
+    }
+
+    public get state(): TorrentState {
+        return this.currentState;
+    }
+
+    public get error(): unknown {
+        return this.lastError;
+    }
+
+    public get stats(): TorrentStats {
+        return {
+            peers: this.peerPool.totalPeers,
+            connections: this.peerPool.size,
+            connecting: this.peerPool.connecting,
+            connectionAttempts: this.peerPool.attempted,
+            failedConnections: this.peerPool.failed,
+            targetConnections: this.peerPool.targetConnections,
+        };
+    }
+
+    public get progress(): DownloadProgress {
+        return (
+            this.downloadManager?.progress ?? {
+                totalBytes: this.metadata.length,
+                receivedBytes: 0,
+                downloadedBytes: 0,
+                totalPieces: this.metadata.pieces.length,
+                completedPieces: 0,
+                percent: this.metadata.length === 0 ? 1 : 0,
+                speedBytesPerSecond: 0,
+                speed: '0.0 Bps',
+            }
+        );
+    }
+
+    public get files(): TorrentFiles {
+        if (!this.selectedFiles) return { included: this.metadata.files, excluded: [] };
+
+        const included = this.metadata.files.filter((f) =>
+            this.selectedFiles?.has(f.path.join('/')),
+        );
+        const excluded = this.metadata.files.filter(
+            (f) => !this.selectedFiles?.has(f.path.join('/')),
+        );
+        return { included, excluded };
+    }
+
+    public on<TEvent extends TorrentEventName>(
+        event: TEvent,
+        listener: TorrentEventListener<TEvent>,
+    ): () => void {
+        if (event === 'peer') {
+            return this.peerPool.onSession((session) => {
+                (listener as TorrentEventListener<'peer'>)(session);
+            });
+        }
+
+        const listeners = this.getListeners(event);
+        listeners.add(listener as (...args: unknown[]) => void);
+
+        return () => {
+            listeners.delete(listener as (...args: unknown[]) => void);
+        };
+    }
+
+    public close(): void {
+        if (this.currentState === TorrentState.CLOSED) return;
+
+        this.downloadManager?.close();
+        this.peerPool.close();
+        this.setState(TorrentState.CLOSED);
+        this.emit('close');
+    }
+
+    private setState(state: TorrentState): void {
+        if (this.currentState === state) return;
+
+        const previous = this.currentState;
+        this.currentState = state;
+        this.emit('state', { previous, state });
+    }
+
+    private emit<TEvent extends TorrentEventName>(
+        event: TEvent,
+        ...args: TorrentEventMap[TEvent]
+    ): void {
+        for (const listener of this.getListeners(event)) {
+            listener(...args);
+        }
+    }
+
+    private getListeners(event: TorrentEventName): Set<(...args: unknown[]) => void> {
+        const existing = this.listeners.get(event);
+        if (existing) return existing;
+
+        const listeners = new Set<(...args: unknown[]) => void>();
+        this.listeners.set(event, listeners);
+        return listeners;
+    }
+}

package/src/torrent/session/session.test.ts

@@ -0,0 +1,279 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Torrent, TorrentState } from '.';
+import type { DownloadProgress, DownloadProgressListener } from '../download';
+import type { TorrentMetadata } from '../types';
+
+describe('Torrent', () => {
+    test('returns live stats from the peer pool', () => {
+        const pool = new FakePeerPool();
+        const torrent = new Torrent(makeMetadata(), pool);
+
+        expect(torrent.stats).toEqual({
+            peers: 10,
+            connections: 1,
+            connecting: 2,
+            connectionAttempts: 3,
+            failedConnections: 4,
+            targetConnections: 5,
+        });
+
+        pool.size = 2;
+        pool.connecting = 1;
+
+        expect(torrent.stats.connections).toBe(2);
+        expect(torrent.stats.connecting).toBe(1);
+    });
+
+    test('closes the peer pool', () => {
+        const pool = new FakePeerPool();
+        const torrent = new Torrent(makeMetadata(), pool);
+
+        torrent.close();
+
+        expect(pool.closed).toBe(true);
+    });
+
+    test('starts and closes the download manager when provided', async () => {
+        const pool = new FakePeerPool();
+        const manager = new FakeDownloadManager();
+        const torrent = new Torrent(makeMetadata(), pool, manager);
+
+        expect(manager.started).toBe(true);
+        expect(torrent.done).toBe(manager.done);
+        expect(torrent.state).toBe(TorrentState.DOWNLOADING);
+
+        manager.resolve();
+        await expect(torrent.done).resolves.toBeUndefined();
+        expect(torrent.state).toBe(TorrentState.COMPLETED);
+
+        torrent.close();
+
+        expect(torrent.state).toBe(TorrentState.CLOSED);
+        expect(manager.closed).toBe(true);
+        expect(pool.closed).toBe(true);
+    });
+
+    test('emits peer, state, done, and close events', async () => {
+        const pool = new FakePeerPool();
+        const manager = new FakeDownloadManager();
+        const torrent = new Torrent(makeMetadata(), pool, manager);
+        const peers: unknown[] = [];
+        const states: string[] = [];
+        let done = false;
+        let closed = false;
+
+        torrent.on('peer', (session) => peers.push(session));
+        torrent.on('state', (change) => states.push(`${change.previous}->${change.state}`));
+        torrent.on('done', () => {
+            done = true;
+        });
+        torrent.on('close', () => {
+            closed = true;
+        });
+
+        const peer = {};
+        pool.addSession(peer);
+        manager.resolve();
+        await torrent.done;
+
+        torrent.close();
+
+        expect(peers).toEqual([peer]);
+        expect(states).toEqual(['downloading->completed', 'completed->closed']);
+        expect(done).toBe(true);
+        expect(closed).toBe(true);
+    });
+
+    test('emits errors when download fails', async () => {
+        const pool = new FakePeerPool();
+        const manager = new FakeDownloadManager();
+        const torrent = new Torrent(makeMetadata(), pool, manager);
+        const errors: unknown[] = [];
+
+        torrent.on('error', (error) => errors.push(error));
+
+        const error = new Error('download failed');
+        manager.reject(error);
+        await expect(torrent.done).rejects.toBe(error);
+
+        expect(torrent.state).toBe(TorrentState.FAILED);
+        expect(torrent.error).toBe(error);
+        expect(errors).toEqual([error]);
+    });
+
+    test('keeps closed state when close resolves the manager', async () => {
+        const pool = new FakePeerPool();
+        const manager = new FakeDownloadManager();
+        const torrent = new Torrent(makeMetadata(), pool, manager);
+        const states: string[] = [];
+
+        torrent.on('state', (change) => states.push(`${change.previous}->${change.state}`));
+        torrent.close();
+        await torrent.done;
+
+        expect(torrent.state).toBe(TorrentState.CLOSED);
+        expect(states).toEqual(['downloading->closed']);
+    });
+
+    test('returns and emits download progress', () => {
+        const pool = new FakePeerPool();
+        const manager = new FakeDownloadManager();
+        const torrent = new Torrent(makeMetadata(), pool, manager);
+        const events: DownloadProgress[] = [];
+
+        torrent.on('progress', (progress) => events.push(progress));
+
+        manager.progress = {
+            totalBytes: 16_384,
+            receivedBytes: 8_192,
+            downloadedBytes: 0,
+            totalPieces: 1,
+            completedPieces: 0,
+            percent: 0,
+            speedBytesPerSecond: 1_000,
+            speed: '1.0 KBps',
+        };
+        manager.emitProgress();
+
+        expect(torrent.progress).toEqual(manager.progress);
+        expect(events).toEqual([manager.progress]);
+    });
+
+    test('returns all files as included when no file selection is provided', () => {
+        const pool = new FakePeerPool();
+        const metadata = makeMultiFileMetadata();
+        const torrent = new Torrent(metadata, pool);
+
+        expect(torrent.files).toEqual({
+            included: metadata.files,
+            excluded: [],
+        });
+    });
+
+    test('splits selected files into included and excluded lists', () => {
+        const pool = new FakePeerPool();
+        const metadata = makeMultiFileMetadata();
+        const torrent = new Torrent(metadata, pool, undefined, new Set(['video.mp4']));
+
+        expect(torrent.files).toEqual({
+            included: [{ path: ['video.mp4'], length: 8, offset: 2 }],
+            excluded: [
+                { path: ['subtitle.srt'], length: 2, offset: 0 },
+                { path: ['poster.jpg'], length: 4, offset: 10 },
+            ],
+        });
+    });
+});
+
+class FakePeerPool {
+    public done = Promise.resolve([]);
+    public totalPeers = 10;
+    public size = 1;
+    public connecting = 2;
+    public attempted = 3;
+    public failed = 4;
+    public targetConnections = 5;
+    public closed = false;
+    private readonly sessions: unknown[] = [];
+    private readonly sessionListeners = new Set<(session: unknown) => void>();
+
+    public onSession(callback: (session: unknown) => void): () => void {
+        this.sessionListeners.add(callback);
+        for (const session of this.sessions) callback(session);
+
+        return () => {
+            this.sessionListeners.delete(callback);
+        };
+    }
+
+    public close(): void {
+        this.closed = true;
+    }
+
+    public addSession(session: unknown): void {
+        this.sessions.push(session);
+        for (const listener of this.sessionListeners) listener(session);
+    }
+}
+
+class FakeDownloadManager {
+    public started = false;
+    public closed = false;
+    public done: Promise<void>;
+    public progress: DownloadProgress = {
+        totalBytes: 16_384,
+        receivedBytes: 0,
+        downloadedBytes: 0,
+        totalPieces: 1,
+        completedPieces: 0,
+        percent: 0,
+        speedBytesPerSecond: 0,
+        speed: '0.0 Bps',
+    };
+    private readonly progressListeners = new Set<DownloadProgressListener>();
+    private resolveDone!: () => void;
+    private rejectDone!: (error: unknown) => void;
+
+    public constructor() {
+        this.done = new Promise((resolve, reject) => {
+            this.resolveDone = resolve;
+            this.rejectDone = reject;
+        });
+    }
+
+    public start(): void {
+        this.started = true;
+    }
+
+    public close(): void {
+        this.closed = true;
+        this.resolveDone();
+    }
+
+    public onProgress(listener: DownloadProgressListener): () => void {
+        this.progressListeners.add(listener);
+
+        return () => {
+            this.progressListeners.delete(listener);
+        };
+    }
+
+    public emitProgress(): void {
+        for (const listener of this.progressListeners) listener(this.progress);
+    }
+
+    public resolve(): void {
+        this.resolveDone();
+    }
+
+    public reject(error: unknown): void {
+        this.rejectDone(error);
+    }
+}
+
+const makeMetadata = (): TorrentMetadata => ({
+    announce: 'udp://tracker.test:80',
+    announceList: [],
+    infoHash: new Uint8Array(20),
+    name: 'file.bin',
+    pieceLength: 16_384,
+    pieces: [new Uint8Array(20)],
+    length: 16_384,
+    files: [{ path: ['file.bin'], length: 16_384, offset: 0 }],
+});
+
+const makeMultiFileMetadata = (): TorrentMetadata => ({
+    announce: 'udp://tracker.test:80',
+    announceList: [],
+    infoHash: new Uint8Array(20),
+    name: 'download',
+    pieceLength: 4,
+    pieces: [new Uint8Array(20), new Uint8Array(20), new Uint8Array(20), new Uint8Array(20)],
+    length: 14,
+    files: [
+        { path: ['subtitle.srt'], length: 2, offset: 0 },
+        { path: ['video.mp4'], length: 8, offset: 2 },
+        { path: ['poster.jpg'], length: 4, offset: 10 },
+    ],
+});