bun-torrent 0.0.1-beta

package/src/torrent/parser/index.ts

@@ -0,0 +1,197 @@
+import { decodeBencode } from '../bencode';
+import { fail, readText, readInteger, readBytes } from './helpers';
+import { computeInfoHash } from './info-hash';
+import { TorrentParseErrorCode } from './parser.error';
+import type { BDict, BValue } from '../bencode/types';
+import type { TorrentFile, TorrentMetadata } from '../types';
+
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+
+export const parseTorrent = (input: Uint8Array): TorrentMetadata => {
+    const decoded = decodeBencode(input);
+    if (!(decoded instanceof Map)) {
+        return fail(
+            TorrentParseErrorCode.ROOT_NOT_DICT,
+            'Torrent root must be a dictionary',
+            'root',
+        );
+    }
+
+    const root = decoded;
+    const infoValue = root.get('info');
+    if (infoValue === undefined) {
+        return fail(TorrentParseErrorCode.INFO_MISSING, 'Missing torrent info dictionary', 'info');
+    }
+    if (!(infoValue instanceof Map)) {
+        return fail(
+            TorrentParseErrorCode.INFO_NOT_DICT,
+            'Torrent info must be a dictionary',
+            'info',
+        );
+    }
+
+    const info = infoValue;
+
+    const name = readText(info, 'name');
+    const pieceLength = readInteger(info, 'piece length');
+    const piecesBytes = readBytes(info, 'pieces');
+    const files = readFiles(info, name);
+    const length = files.reduce((total, file) => total + file.length, 0);
+
+    return {
+        announce: root.has('announce') ? readText(root, 'announce') : undefined,
+        announceList: readAnnounceList(root),
+        infoHash: computeInfoHash(info),
+        name,
+        pieceLength,
+        pieces: splitPieces(piecesBytes),
+        length,
+        files,
+    };
+};
+
+const readFiles = (info: BDict, name: string): TorrentFile[] => {
+    const filesValue = info.get('files');
+    if (filesValue === undefined) {
+        const length = readInteger(info, 'length');
+        return [{ path: [name], length, offset: 0 }];
+    }
+
+    if (!Array.isArray(filesValue)) {
+        return fail(TorrentParseErrorCode.FIELD_INVALID, 'Expected files to be a list', 'files');
+    }
+
+    const files: TorrentFile[] = [];
+    let offset = 0;
+
+    for (let index = 0; index < filesValue.length; index++) {
+        const fileValue = filesValue[index]!;
+        if (!(fileValue instanceof Map)) {
+            return fail(
+                TorrentParseErrorCode.FIELD_INVALID,
+                'Expected file entry to be a dictionary',
+                `files[${index}]`,
+            );
+        }
+
+        const length = readFileLength(fileValue, index);
+        const path = readFilePath(fileValue, index);
+
+        files.push({ path, length, offset });
+        offset += length;
+    }
+
+    return files;
+};
+
+const readFileLength = (file: BDict, fileIndex: number): number => {
+    const value = file.get('length');
+    if (value === undefined) {
+        return fail(
+            TorrentParseErrorCode.FIELD_MISSING,
+            `Missing field: files[${fileIndex}].length`,
+            `files[${fileIndex}].length`,
+        );
+    }
+    if (typeof value !== 'number') {
+        return fail(
+            TorrentParseErrorCode.FIELD_INVALID,
+            `Expected integer: files[${fileIndex}].length`,
+            `files[${fileIndex}].length`,
+        );
+    }
+
+    return value;
+};
+
+const readFilePath = (file: BDict, fileIndex: number): string[] => {
+    const value = file.get('path');
+    if (value === undefined) {
+        return fail(
+            TorrentParseErrorCode.FIELD_MISSING,
+            `Missing field: files[${fileIndex}].path`,
+            `files[${fileIndex}].path`,
+        );
+    }
+    if (!Array.isArray(value) || value.length === 0) {
+        return fail(
+            TorrentParseErrorCode.FILE_PATH_INVALID,
+            'Expected file path to be a non-empty list',
+            `files[${fileIndex}].path`,
+        );
+    }
+
+    return value.map((segment, segmentIndex) => {
+        if (!(segment instanceof Uint8Array)) {
+            return fail(
+                TorrentParseErrorCode.FILE_PATH_INVALID,
+                'Expected file path segment to be bytes',
+                `files[${fileIndex}].path[${segmentIndex}]`,
+            );
+        }
+
+        const text = textDecoder.decode(segment);
+        if (text.length === 0 || text === '.' || text === '..' || text.includes('/')) {
+            return fail(
+                TorrentParseErrorCode.FILE_PATH_INVALID,
+                'Invalid file path segment',
+                `files[${fileIndex}].path[${segmentIndex}]`,
+            );
+        }
+
+        return text;
+    });
+};
+
+const readAnnounceList = (root: BDict): string[][] => {
+    const value = root.get('announce-list');
+    if (value === undefined) return [];
+
+    if (!Array.isArray(value)) {
+        return fail(
+            TorrentParseErrorCode.FIELD_INVALID,
+            'Expected announce-list to be a list',
+            'announce-list',
+        );
+    }
+
+    return value.map((tier, tierIndex) => readAnnounceTier(tier, tierIndex));
+};
+
+const readAnnounceTier = (value: BValue, tierIndex: number): string[] => {
+    if (!Array.isArray(value)) {
+        return fail(
+            TorrentParseErrorCode.FIELD_INVALID,
+            'Expected announce-list tier to be a list',
+            `announce-list[${tierIndex}]`,
+        );
+    }
+
+    return value.map((tracker, trackerIndex) => {
+        if (!(tracker instanceof Uint8Array)) {
+            return fail(
+                TorrentParseErrorCode.FIELD_INVALID,
+                'Expected announce-list tracker to be bytes',
+                `announce-list[${tierIndex}][${trackerIndex}]`,
+            );
+        }
+
+        return textDecoder.decode(tracker);
+    });
+};
+
+const SHA1_HASH_LENGTH = 20;
+
+const splitPieces = (pieces: Uint8Array): Uint8Array[] => {
+    if (pieces.byteLength === 0 || pieces.byteLength % SHA1_HASH_LENGTH !== 0) {
+        fail(TorrentParseErrorCode.PIECES_INVALID, 'Invalid pieces field', 'pieces');
+    }
+
+    const hashes: Uint8Array[] = [];
+
+    for (let offset = 0; offset < pieces.byteLength; offset += SHA1_HASH_LENGTH) {
+        hashes.push(pieces.subarray(offset, offset + SHA1_HASH_LENGTH));
+    }
+
+    return hashes;
+};

