bun-torrent 0.0.1-beta

package/src/torrent/storage/index.ts

@@ -0,0 +1,161 @@
+import type { TorrentMetadata } from '@torrent/types';
+import { mkdir, open } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import {
+    getPieceLength,
+    validatePiece,
+    type PieceCompletion,
+    type PieceValidationResult,
+} from '../pieces';
+import { getTorrentFilePathKey, normalizeTorrentFileSelection } from '../file-selection';
+import { TorrentStorageError, TorrentStorageErrorCode } from './storage.error';
+import type { FileWrite, WritePieceOptions } from './types';
+
+/**
+ * Map a completed piece to file write ranges in torrent file order.
+ *
+ * @param metadata - Parsed torrent metadata.
+ * @param pieceIndex - Completed piece index.
+ * @param data - Completed piece bytes.
+ * @returns File write ranges that cover the piece data.
+ * @throws {TorrentStorageError} When the piece index or piece length is invalid.
+ */
+export const planPieceWrites = (
+    metadata: TorrentMetadata,
+    pieceIndex: number,
+    data: Uint8Array,
+): FileWrite[] => {
+    const pieceLength = getStoragePieceLength(metadata, pieceIndex);
+    if (data.byteLength !== pieceLength) {
+        throw new TorrentStorageError(
+            TorrentStorageErrorCode.INVALID_PIECE_LENGTH,
+            `Piece ${pieceIndex} length mismatch: expected ${pieceLength}, received ${data.byteLength}`,
+            pieceIndex,
+        );
+    }
+
+    const pieceStart = pieceIndex * metadata.pieceLength;
+    const pieceEnd = pieceStart + data.byteLength;
+    const writes: FileWrite[] = [];
+
+    for (const file of metadata.files) {
+        const fileStart = file.offset;
+        const fileEnd = file.offset + file.length;
+        const start = Math.max(pieceStart, fileStart);
+        const end = Math.min(pieceEnd, fileEnd);
+
+        if (start >= end) continue;
+
+        writes.push({
+            path: file.path,
+            fileOffset: start - fileStart,
+            dataOffset: start - pieceStart,
+            length: end - start,
+        });
+    }
+
+    const plannedLength = writes.reduce((total, write) => total + write.length, 0);
+    if (plannedLength !== data.byteLength) {
+        throw new TorrentStorageError(
+            TorrentStorageErrorCode.INVALID_FILE_LAYOUT,
+            `Torrent file layout does not cover piece ${pieceIndex}`,
+            pieceIndex,
+        );
+    }
+
+    return writes;
+};
+
+/**
+ * Write a validated completed piece into its torrent files.
+ *
+ * @param metadata - Parsed torrent metadata.
+ * @param pieceIndex - Completed piece index.
+ * @param data - Validated piece bytes.
+ * @param options - Storage options including output directory.
+ * @throws {TorrentStorageError} When the piece or target file path is invalid.
+ */
+export const writePiece = async (
+    metadata: TorrentMetadata,
+    pieceIndex: number,
+    data: Uint8Array,
+    options: WritePieceOptions,
+): Promise<void> => {
+    const selectedFiles = normalizeTorrentFileSelection(options.files);
+    const writes = planPieceWrites(metadata, pieceIndex, data).filter(
+        (write) => !selectedFiles || selectedFiles.has(getTorrentFilePathKey(write.path)),
+    );
+
+    for (const write of writes) {
+        const path = resolveTorrentFilePath(options.outputDirectory, write.path);
+        await mkdir(dirname(path), { recursive: true });
+
+        const file = await open(path, 'a+');
+        try {
+            await file.write(
+                data.subarray(write.dataOffset, write.dataOffset + write.length),
+                0,
+                write.length,
+                write.fileOffset,
+            );
+        } finally {
+            await file.close();
+        }
+    }
+};
+
+/**
+ * Validate a completed piece and write it only when its SHA-1 hash matches.
+ *
+ * @param metadata - Parsed torrent metadata.
+ * @param piece - Completed piece returned by the planner.
+ * @param options - Storage options including output directory.
+ * @returns Piece validation result. Invalid pieces are not written to disk.
+ * @throws {TorrentStorageError} When storage planning or file writing fails for a valid piece.
+ */
+export const writeValidatedPiece = async (
+    metadata: TorrentMetadata,
+    piece: PieceCompletion,
+    options: WritePieceOptions,
+): Promise<PieceValidationResult> => {
+    const validation = validatePiece(piece);
+    if (!validation.valid) return validation;
+
+    await writePiece(metadata, piece.pieceIndex, piece.data, options);
+    return validation;
+};
+
+const getStoragePieceLength = (metadata: TorrentMetadata, pieceIndex: number): number => {
+    try {
+        return getPieceLength(metadata, pieceIndex);
+    } catch {
+        throw new TorrentStorageError(
+            TorrentStorageErrorCode.INVALID_PIECE_INDEX,
+            `Unknown piece index: ${pieceIndex}`,
+            pieceIndex,
+        );
+    }
+};
+
+const resolveTorrentFilePath = (outputDirectory: string, parts: string[]): string => {
+    if (
+        parts.some(
+            (part) =>
+                part === '' ||
+                part === '.' ||
+                part === '..' ||
+                part.includes('/') ||
+                part.includes('\\'),
+        )
+    ) {
+        throw new TorrentStorageError(
+            TorrentStorageErrorCode.INVALID_FILE_PATH,
+            `Invalid torrent file path: ${parts.join('/')}`,
+        );
+    }
+
+    return join(outputDirectory, ...parts);
+};
+
+export { TorrentStorageError, TorrentStorageErrorCode } from './storage.error';
+export type { FileWrite, WritePieceOptions } from './types';

