bun-torrent 0.0.1-beta

package/src/torrent/pieces/DefaultPlanner.ts

@@ -0,0 +1,257 @@
+import type { TorrentMetadata } from '@torrent/types';
+import type {
+    BlockState,
+    PieceAvailability,
+    PieceBlock,
+    PieceBlockRequest,
+    PieceCompletion,
+    PiecePlanner,
+    PiecePlannerOptions,
+    PieceProgress,
+    PlannedPiece,
+} from './types';
+import { getPieceLength, isValidBlockForRequest, splitPieceIntoRequests } from './utils';
+import { concatBytes } from '@utils/buffers';
+import { PiecePlannerError, PiecePlannerErrorCode } from './planner.error';
+
+/**
+ * In-memory piece planner that schedules block requests and assembles completed pieces.
+ */
+export class DefaultPiecePlanner implements PiecePlanner {
+    private pieces: PlannedPiece[];
+    private selectedPieces: Set<number>;
+    private selectedPieceList: number[];
+    private completed = new Set<number>();
+
+    /**
+     * Build an initial missing-block plan from torrent metadata.
+     *
+     * @param metadata - Parsed torrent metadata containing piece hashes and sizes.
+     * @param options - Planner options, including optional block size.
+     * @throws {PiecePlannerError} When piece or block sizing is invalid.
+     */
+    constructor(metadata: TorrentMetadata, options: PiecePlannerOptions) {
+        this.pieces = metadata.pieces.map((expectedHash, pieceIndex) => {
+            const length = getPieceLength(metadata, pieceIndex);
+            return {
+                pieceIndex,
+                expectedHash,
+                length,
+                blocks: splitPieceIntoRequests({
+                    pieceIndex,
+                    pieceLength: length,
+                    blockLength: options.blockLength,
+                }).map((request) => ({
+                    request,
+                    status: 'missing',
+                    data: undefined,
+                })),
+            };
+        });
+        this.selectedPieceList =
+            options.pieceIndexes === undefined
+                ? this.pieces.map((piece) => piece.pieceIndex)
+                : [...new Set(options.pieceIndexes)].sort((a, b) => a - b);
+        this.selectedPieces = new Set(this.selectedPieceList);
+
+        for (const pieceIndex of this.selectedPieceList) this.getPiece(pieceIndex);
+    }
+
+    get complete(): boolean {
+        return this.completed.size === this.selectedPieces.size;
+    }
+
+    get completedPieces(): number {
+        return this.completed.size;
+    }
+
+    get pieceIndexes(): readonly number[] {
+        return this.selectedPieceList;
+    }
+
+    get totalPieces(): number {
+        return this.selectedPieces.size;
+    }
+
+    /**
+     * Return internal state for a piece.
+     *
+     * @param pieceIndex - Zero-based piece index.
+     * @returns Planned piece state.
+     * @throws {PiecePlannerError} When `pieceIndex` is outside the torrent piece range.
+     */
+    private getPiece(pieceIndex: number): PlannedPiece {
+        const piece = this.pieces[pieceIndex];
+        if (!piece) {
+            throw new PiecePlannerError(
+                PiecePlannerErrorCode.INVALID_PIECE_INDEX,
+                `Unknown piece index: ${pieceIndex}`,
+                pieceIndex,
+            );
+        }
+        return piece;
+    }
+
+    /**
+     * Locate the internal block state described by a request.
+     *
+     * @param request - Block request to look up.
+     * @returns Matching block state, or `undefined` when the request is unknown.
+     * @throws {PiecePlannerError} When `request.pieceIndex` is invalid.
+     */
+    private findBlock(request: PieceBlockRequest): BlockState | undefined {
+        const piece = this.getPiece(request.pieceIndex);
+        return piece.blocks.find(
+            (b) => b.request.offset === request.offset && b.request.length === request.length,
+        );
+    }
+
+    /**
+     * Return a progress snapshot for a piece.
+     *
+     * @param pieceIndex - Zero-based piece index.
+     * @returns Progress for the requested piece.
+     * @throws {PiecePlannerError} When `pieceIndex` is outside the torrent piece range.
+     */
+    public getProgress(pieceIndex: number): PieceProgress {
+        const piece = this.getPiece(pieceIndex);
+        const completed = this.completed.has(pieceIndex);
+        const receivedBytes = piece.blocks.reduce<number>(
+            (a, b) => a + (b.status === 'received' ? b.request.length : 0),
+            0,
+        );
+
+        return {
+            pieceIndex,
+            length: piece.length,
+            receivedBytes,
+            status: completed
+                ? 'complete'
+                : piece.blocks.some((b) => b.status === 'pending')
+                  ? 'pending'
+                  : 'missing',
+        };
+    }
+
+    /**
+     * Pick the next missing block request.
+     *
+     * @param availablePieces - Optional peer availability filter, usually backed by bitfield/have state.
+     * @returns The next request to send, or `undefined` when nothing is currently requestable.
+     */
+    public nextRequest(availablePieces?: PieceAvailability): PieceBlockRequest | undefined {
+        for (const piece of this.pieces) {
+            if (!this.selectedPieces.has(piece.pieceIndex)) continue;
+            if (this.completed.has(piece.pieceIndex)) continue;
+            if (availablePieces && !availablePieces.hasPiece(piece.pieceIndex)) continue;
+
+            const block = piece.blocks.find((b) => b.status === 'missing');
+            if (block) return block.request;
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Mark a missing request as in-flight.
+     *
+     * @param request - Request selected by `nextRequest`.
+     * @throws {PiecePlannerError} When `request.pieceIndex` is invalid.
+     */
+    public markPending(request: PieceBlockRequest): void {
+        const block = this.findBlock(request);
+        if (!block || block.status !== 'missing') return;
+
+        block.status = 'pending';
+    }
+
+    /**
+     * Return an in-flight request back to the missing state.
+     *
+     * @param request - Pending request that timed out or belonged to a disconnected peer.
+     * @throws {PiecePlannerError} When `request.pieceIndex` is invalid.
+     */
+    public resetPending(request: PieceBlockRequest): void {
+        const block = this.findBlock(request);
+        if (!block || block.status !== 'pending') return;
+
+        block.status = 'missing';
+    }
+
+    /**
+     * Reset every in-flight request assigned to a disconnected peer.
+     *
+     * @param requests - Requests previously assigned to the peer.
+     * @throws {PiecePlannerError} When any request contains an invalid piece index.
+     */
+    public resetPeerRequests(requests: Iterable<PieceBlockRequest>): void {
+        for (const r of requests) this.resetPending(r);
+    }
+
+    /**
+     * Concatenate received blocks for a completed piece.
+     *
+     * @param piece - Planned piece whose blocks should all be received.
+     * @returns The assembled piece bytes.
+     * @throws {PiecePlannerError} When any block payload is missing.
+     */
+    private assemblePiece(piece: PlannedPiece): Uint8Array {
+        const blocks: Uint8Array[] = [];
+
+        for (const block of piece.blocks) {
+            if (!block.data) {
+                throw new PiecePlannerError(
+                    PiecePlannerErrorCode.INCOMPLETE_PIECE,
+                    `Cannot assemble incomplete piece: ${piece.pieceIndex}`,
+                    piece.pieceIndex,
+                );
+            }
+            blocks.push(block.data);
+        }
+
+        return concatBytes(blocks);
+    }
+
+    /**
+     * Accept a received block and emit a completed piece once all blocks are present.
+     *
+     * @param block - Received peer piece message.
+     * @returns Completed piece data, or `undefined` if the piece is still incomplete or the block is unknown.
+     * @throws {PiecePlannerError} When `block.pieceIndex` is invalid.
+     */
+    public receiveBlock(block: PieceBlock): PieceCompletion | undefined {
+        const piece = this.getPiece(block.pieceIndex);
+        const state = piece.blocks.find((b) => isValidBlockForRequest(block, b.request));
+
+        if (!state || state.status !== 'pending') return undefined;
+
+        state.status = 'received';
+        state.data = block.block;
+
+        if (!piece.blocks.every((block) => block.status === 'received')) return undefined;
+
+        this.completed.add(piece.pieceIndex);
+
+        return {
+            pieceIndex: block.pieceIndex,
+            data: this.assemblePiece(piece),
+            expectedHash: piece.expectedHash,
+        };
+    }
+
+    /**
+     * Return every block in a piece to the missing state.
+     *
+     * @param pieceIndex - Piece to retry after failed validation or storage.
+     * @throws {PiecePlannerError} When `pieceIndex` is outside the torrent piece range.
+     */
+    public resetPiece(pieceIndex: number): void {
+        const piece = this.getPiece(pieceIndex);
+        this.completed.delete(pieceIndex);
+
+        for (const block of piece.blocks) {
+            block.status = 'missing';
+            block.data = undefined;
+        }
+    }
+}

package/src/torrent/pieces/index.ts

@@ -0,0 +1,20 @@
+export { createPiecePlanner } from './planner';
+export {
+    DEFAULT_BLOCK_LENGTH,
+    getPieceLength,
+    isValidBlockForRequest,
+    splitPieceIntoRequests,
+} from './utils';
+export { PiecePlannerError, PiecePlannerErrorCode } from './planner.error';
+export { validatePiece, type PieceValidationResult } from './validation';
+
+export type {
+    PieceAvailability,
+    PieceBlock,
+    PieceBlockRequest,
+    PieceCompletion,
+    PiecePlanner,
+    PiecePlannerOptions,
+    PieceProgress,
+    PieceStatus,
+} from './types';

package/src/torrent/pieces/planner.error.ts

@@ -0,0 +1,18 @@
+import { BunTorrentError } from '@utils/errors';
+
+export enum PiecePlannerErrorCode {
+    INCOMPLETE_PIECE = 'PIECE_PLANNER_INCOMPLETE_PIECE',
+    INVALID_BLOCK_LENGTH = 'PIECE_PLANNER_INVALID_BLOCK_LENGTH',
+    INVALID_PIECE_INDEX = 'PIECE_PLANNER_INVALID_PIECE_INDEX',
+    INVALID_PIECE_LENGTH = 'PIECE_PLANNER_INVALID_PIECE_LENGTH',
+}
+
+export class PiecePlannerError extends BunTorrentError {
+    constructor(
+        code: PiecePlannerErrorCode,
+        message: string,
+        public readonly pieceIndex?: number,
+    ) {
+        super(message, code);
+    }
+}

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

@@ -0,0 +1,303 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { TorrentMetadata } from '@torrent/types';
+import { createPiecePlanner } from './planner';
+import { PiecePlannerError, PiecePlannerErrorCode } from './planner.error';
+import { getPieceLength, isValidBlockForRequest, splitPieceIntoRequests } from './utils';
+
+const makeMetadata = ({
+    length = 1_000,
+    pieceLength = 256,
+    pieces = 4,
+}: {
+    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 }],
+});
+
+const expectPlannerError = (callback: () => unknown, code: PiecePlannerErrorCode): void => {
+    try {
+        callback();
+        throw new Error('Expected callback to throw');
+    } catch (error) {
+        expect(error).toBeInstanceOf(PiecePlannerError);
+        expect((error as PiecePlannerError).code).toBe(code);
+    }
+};
+
+describe('piece planner utils', () => {
+    test('gets regular and final piece lengths', () => {
+        const metadata = makeMetadata();
+
+        expect(getPieceLength(metadata, 0)).toBe(256);
+        expect(getPieceLength(metadata, 1)).toBe(256);
+        expect(getPieceLength(metadata, 2)).toBe(256);
+        expect(getPieceLength(metadata, 3)).toBe(232);
+    });
+
+    test('rejects invalid piece indexes', () => {
+        const metadata = makeMetadata();
+
+        expectPlannerError(
+            () => getPieceLength(metadata, -1),
+            PiecePlannerErrorCode.INVALID_PIECE_INDEX,
+        );
+        expectPlannerError(
+            () => getPieceLength(metadata, 4),
+            PiecePlannerErrorCode.INVALID_PIECE_INDEX,
+        );
+    });
+
+    test('splits a piece into block requests', () => {
+        expect(
+            splitPieceIntoRequests({
+                pieceIndex: 3,
+                pieceLength: 40_000,
+                blockLength: 16_384,
+            }),
+        ).toEqual([
+            { type: 'request', pieceIndex: 3, offset: 0, length: 16_384 },
+            { type: 'request', pieceIndex: 3, offset: 16_384, length: 16_384 },
+            { type: 'request', pieceIndex: 3, offset: 32_768, length: 7_232 },
+        ]);
+    });
+
+    test('rejects invalid piece and block lengths', () => {
+        expectPlannerError(
+            () => splitPieceIntoRequests({ pieceIndex: 0, pieceLength: 0 }),
+            PiecePlannerErrorCode.INVALID_PIECE_LENGTH,
+        );
+        expectPlannerError(
+            () => splitPieceIntoRequests({ pieceIndex: 0, pieceLength: 10, blockLength: 0 }),
+            PiecePlannerErrorCode.INVALID_BLOCK_LENGTH,
+        );
+    });
+
+    test('checks whether a block satisfies a request', () => {
+        const request = { type: 'request' as const, pieceIndex: 1, offset: 4, length: 3 };
+
+        expect(
+            isValidBlockForRequest(
+                { type: 'piece', pieceIndex: 1, offset: 4, block: new Uint8Array(3) },
+                request,
+            ),
+        ).toBe(true);
+        expect(
+            isValidBlockForRequest(
+                { type: 'piece', pieceIndex: 1, offset: 5, block: new Uint8Array(3) },
+                request,
+            ),
+        ).toBe(false);
+        expect(
+            isValidBlockForRequest(
+                { type: 'piece', pieceIndex: 1, offset: 4, block: new Uint8Array(2) },
+                request,
+            ),
+        ).toBe(false);
+    });
+});
+
+describe('DefaultPiecePlanner', () => {
+    test('tracks totals and initial progress', () => {
+        const planner = createPiecePlanner(
+            makeMetadata({ length: 10, pieceLength: 4, pieces: 3 }),
+            {
+                blockLength: 2,
+            },
+        );
+
+        expect(planner.totalPieces).toBe(3);
+        expect(planner.completedPieces).toBe(0);
+        expect(planner.complete).toBe(false);
+        expect(planner.getProgress(0)).toEqual({
+            pieceIndex: 0,
+            length: 4,
+            receivedBytes: 0,
+            status: 'missing',
+        });
+    });
+
+    test('returns the next missing request and respects availability', () => {
+        const planner = createPiecePlanner(makeMetadata({ length: 8, pieceLength: 4, pieces: 2 }), {
+            blockLength: 2,
+        });
+
+        expect(
+            planner.nextRequest({
+                hasPiece: (pieceIndex) => pieceIndex === 1,
+            }),
+        ).toEqual({ type: 'request', pieceIndex: 1, offset: 0, length: 2 });
+
+        const request = planner.nextRequest();
+        expect(request).toEqual({ type: 'request', pieceIndex: 0, offset: 0, length: 2 });
+
+        planner.markPending(request!);
+        expect(planner.nextRequest()).toEqual({
+            type: 'request',
+            pieceIndex: 0,
+            offset: 2,
+            length: 2,
+        });
+    });
+
+    test('schedules only selected pieces when configured', () => {
+        const planner = createPiecePlanner(
+            makeMetadata({ length: 12, pieceLength: 4, pieces: 3 }),
+            {
+                pieceIndexes: [1],
+            },
+        );
+
+        expect(planner.totalPieces).toBe(1);
+        expect(planner.pieceIndexes).toEqual([1]);
+        expect(planner.nextRequest()).toEqual({
+            type: 'request',
+            pieceIndex: 1,
+            offset: 0,
+            length: 4,
+        });
+    });
+
+    test('resets pending requests', () => {
+        const planner = createPiecePlanner(makeMetadata({ length: 4, pieceLength: 4, pieces: 1 }), {
+            blockLength: 2,
+        });
+        const first = planner.nextRequest()!;
+        const second = { type: 'request' as const, pieceIndex: 0, offset: 2, length: 2 };
+
+        planner.markPending(first);
+        planner.markPending(second);
+        expect(planner.nextRequest()).toBeUndefined();
+
+        planner.resetPending(first);
+        expect(planner.nextRequest()).toEqual(first);
+
+        planner.markPending(first);
+        planner.resetPeerRequests([first, second]);
+        expect(planner.nextRequest()).toEqual(first);
+    });
+
+    test('ignores blocks that were not requested', () => {
+        const planner = createPiecePlanner(makeMetadata({ length: 4, pieceLength: 4, pieces: 1 }), {
+            blockLength: 4,
+        });
+
+        expect(
+            planner.receiveBlock({
+                type: 'piece',
+                pieceIndex: 0,
+                offset: 0,
+                block: new Uint8Array([1, 2, 3, 4]),
+            }),
+        ).toBeUndefined();
+        expect(planner.getProgress(0).receivedBytes).toBe(0);
+    });
+
+    test('returns completion after all blocks in a piece are received', () => {
+        const planner = createPiecePlanner(makeMetadata({ length: 4, pieceLength: 4, pieces: 1 }), {
+            blockLength: 2,
+        });
+        const first = planner.nextRequest()!;
+        planner.markPending(first);
+        const second = planner.nextRequest()!;
+        planner.markPending(second);
+
+        expect(
+            planner.receiveBlock({
+                type: 'piece',
+                pieceIndex: 0,
+                offset: 0,
+                block: new Uint8Array([1, 2]),
+            }),
+        ).toBeUndefined();
+
+        const completion = planner.receiveBlock({
+            type: 'piece',
+            pieceIndex: 0,
+            offset: 2,
+            block: new Uint8Array([3, 4]),
+        });
+
+        expect(completion).toEqual({
+            pieceIndex: 0,
+            data: new Uint8Array([1, 2, 3, 4]),
+            expectedHash: new Uint8Array(20),
+        });
+        expect(planner.complete).toBe(true);
+        expect(planner.completedPieces).toBe(1);
+        expect(planner.getProgress(0)).toEqual({
+            pieceIndex: 0,
+            length: 4,
+            receivedBytes: 4,
+            status: 'complete',
+        });
+    });
+
+    test('resets a completed piece for retry', () => {
+        const planner = createPiecePlanner(makeMetadata({ length: 4, pieceLength: 4, pieces: 1 }), {
+            blockLength: 2,
+        });
+        const first = planner.nextRequest()!;
+        planner.markPending(first);
+        const second = planner.nextRequest()!;
+        planner.markPending(second);
+        planner.receiveBlock({
+            type: 'piece',
+            pieceIndex: 0,
+            offset: 0,
+            block: new Uint8Array([1, 2]),
+        });
+        planner.receiveBlock({
+            type: 'piece',
+            pieceIndex: 0,
+            offset: 2,
+            block: new Uint8Array([3, 4]),
+        });
+
+        planner.resetPiece(0);
+
+        expect(planner.complete).toBe(false);
+        expect(planner.completedPieces).toBe(0);
+        expect(planner.getProgress(0)).toEqual({
+            pieceIndex: 0,
+            length: 4,
+            receivedBytes: 0,
+            status: 'missing',
+        });
+        expect(planner.nextRequest()).toEqual(first);
+    });
+
+    test('resets a partially received piece for retry', () => {
+        const planner = createPiecePlanner(makeMetadata({ length: 4, pieceLength: 4, pieces: 1 }), {
+            blockLength: 2,
+        });
+        const first = planner.nextRequest()!;
+        planner.markPending(first);
+        planner.receiveBlock({
+            type: 'piece',
+            pieceIndex: 0,
+            offset: 0,
+            block: new Uint8Array([1, 2]),
+        });
+
+        planner.resetPiece(0);
+
+        expect(planner.getProgress(0).receivedBytes).toBe(0);
+        expect(planner.nextRequest()).toEqual(first);
+    });
+
+    test('throws planner errors for invalid piece indexes', () => {
+        const planner = createPiecePlanner(makeMetadata({ length: 4, pieceLength: 4, pieces: 1 }));
+
+        expectPlannerError(() => planner.getProgress(1), PiecePlannerErrorCode.INVALID_PIECE_INDEX);
+        expectPlannerError(() => planner.resetPiece(1), PiecePlannerErrorCode.INVALID_PIECE_INDEX);
+    });
+});