package/src/torrent/parser/info-hash.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test';
+
+import { bytesToHex } from '@utils/buffers';
+import { toBValue } from '../bencode';
+import type { BDict, BValue } from '../bencode/types';
+import { computeInfoHash } from './info-hash';
+
+describe('computeInfoHash', () => {
+    test('hashes the canonical bencoded info dictionary', () => {
+        const info = toBValue({
+            length: 12345,
+            name: 'file.bin',
+            'piece length': 16384,
+            pieces: new Uint8Array([0x00, 0xff, 0x69, 0x65]),
+        }) as BDict;
+
+        const hashed = 'c3982cffb55c2a39ac33477abbd4932316df786c';
+
+        expect(bytesToHex(computeInfoHash(info))).toBe(hashed);
+    });
+
+    test('is stable regardless of dictionary insertion order', () => {
+        const pieces = new Uint8Array([0x00, 0xff, 0x69, 0x65]);
+        const first = new Map<string, BValue>([
+            ['name', new TextEncoder().encode('file.bin')],
+            ['length', 12345],
+            ['piece length', 16384],
+            ['pieces', pieces],
+        ]) as BDict;
+        const second = new Map<string, BValue>([
+            ['pieces', pieces],
+            ['piece length', 16384],
+            ['length', 12345],
+            ['name', new TextEncoder().encode('file.bin')],
+        ]) as BDict;
+
+        expect(bytesToHex(computeInfoHash(first))).toBe(bytesToHex(computeInfoHash(second)));
+    });
+});

package/src/torrent/parser/info-hash.ts

@@ -0,0 +1,7 @@
+import { sha1 } from '@utils/sha1';
+import { encodeBencode } from '../bencode';
+import type { BDict } from '../bencode/types';
+
+export const computeInfoHash = (info: BDict): Uint8Array => {
+    return sha1(encodeBencode(info));
+};

package/src/torrent/parser/parser.error.ts