package/src/torrent/storage/storage.error.ts

@@ -0,0 +1,18 @@
+import { BunTorrentError } from '@utils/errors';
+
+export enum TorrentStorageErrorCode {
+    INVALID_FILE_LAYOUT = 'TORRENT_STORAGE_INVALID_FILE_LAYOUT',
+    INVALID_PIECE_INDEX = 'TORRENT_STORAGE_INVALID_PIECE_INDEX',
+    INVALID_PIECE_LENGTH = 'TORRENT_STORAGE_INVALID_PIECE_LENGTH',
+    INVALID_FILE_PATH = 'TORRENT_STORAGE_INVALID_FILE_PATH',
+}
+
+export class TorrentStorageError extends BunTorrentError {
+    constructor(
+        code: TorrentStorageErrorCode,
+        message: string,
+        public readonly pieceIndex?: number,
+    ) {
+        super(message, code);
+    }
+}

package/src/torrent/storage/storage.test.ts

@@ -0,0 +1,326 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { TorrentMetadata } from '@torrent/types';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { sha1 } from '@utils/sha1';
+import {
+    planPieceWrites,
+    TorrentStorageError,
+    TorrentStorageErrorCode,
+    writePiece,
+    writeValidatedPiece,
+} from './index';
+
+const makeMetadata = ({
+    length,
+    pieceLength,
+    files,
+}: Pick<TorrentMetadata, 'length' | 'pieceLength' | 'files'>): TorrentMetadata => ({
+    announceList: [],
+    infoHash: new Uint8Array(20),
+    name: 'download',
+    pieceLength,
+    pieces: Array.from({ length: Math.ceil(length / pieceLength) }, () => new Uint8Array(20)),
+    length,
+    files,
+});
+
+const readBytes = async (path: string): Promise<number[]> => [...(await Bun.file(path).bytes())];
+
+describe('planPieceWrites', () => {
+    test('maps a single-file piece to one write', () => {
+        const metadata = makeMetadata({
+            length: 10,
+            pieceLength: 4,
+            files: [{ path: ['file.bin'], length: 10, offset: 0 }],
+        });
+
+        expect(planPieceWrites(metadata, 1, new Uint8Array([4, 5, 6, 7]))).toEqual([
+            { path: ['file.bin'], fileOffset: 4, dataOffset: 0, length: 4 },
+        ]);
+    });
+
+    test('splits a piece across multiple files', () => {
+        const metadata = makeMetadata({
+            length: 10,
+            pieceLength: 4,
+            files: [
+                { path: ['a.bin'], length: 6, offset: 0 },
+                { path: ['nested', 'b.bin'], length: 4, offset: 6 },
+            ],
+        });
+
+        expect(planPieceWrites(metadata, 1, new Uint8Array([4, 5, 6, 7]))).toEqual([
+            { path: ['a.bin'], fileOffset: 4, dataOffset: 0, length: 2 },
+            { path: ['nested', 'b.bin'], fileOffset: 0, dataOffset: 2, length: 2 },
+        ]);
+    });
+
+    test('maps the final shorter piece', () => {
+        const metadata = makeMetadata({
+            length: 10,
+            pieceLength: 4,
+            files: [{ path: ['file.bin'], length: 10, offset: 0 }],
+        });
+
+        expect(planPieceWrites(metadata, 2, new Uint8Array([8, 9]))).toEqual([
+            { path: ['file.bin'], fileOffset: 8, dataOffset: 0, length: 2 },
+        ]);
+    });
+
+    test('splits one piece across three files', () => {
+        const metadata = makeMetadata({
+            length: 12,
+            pieceLength: 6,
+            files: [
+                { path: ['a.bin'], length: 3, offset: 0 },
+                { path: ['b.bin'], length: 5, offset: 3 },
+                { path: ['c.bin'], length: 4, offset: 8 },
+            ],
+        });
+
+        expect(planPieceWrites(metadata, 1, new Uint8Array([6, 7, 8, 9, 10, 11]))).toEqual([
+            { path: ['b.bin'], fileOffset: 3, dataOffset: 0, length: 2 },
+            { path: ['c.bin'], fileOffset: 0, dataOffset: 2, length: 4 },
+        ]);
+    });
+
+    test('rejects invalid piece indexes and lengths', () => {
+        const metadata = makeMetadata({
+            length: 10,
+            pieceLength: 4,
+            files: [{ path: ['file.bin'], length: 10, offset: 0 }],
+        });
+
+        expect(() => planPieceWrites(metadata, 3, new Uint8Array())).toThrow(TorrentStorageError);
+        expect(() => planPieceWrites(metadata, 3, new Uint8Array())).toThrow(
+            'Unknown piece index: 3',
+        );
+
+        try {
+            planPieceWrites(metadata, 3, new Uint8Array());
+            throw new Error('Expected planPieceWrites to throw');
+        } catch (error) {
+            expect((error as TorrentStorageError).code).toBe(
+                TorrentStorageErrorCode.INVALID_PIECE_INDEX,
+            );
+        }
+
+        try {
+            planPieceWrites(metadata, 2, new Uint8Array([8]));
+            throw new Error('Expected planPieceWrites to throw');
+        } catch (error) {
+            expect((error as TorrentStorageError).code).toBe(
+                TorrentStorageErrorCode.INVALID_PIECE_LENGTH,
+            );
+        }
+    });
+
+    test('rejects file layouts that do not cover the whole piece', () => {
+        const metadata = makeMetadata({
+            length: 8,
+            pieceLength: 4,
+            files: [
+                { path: ['a.bin'], length: 2, offset: 0 },
+                { path: ['b.bin'], length: 2, offset: 6 },
+            ],
+        });
+
+        expect(() => planPieceWrites(metadata, 0, new Uint8Array([1, 2, 3, 4]))).toThrow(
+            TorrentStorageError,
+        );
+
+        try {
+            planPieceWrites(metadata, 0, new Uint8Array([1, 2, 3, 4]));
+            throw new Error('Expected planPieceWrites to throw');
+        } catch (error) {
+            expect((error as TorrentStorageError).code).toBe(
+                TorrentStorageErrorCode.INVALID_FILE_LAYOUT,
+            );
+        }
+    });
+
+    test('rejects overlapping file layouts for a piece', () => {
+        const metadata = makeMetadata({
+            length: 6,
+            pieceLength: 4,
+            files: [
+                { path: ['a.bin'], length: 4, offset: 0 },
+                { path: ['b.bin'], length: 4, offset: 2 },
+            ],
+        });
+
+        expect(() => planPieceWrites(metadata, 0, new Uint8Array([1, 2, 3, 4]))).toThrow(
+            TorrentStorageError,
+        );
+
+        try {
+            planPieceWrites(metadata, 0, new Uint8Array([1, 2, 3, 4]));
+            throw new Error('Expected planPieceWrites to throw');
+        } catch (error) {
+            expect((error as TorrentStorageError).code).toBe(
+                TorrentStorageErrorCode.INVALID_FILE_LAYOUT,
+            );
+        }
+    });
+});
+
+describe('writePiece', () => {
+    test('writes a piece to a single file at the correct offset', async () => {
+        const outputDirectory = await mkdtemp(join(tmpdir(), 'bun-torrent-storage-'));
+        const metadata = makeMetadata({
+            length: 8,
+            pieceLength: 4,
+            files: [{ path: ['file.bin'], length: 8, offset: 0 }],
+        });
+
+        await writePiece(metadata, 0, new Uint8Array([1, 2, 3, 4]), { outputDirectory });
+        await writePiece(metadata, 1, new Uint8Array([5, 6, 7, 8]), { outputDirectory });
+
+        expect(await readBytes(join(outputDirectory, 'file.bin'))).toEqual([
+            1, 2, 3, 4, 5, 6, 7, 8,
+        ]);
+    });
+
+    test('writes a piece across multiple files', async () => {
+        const outputDirectory = await mkdtemp(join(tmpdir(), 'bun-torrent-storage-'));
+        const metadata = makeMetadata({
+            length: 10,
+            pieceLength: 4,
+            files: [
+                { path: ['a.bin'], length: 6, offset: 0 },
+                { path: ['nested', 'b.bin'], length: 4, offset: 6 },
+            ],
+        });
+
+        await writePiece(metadata, 1, new Uint8Array([4, 5, 6, 7]), { outputDirectory });
+
+        expect(await readBytes(join(outputDirectory, 'a.bin'))).toEqual([0, 0, 0, 0, 4, 5]);
+        expect(await readBytes(join(outputDirectory, 'nested', 'b.bin'))).toEqual([6, 7]);
+    });
+
+    test('writes only selected files from a cross-file piece', async () => {
+        const outputDirectory = await mkdtemp(join(tmpdir(), 'bun-torrent-storage-'));
+        const metadata = makeMetadata({
+            length: 10,
+            pieceLength: 4,
+            files: [
+                { path: ['a.bin'], length: 6, offset: 0 },
+                { path: ['nested', 'b.bin'], length: 4, offset: 6 },
+            ],
+        });
+
+        await writePiece(metadata, 1, new Uint8Array([4, 5, 6, 7]), {
+            outputDirectory,
+            files: [['nested', 'b.bin']],
+        });
+
+        expect(await Bun.file(join(outputDirectory, 'a.bin')).exists()).toBe(false);
+        expect(await readBytes(join(outputDirectory, 'nested', 'b.bin'))).toEqual([6, 7]);
+    });
+
+    test('creates nested directories before writing', async () => {
+        const outputDirectory = await mkdtemp(join(tmpdir(), 'bun-torrent-storage-'));
+        const metadata = makeMetadata({
+            length: 4,
+            pieceLength: 4,
+            files: [{ path: ['deep', 'nested', 'file.bin'], length: 4, offset: 0 }],
+        });
+
+        await writePiece(metadata, 0, new Uint8Array([1, 2, 3, 4]), { outputDirectory });
+
+        expect(await readBytes(join(outputDirectory, 'deep', 'nested', 'file.bin'))).toEqual([
+            1, 2, 3, 4,
+        ]);
+    });
+
+    test('overwrites the same piece bytes at the same offset', async () => {
+        const outputDirectory = await mkdtemp(join(tmpdir(), 'bun-torrent-storage-'));
+        const metadata = makeMetadata({
+            length: 8,
+            pieceLength: 4,
+            files: [{ path: ['file.bin'], length: 8, offset: 0 }],
+        });
+        await writeFile(
+            join(outputDirectory, 'file.bin'),
+            new Uint8Array([0, 0, 0, 0, 9, 9, 9, 9]),
+        );
+
+        await writePiece(metadata, 1, new Uint8Array([5, 6, 7, 8]), { outputDirectory });
+        await writePiece(metadata, 1, new Uint8Array([8, 7, 6, 5]), { outputDirectory });
+
+        expect(await readBytes(join(outputDirectory, 'file.bin'))).toEqual([
+            0, 0, 0, 0, 8, 7, 6, 5,
+        ]);
+    });
+
+    test('rejects unsafe torrent file paths', async () => {
+        const outputDirectory = await mkdtemp(join(tmpdir(), 'bun-torrent-storage-'));
+        const unsafePaths = [
+            ['..', 'evil.bin'],
+            ['.', 'evil.bin'],
+            ['', 'evil.bin'],
+            ['nested/evil.bin'],
+            ['nested\\evil.bin'],
+        ];
+
+        for (const path of unsafePaths) {
+            const metadata = makeMetadata({
+                length: 4,
+                pieceLength: 4,
+                files: [{ path, length: 4, offset: 0 }],
+            });
+
+            await expect(
+                writePiece(metadata, 0, new Uint8Array([1, 2, 3, 4]), { outputDirectory }),
+            ).rejects.toMatchObject({
+                code: TorrentStorageErrorCode.INVALID_FILE_PATH,
+            });
+        }
+    });
+});
+
+describe('writeValidatedPiece', () => {
+    test('writes a completed piece when its hash matches', async () => {
+        const outputDirectory = await mkdtemp(join(tmpdir(), 'bun-torrent-storage-'));
+        const data = new Uint8Array([1, 2, 3, 4]);
+        const metadata = makeMetadata({
+            length: 4,
+            pieceLength: 4,
+            files: [{ path: ['file.bin'], length: 4, offset: 0 }],
+        });
+
+        const result = await writeValidatedPiece(
+            metadata,
+            { pieceIndex: 0, data, expectedHash: sha1(data) },
+            { outputDirectory },
+        );
+
+        expect(result.valid).toBe(true);
+        expect(await readBytes(join(outputDirectory, 'file.bin'))).toEqual([1, 2, 3, 4]);
+    });
+
+    test('does not write a completed piece when its hash does not match', async () => {
+        const outputDirectory = await mkdtemp(join(tmpdir(), 'bun-torrent-storage-'));
+        const metadata = makeMetadata({
+            length: 4,
+            pieceLength: 4,
+            files: [{ path: ['file.bin'], length: 4, offset: 0 }],
+        });
+
+        const result = await writeValidatedPiece(
+            metadata,
+            {
+                pieceIndex: 0,
+                data: new Uint8Array([1, 2, 3, 4]),
+                expectedHash: sha1(new Uint8Array([4, 3, 2, 1])),
+            },
+            { outputDirectory },
+        );
+
+        expect(result.valid).toBe(false);
+        expect(await Bun.file(join(outputDirectory, 'file.bin')).exists()).toBe(false);
+    });
+});