package/src/torrent/pieces/planner.ts

@@ -0,0 +1,16 @@
+import type { TorrentMetadata } from '@torrent/types';
+import type { PiecePlanner, PiecePlannerOptions } from './types';
+import { DefaultPiecePlanner } from './DefaultPlanner';
+
+/**
+ * Create the default mutable piece planner for torrent download scheduling.
+ *
+ * @param metadata - Parsed torrent metadata containing piece hashes and sizing information.
+ * @param options - Planner configuration such as block size.
+ * @returns A planner that can schedule block requests and assemble completed pieces.
+ * @throws {PiecePlannerError} When metadata implies invalid piece or block sizing.
+ */
+export const createPiecePlanner = (
+    metadata: TorrentMetadata,
+    options: PiecePlannerOptions = {},
+): PiecePlanner => new DefaultPiecePlanner(metadata, options);

package/src/torrent/pieces/types.ts

@@ -0,0 +1,59 @@
+import type { PieceMessage, RequestMessage } from '@peer/messages';
+
+export type PiecePlannerOptions = {
+    blockLength?: number;
+    pieceIndexes?: Iterable<number>;
+};
+
+export type PieceBlockRequest = RequestMessage;
+
+export type PieceBlock = PieceMessage;
+
+export type PieceStatus = 'missing' | 'pending' | 'complete';
+
+export type PieceProgress = {
+    pieceIndex: number;
+    length: number;
+    receivedBytes: number;
+    status: PieceStatus;
+};
+
+export type PiecePlanner = {
+    readonly complete: boolean;
+    readonly completedPieces: number;
+    readonly pieceIndexes: readonly number[];
+    readonly totalPieces: number;
+
+    getProgress(pieceIndex: number): PieceProgress;
+    nextRequest(availablePieces?: PieceAvailability): PieceBlockRequest | undefined;
+    markPending(request: PieceBlockRequest): void;
+    receiveBlock(block: PieceBlock): PieceCompletion | undefined;
+    resetPiece(pieceIndex: number): void;
+    resetPending(request: PieceBlockRequest): void;
+    resetPeerRequests(requests: Iterable<PieceBlockRequest>): void;
+};
+
+export type PieceAvailability = {
+    hasPiece(pieceIndex: number): boolean;
+};
+
+export type PieceCompletion = {
+    pieceIndex: number;
+    data: Uint8Array;
+    expectedHash: Uint8Array;
+};
+
+export type BlockStatus = 'missing' | 'pending' | 'received';
+
+export type BlockState = {
+    request: PieceBlockRequest;
+    status: BlockStatus;
+    data?: Uint8Array;
+};
+
+export type PlannedPiece = {
+    pieceIndex: number;
+    length: number;
+    expectedHash: Uint8Array;
+    blocks: BlockState[];
+};