@@ -0,0 +1,21 @@
+import { BunTorrentError } from '@utils/errors';
+
+export enum TorrentParseErrorCode {
+    ROOT_NOT_DICT = 'TORRENT_ROOT_NOT_DICT',
+    INFO_MISSING = 'TORRENT_INFO_MISSING',
+    INFO_NOT_DICT = 'TORRENT_INFO_NOT_DICT',
+    FIELD_MISSING = 'TORRENT_FIELD_MISSING',
+    FIELD_INVALID = 'TORRENT_FIELD_INVALID',
+    FILE_PATH_INVALID = 'TORRENT_FILE_PATH_INVALID',
+    PIECES_INVALID = 'TORRENT_PIECES_INVALID',
+}
+
+export class TorrentParseError extends BunTorrentError {
+    constructor(
+        code: TorrentParseErrorCode,
+        message: string,
+        public readonly field?: string,
+    ) {
+        super(message, code);
+    }
+}

package/src/torrent/parser/parser.test.ts

@@ -0,0 +1,286 @@
+import { describe, expect, test } from 'bun:test';
+
+import { BunTorrentError } from '@utils/errors';
+import { bytesToHex } from '@utils/buffers';
+import { encodeBencode, toBValue } from '../bencode';
+import { TorrentParseError, TorrentParseErrorCode } from './parser.error';
+import { parseTorrent } from './index';
+
+const textEncoder = new TextEncoder();
+
+const bytes = (value: string): Uint8Array => textEncoder.encode(value);
+
+const makePieces = (count: number): Uint8Array => {
+    const pieces = new Uint8Array(count * 20);
+
+    for (let i = 0; i < pieces.byteLength; i++) {
+        pieces[i] = i;
+    }
+
+    return pieces;
+};
+
+const makeTorrent = ({
+    info: infoOverrides = {},
+    root: rootOverrides = {},
+}: {
+    info?: Record<string, unknown>;
+    root?: Record<string, unknown>;
+} = {}): Uint8Array => {
+    const info = Object.fromEntries(
+        Object.entries({
+            length: 12345,
+            name: 'file.bin',
+            'piece length': 16384,
+            pieces: makePieces(2),
+            ...infoOverrides,
+        }).filter(([, value]) => value !== undefined),
+    );
+
+    return encodeBencode(
+        toBValue(
+            Object.fromEntries(
+                Object.entries({
+                    announce: 'https://tracker.test/announce',
+                    info,
+                    ...rootOverrides,
+                }).filter(([, value]) => value !== undefined),
+            ),
+        ),
+    );
+};
+
+const expectParseError = (input: Uint8Array, code: TorrentParseErrorCode, field?: string): void => {
+    try {
+        parseTorrent(input);
+        throw new Error('Expected parseTorrent to throw');
+    } catch (error) {
+        expect(error).toBeInstanceOf(TorrentParseError);
+        expect(error).toBeInstanceOf(BunTorrentError);
+        expect((error as TorrentParseError).code).toBe(code);
+
+        if (field !== undefined) {
+            expect((error as TorrentParseError).field).toBe(field);
+        }
+    }
+};
+
+describe('parseTorrent', () => {
+    test('parses single-file torrent metadata', () => {
+        const metadata = parseTorrent(makeTorrent());
+
+        expect(metadata.announce).toBe('https://tracker.test/announce');
+        expect(metadata.announceList).toEqual([]);
+        expect(metadata.name).toBe('file.bin');
+        expect(metadata.length).toBe(12345);
+        expect(metadata.pieceLength).toBe(16384);
+        expect(metadata.pieces).toHaveLength(2);
+        expect([...metadata.pieces[0]!]).toEqual([...makePieces(1)]);
+        expect([...metadata.pieces[1]!]).toEqual([...makePieces(2).subarray(20, 40)]);
+        expect(metadata.files).toEqual([{ path: ['file.bin'], length: 12345, offset: 0 }]);
+        expect(metadata.infoHash.byteLength).toBe(20);
+        expect(bytesToHex(metadata.infoHash)).toBe('a6de37ba09e404285c68421a31e3320ae9758501');
+    });
+
+    test('parses multi-file torrent metadata', () => {
+        const metadata = parseTorrent(
+            makeTorrent({
+                info: {
+                    name: 'folder',
+                    length: undefined,
+                    files: [
+                        {
+                            length: 100,
+                            path: ['a.txt'],
+                        },
+                        {
+                            length: 250,
+                            path: ['nested', 'b.bin'],
+                        },
+                    ],
+                },
+            }),
+        );
+
+        expect(metadata.name).toBe('folder');
+        expect(metadata.length).toBe(350);
+        expect(metadata.files).toEqual([
+            { path: ['a.txt'], length: 100, offset: 0 },
+            { path: ['nested', 'b.bin'], length: 250, offset: 100 },
+        ]);
+    });
+
+    test('parses announce-list tiers', () => {
+        const metadata = parseTorrent(
+            makeTorrent({
+                root: {
+                    'announce-list': [
+                        ['https://tracker-a.test/announce'],
+                        ['https://tracker-b.test/announce', 'https://tracker-c.test/announce'],
+                    ],
+                },
+            }),
+        );
+
+        expect(metadata.announceList).toEqual([
+            ['https://tracker-a.test/announce'],
+            ['https://tracker-b.test/announce', 'https://tracker-c.test/announce'],
+        ]);
+    });
+
+    test('allows torrents without announce', () => {
+        const input = encodeBencode(
+            toBValue({
+                info: {
+                    length: 12345,
+                    name: 'file.bin',
+                    'piece length': 16384,
+                    pieces: makePieces(1),
+                },
+            }),
+        );
+
+        expect(parseTorrent(input).announce).toBeUndefined();
+    });
+
+    test('rejects non-dictionary roots', () => {
+        expectParseError(encodeBencode(1), TorrentParseErrorCode.ROOT_NOT_DICT, 'root');
+    });
+
+    test('rejects missing info dictionary', () => {
+        expectParseError(
+            encodeBencode(toBValue({ announce: 'https://tracker.test/announce' })),
+            TorrentParseErrorCode.INFO_MISSING,
+            'info',
+        );
+    });
+
+    test('rejects non-dictionary info values', () => {
+        expectParseError(
+            encodeBencode(toBValue({ info: 'file.bin' })),
+            TorrentParseErrorCode.INFO_NOT_DICT,
+            'info',
+        );
+    });
+
+    test('rejects missing required info fields', () => {
+        expectParseError(
+            makeTorrent({ info: { name: undefined } }),
+            TorrentParseErrorCode.FIELD_MISSING,
+            'name',
+        );
+    });
+
+    test('rejects invalid required info field types', () => {
+        expectParseError(
+            makeTorrent({ info: { length: bytes('12345') } }),
+            TorrentParseErrorCode.FIELD_INVALID,
+            'length',
+        );
+    });
+
+    test('rejects pieces values that are not made of 20-byte SHA-1 hashes', () => {
+        expectParseError(
+            makeTorrent({ info: { pieces: new Uint8Array(21) } }),
+            TorrentParseErrorCode.PIECES_INVALID,
+            'pieces',
+        );
+        expectParseError(
+            makeTorrent({ info: { pieces: new Uint8Array() } }),
+            TorrentParseErrorCode.PIECES_INVALID,
+            'pieces',
+        );
+    });
+
+    test('rejects invalid multi-file entries', () => {
+        expectParseError(
+            makeTorrent({
+                info: {
+                    length: undefined,
+                    files: ['file.bin'],
+                },
+            }),
+            TorrentParseErrorCode.FIELD_INVALID,
+            'files[0]',
+        );
+
+        expectParseError(
+            makeTorrent({
+                info: {
+                    length: undefined,
+                    files: [
+                        {
+                            path: ['file.bin'],
+                        },
+                    ],
+                },
+            }),
+            TorrentParseErrorCode.FIELD_MISSING,
+            'files[0].length',
+        );
+
+        expectParseError(
+            makeTorrent({
+                info: {
+                    length: undefined,
+                    files: [
+                        {
+                            length: 123,
+                            path: [],
+                        },
+                    ],
+                },
+            }),
+            TorrentParseErrorCode.FILE_PATH_INVALID,
+            'files[0].path',
+        );
+
+        expectParseError(
+            makeTorrent({
+                info: {
+                    length: undefined,
+                    files: [
+                        {
+                            length: 123,
+                            path: ['..'],
+                        },
+                    ],
+                },
+            }),
+            TorrentParseErrorCode.FILE_PATH_INVALID,
+            'files[0].path[0]',
+        );
+    });
+
+    test('rejects invalid announce-list shape', () => {
+        expectParseError(
+            makeTorrent({
+                root: {
+                    'announce-list': 'https://tracker.test/announce',
+                },
+            }),
+            TorrentParseErrorCode.FIELD_INVALID,
+            'announce-list',
+        );
+
+        expectParseError(
+            makeTorrent({
+                root: {
+                    'announce-list': ['https://tracker.test/announce'],
+                },
+            }),
+            TorrentParseErrorCode.FIELD_INVALID,
+            'announce-list[0]',
+        );
+
+        expectParseError(
+            makeTorrent({
+                root: {
+                    'announce-list': [[123]],
+                },
+            }),
+            TorrentParseErrorCode.FIELD_INVALID,
+            'announce-list[0][0]',
+        );
+    });
+});