package/src/torrent/storage/types.ts

@@ -0,0 +1,13 @@
+import type { TorrentFileSelection } from '../file-selection';
+
+export type FileWrite = {
+    path: string[];
+    fileOffset: number;
+    dataOffset: number;
+    length: number;
+};
+
+export type WritePieceOptions = {
+    files?: TorrentFileSelection;
+    outputDirectory: string;
+};

package/src/torrent/types.ts

@@ -0,0 +1,16 @@
+export type TorrentFile = {
+    path: string[];
+    length: number;
+    offset: number;
+};
+
+export type TorrentMetadata = {
+    announce?: string;
+    announceList: string[][];
+    infoHash: Uint8Array;
+    name: string;
+    pieceLength: number;
+    pieces: Uint8Array[];
+    length: number;
+    files: TorrentFile[];
+};

package/src/tracker/http.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test';
+
+import { encodeBencode, toBValue } from '@torrent/bencode';
+import { parseHttpAnnounceResponse } from './http';
+import { TrackerError, TrackerErrorCode } from './tracker.error';
+
+describe('parseHttpAnnounceResponse', () => {
+    test('parses compact peers from a tracker response', () => {
+        const peers = parseHttpAnnounceResponse(
+            encodeBencode(
+                toBValue({
+                    interval: 1_800,
+                    peers: new Uint8Array([127, 0, 0, 1, 0x1a, 0xe1, 10, 0, 0, 2, 0x13, 0x88]),
+                }),
+            ),
+        );
+
+        expect(peers).toEqual([
+            { ip: '127.0.0.1', port: 6881 },
+            { ip: '10.0.0.2', port: 5000 },
+        ]);
+    });
+
+    test('rejects tracker failure responses', () => {
+        expect(() =>
+            parseHttpAnnounceResponse(
+                encodeBencode(toBValue({ 'failure reason': 'torrent not registered' })),
+            ),
+        ).toThrow(TrackerError);
+        expect(() =>
+            parseHttpAnnounceResponse(
+                encodeBencode(toBValue({ 'failure reason': 'torrent not registered' })),
+            ),
+        ).toThrow('torrent not registered');
+    });
+
+    test('rejects malformed compact peer lists', () => {
+        expect(() =>
+            parseHttpAnnounceResponse(
+                encodeBencode(toBValue({ peers: new Uint8Array([127, 0, 0, 1, 0x1a]) })),
+            ),
+        ).toThrow(TrackerError);
+
+        try {
+            parseHttpAnnounceResponse(
+                encodeBencode(toBValue({ peers: new Uint8Array([127, 0, 0, 1, 0x1a]) })),
+            );
+            throw new Error('Expected parseHttpAnnounceResponse to throw');
+        } catch (error) {
+            expect((error as TrackerError).code).toBe(TrackerErrorCode.HTTP_RESPONSE_INVALID);
+        }
+    });
+
+    test('rejects empty peer lists as no peers', () => {
+        expect(() =>
+            parseHttpAnnounceResponse(encodeBencode(toBValue({ peers: new Uint8Array() }))),
+        ).toThrow(TrackerError);
+
+        try {
+            parseHttpAnnounceResponse(encodeBencode(toBValue({ peers: new Uint8Array() })));
+            throw new Error('Expected parseHttpAnnounceResponse to throw');
+        } catch (error) {
+            expect((error as TrackerError).code).toBe(TrackerErrorCode.NO_PEERS);
+        }
+    });
+});