bun-torrent 0.0.1-beta

package/src/peer/availability.ts

@@ -0,0 +1,88 @@
+export type PeerPieceAvailabilityOptions = {
+    bitfield?: Uint8Array;
+};
+
+/**
+ * Mutable view of which torrent pieces a peer claims to have.
+ */
+export class PeerPieceAvailability {
+    private readonly pieces: boolean[];
+
+    /**
+     * Create availability state from an optional peer bitfield.
+     *
+     * @param totalPieces - Number of pieces in the torrent.
+     * @param options - Optional initial bitfield from the peer.
+     */
+    public constructor(
+        public readonly totalPieces: number,
+        options: PeerPieceAvailabilityOptions = {},
+    ) {
+        this.pieces = Array.from({ length: totalPieces }, (_, pieceIndex) =>
+            options.bitfield ? hasBitfieldPiece(options.bitfield, pieceIndex) : false,
+        );
+    }
+
+    /**
+     * Return true when the peer claims to have a piece.
+     *
+     * @param pieceIndex - Zero-based piece index.
+     * @returns Whether the peer has the piece. Invalid indexes return false.
+     */
+    public hasPiece(pieceIndex: number): boolean {
+        return this.pieces[pieceIndex] ?? false;
+    }
+
+    /**
+     * Mark one piece as available after receiving a peer `have` message.
+     *
+     * @param pieceIndex - Zero-based piece index.
+     */
+    public markHave(pieceIndex: number): void {
+        if (!Number.isInteger(pieceIndex) || pieceIndex < 0 || pieceIndex >= this.totalPieces) {
+            return;
+        }
+
+        this.pieces[pieceIndex] = true;
+    }
+
+    /**
+     * Replace availability from a peer `bitfield` message.
+     *
+     * @param bitfield - Raw bitfield payload from the peer.
+     */
+    public setBitfield(bitfield: Uint8Array): void {
+        for (let pieceIndex = 0; pieceIndex < this.totalPieces; pieceIndex += 1) {
+            this.pieces[pieceIndex] = hasBitfieldPiece(bitfield, pieceIndex);
+        }
+    }
+
+    /**
+     * Return available piece indexes in ascending order.
+     *
+     * @returns Piece indexes currently marked as available.
+     */
+    public toPieceIndexes(): number[] {
+        return this.pieces.flatMap((available, pieceIndex) => (available ? [pieceIndex] : []));
+    }
+}
+
+/**
+ * Create mutable availability state from an optional peer bitfield.
+ *
+ * @param totalPieces - Number of pieces in the torrent.
+ * @param bitfield - Optional raw bitfield payload from the peer.
+ * @returns Peer piece availability state.
+ */
+export const createPeerPieceAvailability = (
+    totalPieces: number,
+    bitfield?: Uint8Array,
+): PeerPieceAvailability => new PeerPieceAvailability(totalPieces, { bitfield });
+
+const hasBitfieldPiece = (bitfield: Uint8Array, pieceIndex: number): boolean => {
+    const byte = bitfield[Math.floor(pieceIndex / 8)];
+    if (byte === undefined) return false;
+
+    const mask = 0x80 >> (pieceIndex % 8);
+    return (byte & mask) !== 0;
+};

package/src/peer/consts.ts

@@ -0,0 +1,11 @@
+export const PROTOCOL = 'BitTorrent protocol';
+export const PROTOCOL_BYTES = new TextEncoder().encode(PROTOCOL);
+
+export const PEER_ID_PREFIX = '-BT0001-';
+
+export const HANDSHAKE_LENGTH = 68;
+export const RESERVED_LENGTH = 8;
+export const INFO_HASH_LENGTH = 20;
+export const PEER_ID_LENGTH = 20;
+
+export const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

package/src/peer/handshake/handshake.error.ts

@@ -0,0 +1,15 @@
+import { BunTorrentError } from '@utils/errors';
+
+export enum HandshakeErrorCode {
+    INFOHASH_INVALID_LENGTH = 'HANDSHK_INFOHASH_INVALID_LENGTH',
+    INVALID_LENGTH = 'HANDSHK_INVALID_LENGTH',
+    INVALID_PROTOCOL = 'HANDSHK_INVALID_PROTOCOL',
+    PEERID_INVALID_LENGTH = 'HANDSHK_PEERID_INVALID_LENGTH',
+    RESERVED_INVALID_LENGTH = 'HANDSHK_RESERVED_INVALID_LENGTH',
+}
+
+export class PeerHandshakeError extends BunTorrentError {
+    constructor(code: HandshakeErrorCode, message: string) {
+        super(message, code);
+    }
+}

package/src/peer/handshake/handshake.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from 'bun:test';
+
+import { BunTorrentError } from '@utils/errors';
+import {
+    HANDSHAKE_LENGTH,
+    INFO_HASH_LENGTH,
+    PEER_ID_LENGTH,
+    PROTOCOL,
+    PROTOCOL_BYTES,
+    RESERVED_LENGTH,
+} from '../consts';
+import { decodeHandshake, encodeHandshake } from '.';
+import { HandshakeErrorCode, PeerHandshakeError } from '../handshake/handshake.error';
+
+const makeBytes = (length: number, start = 0): Uint8Array => {
+    const bytes = new Uint8Array(length);
+
+    for (let i = 0; i < length; i++) {
+        bytes[i] = start + i;
+    }
+
+    return bytes;
+};
+
+const expectHandshakeError = (callback: () => unknown, code: HandshakeErrorCode): void => {
+    try {
+        callback();
+        throw new Error('Expected handshake operation to throw');
+    } catch (error) {
+        expect(error).toBeInstanceOf(PeerHandshakeError);
+        expect(error).toBeInstanceOf(BunTorrentError);
+        expect((error as PeerHandshakeError).code).toBe(code);
+    }
+};
+
+describe('encodeHandshake', () => {
+    test('encodes a 68-byte BitTorrent handshake', () => {
+        const infoHash = makeBytes(INFO_HASH_LENGTH, 1);
+        const peerId = makeBytes(PEER_ID_LENGTH, 101);
+        const handshake = encodeHandshake({ infoHash, peerId });
+
+        expect(handshake.byteLength).toBe(HANDSHAKE_LENGTH);
+        expect(handshake[0]).toBe(PROTOCOL_BYTES.byteLength);
+        expect([...handshake.subarray(1, 20)]).toEqual([...PROTOCOL_BYTES]);
+        expect([...handshake.subarray(20, 28)]).toEqual([...new Uint8Array(RESERVED_LENGTH)]);
+        expect([...handshake.subarray(28, 48)]).toEqual([...infoHash]);
+        expect([...handshake.subarray(48, 68)]).toEqual([...peerId]);
+    });
+
+    test('encodes custom reserved bytes', () => {
+        const reserved = makeBytes(RESERVED_LENGTH, 201);
+        const handshake = encodeHandshake({
+            infoHash: makeBytes(INFO_HASH_LENGTH, 1),
+            peerId: makeBytes(PEER_ID_LENGTH, 101),
+            reserved,
+        });
+
+        expect([...handshake.subarray(20, 28)]).toEqual([...reserved]);
+    });
+
+    test('rejects invalid info hash length', () => {
+        expectHandshakeError(
+            () =>
+                encodeHandshake({
+                    infoHash: new Uint8Array(19),
+                    peerId: makeBytes(PEER_ID_LENGTH),
+                }),
+            HandshakeErrorCode.INFOHASH_INVALID_LENGTH,
+        );
+    });
+
+    test('rejects invalid peer id length', () => {
+        expectHandshakeError(
+            () =>
+                encodeHandshake({
+                    infoHash: makeBytes(INFO_HASH_LENGTH),
+                    peerId: new Uint8Array(19),
+                }),
+            HandshakeErrorCode.PEERID_INVALID_LENGTH,
+        );
+    });
+
+    test('rejects invalid reserved length', () => {
+        expectHandshakeError(
+            () =>
+                encodeHandshake({
+                    infoHash: makeBytes(INFO_HASH_LENGTH),
+                    peerId: makeBytes(PEER_ID_LENGTH),
+                    reserved: new Uint8Array(7),
+                }),
+            HandshakeErrorCode.RESERVED_INVALID_LENGTH,
+        );
+    });
+});
+
+describe('decodeHandshake', () => {
+    test('decodes an encoded handshake', () => {
+        const infoHash = makeBytes(INFO_HASH_LENGTH, 1);
+        const peerId = makeBytes(PEER_ID_LENGTH, 101);
+        const reserved = makeBytes(RESERVED_LENGTH, 201);
+        const decoded = decodeHandshake(encodeHandshake({ infoHash, peerId, reserved }));
+
+        expect(decoded.protocol).toBe(PROTOCOL);
+        expect([...decoded.reserved]).toEqual([...reserved]);
+        expect([...decoded.infoHash]).toEqual([...infoHash]);
+        expect([...decoded.peerId]).toEqual([...peerId]);
+    });
+
+    test('rejects invalid handshake length', () => {
+        expectHandshakeError(
+            () => decodeHandshake(new Uint8Array(HANDSHAKE_LENGTH - 1)),
+            HandshakeErrorCode.INVALID_LENGTH,
+        );
+    });
+
+    test('rejects invalid protocol', () => {
+        const handshake = encodeHandshake({
+            infoHash: makeBytes(INFO_HASH_LENGTH),
+            peerId: makeBytes(PEER_ID_LENGTH),
+        });
+        handshake[1] = 0x78;
+
+        expectHandshakeError(() => decodeHandshake(handshake), HandshakeErrorCode.INVALID_PROTOCOL);
+    });
+});

package/src/peer/handshake/index.ts

@@ -0,0 +1,83 @@
+import {
+    HANDSHAKE_LENGTH,
+    INFO_HASH_LENGTH,
+    PEER_ID_LENGTH,
+    PROTOCOL,
+    PROTOCOL_BYTES,
+    RESERVED_LENGTH,
+} from '../consts';
+import { HandshakeErrorCode, PeerHandshakeError } from './handshake.error';
+import type { PeerHandshake } from '../types';
+
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+
+export const encodeHandshake = (input: {
+    infoHash: Uint8Array;
+    peerId: Uint8Array;
+    reserved?: Uint8Array;
+}): Uint8Array => {
+    if (input.infoHash.byteLength !== INFO_HASH_LENGTH)
+        return fail(
+            HandshakeErrorCode.INFOHASH_INVALID_LENGTH,
+            'Torrent infohash is invalid length',
+        );
+    if (input.peerId.byteLength !== PEER_ID_LENGTH)
+        return fail(HandshakeErrorCode.PEERID_INVALID_LENGTH, 'Torrent peerId is invalid length');
+
+    let offset = 0;
+    const handshake = new Uint8Array(HANDSHAKE_LENGTH);
+
+    handshake[offset++] = PROTOCOL_BYTES.byteLength;
+    handshake.set(PROTOCOL_BYTES, offset);
+    offset += PROTOCOL_BYTES.byteLength;
+
+    const reserved = input.reserved ?? new Uint8Array(RESERVED_LENGTH);
+    if (reserved.byteLength !== RESERVED_LENGTH)
+        return fail(
+            HandshakeErrorCode.RESERVED_INVALID_LENGTH,
+            'Handshake reserved is invalid length',
+        );
+
+    handshake.set(reserved, offset);
+    offset += RESERVED_LENGTH;
+
+    handshake.set(input.infoHash, offset);
+    offset += INFO_HASH_LENGTH;
+
+    handshake.set(input.peerId, offset);
+
+    return handshake;
+};
+
+export const decodeHandshake = (handshake: Uint8Array): PeerHandshake => {
+    if (handshake.byteLength !== HANDSHAKE_LENGTH)
+        return fail(HandshakeErrorCode.INVALID_LENGTH, 'Handshake is invalid length');
+
+    let offset = 0;
+    const protocolLength = handshake[offset++]!;
+    const protocolEnd = offset + protocolLength;
+    const protocol = textDecoder.decode(handshake.subarray(offset, protocolEnd));
+    offset = protocolEnd;
+
+    if (protocol !== PROTOCOL)
+        return fail(HandshakeErrorCode.INVALID_PROTOCOL, 'Handshake protocol is invalid');
+
+    const reserved = handshake.subarray(offset, offset + RESERVED_LENGTH);
+    offset += RESERVED_LENGTH;
+
+    const infoHash = handshake.subarray(offset, offset + INFO_HASH_LENGTH);
+    offset += INFO_HASH_LENGTH;
+
+    const peerId = handshake.subarray(offset, offset + PEER_ID_LENGTH);
+
+    return {
+        protocol,
+        reserved,
+        infoHash,
+        peerId,
+    };
+};
+
+const fail = (code: HandshakeErrorCode, message: string): never => {
+    throw new PeerHandshakeError(code, message);
+};

package/src/peer/index.ts

@@ -0,0 +1,31 @@
+export { createPeerId } from './peer-id';
+export { createPeerPieceAvailability, PeerPieceAvailability } from './availability';
+export { PeerSession, PeerSessionError, PeerSessionErrorCode } from './session';
+export { encodeHandshake, decodeHandshake } from './handshake';
+export { HandshakeErrorCode, PeerHandshakeError } from './handshake/handshake.error';
+export {
+    decodePeerMessage,
+    encodePeerMessage,
+    PeerMessageError,
+    PeerMessageErrorCode,
+    PeerMessageId,
+} from './messages';
+export { connectToPeers, openPeerPool, PeerPool, PeerPoolError, PeerPoolErrorCode } from './pool';
+
+export type { PeerHandshake } from './types';
+export type { PeerPieceAvailabilityOptions } from './availability';
+export type { PeerSessionConnectOptions } from './session';
+export type { PeerConnectionSession, PeerPoolOptions } from './pool';
+export type {
+    BitfieldMessage,
+    CancelMessage,
+    ChokeMessage,
+    HaveMessage,
+    InterestedMessage,
+    KeepAliveMessage,
+    NotInterestedMessage,
+    PeerMessage,
+    PieceMessage,
+    RequestMessage,
+    UnchokeMessage,
+} from './messages/types';

package/src/peer/messages/error.ts

@@ -0,0 +1,16 @@
+import { BunTorrentError } from '@utils/errors';
+
+export enum PeerMessageErrorCode {
+    INVALID_LENGTH_PREFIX = 'PEER_MSG_INVALID_LENGTH_PREFIX',
+    INVALID_MESSAGE_LENGTH = 'PEER_MSG_INVALID_MESSAGE_LENGTH',
+    INVALID_PAYLOAD_LENGTH = 'PEER_MSG_INVALID_PAYLOAD_LENGTH',
+    INVALID_UINT32 = 'PEER_MSG_INVALID_UINT32',
+    UNKNOWN_MESSAGE_ID = 'PEER_MSG_UNKNOWN_MESSAGE_ID',
+    UNSUPPORTED_MESSAGE = 'PEER_MSG_UNSUPPORTED_MESSAGE',
+}
+
+export class PeerMessageError extends BunTorrentError {
+    constructor(code: PeerMessageErrorCode, message: string) {
+        super(message, code);
+    }
+}

package/src/peer/messages/helpers.ts

@@ -0,0 +1,36 @@
+import { concatBytes } from '@utils/buffers';
+import { PeerMessageError, PeerMessageErrorCode } from './error';
+import type { PeerMessageId } from './types';
+
+const UINT32_MAX = 0xffffffff;
+
+export const encodeFrame = (
+    id: PeerMessageId,
+    payload: Uint8Array<ArrayBufferLike> = new Uint8Array(),
+): Uint8Array => concatBytes([writeUInt32(1 + payload.byteLength), new Uint8Array([id]), payload]);
+
+export const writeUInt32 = (value: number): Uint8Array => {
+    assertUInt32(value);
+
+    const bytes = new Uint8Array(4);
+    new DataView(bytes.buffer).setUint32(0, value, false);
+    return bytes;
+};
+
+export const readUInt32 = (input: Uint8Array, offset: number): number => {
+    if (offset < 0 || offset + 4 > input.byteLength) {
+        return fail(PeerMessageErrorCode.INVALID_LENGTH_PREFIX, 'Not enough bytes to read uint32');
+    }
+
+    return new DataView(input.buffer, input.byteOffset + offset, 4).getUint32(0, false);
+};
+
+export const assertUInt32 = (value: number): void => {
+    if (!Number.isInteger(value) || value < 0 || value > UINT32_MAX) {
+        return fail(PeerMessageErrorCode.INVALID_UINT32, `Invalid uint32: ${value}`);
+    }
+};
+
+const fail = (code: PeerMessageErrorCode, message: string): never => {
+    throw new PeerMessageError(code, message);
+};

package/src/peer/messages/index.ts

@@ -0,0 +1,174 @@
+import { PeerMessageError, PeerMessageErrorCode } from './error';
+import { encodeFrame, writeUInt32 } from './helpers';
+import { PeerMessageId, type PeerMessage } from './types';
+import { concatBytes } from '@utils/buffers';
+
+export const encodePeerMessage = (message: PeerMessage): Uint8Array => {
+    switch (message.type) {
+        case 'keep-alive':
+            return writeUInt32(0);
+        case 'choke':
+            return encodeFrame(PeerMessageId.Choke);
+        case 'unchoke':
+            return encodeFrame(PeerMessageId.Unchoke);
+        case 'interested':
+            return encodeFrame(PeerMessageId.Interested);
+        case 'not-interested':
+            return encodeFrame(PeerMessageId.NotInterested);
+        case 'have':
+            return encodeFrame(PeerMessageId.Have, writeUInt32(message.pieceIndex));
+        case 'bitfield':
+            return encodeFrame(PeerMessageId.Bitfield, message.bitfield);
+        case 'request':
+            return encodeFrame(
+                PeerMessageId.Request,
+                concatBytes([
+                    writeUInt32(message.pieceIndex),
+                    writeUInt32(message.offset),
+                    writeUInt32(message.length),
+                ]),
+            );
+        case 'piece':
+            return encodeFrame(
+                PeerMessageId.Piece,
+                concatBytes([
+                    writeUInt32(message.pieceIndex),
+                    writeUInt32(message.offset),
+                    message.block,
+                ]),
+            );
+        case 'cancel':
+            return encodeFrame(
+                PeerMessageId.Cancel,
+                concatBytes([
+                    writeUInt32(message.pieceIndex),
+                    writeUInt32(message.offset),
+                    writeUInt32(message.length),
+                ]),
+            );
+        default:
+            return assertNever(message);
+    }
+};
+
+export const decodePeerMessage = (input: Uint8Array): PeerMessage => {
+    if (input.byteLength < 4) {
+        return fail(
+            PeerMessageErrorCode.INVALID_LENGTH_PREFIX,
+            'Peer message is missing length prefix',
+        );
+    }
+
+    const length = readUInt32(input, 0);
+    if (input.byteLength !== 4 + length) {
+        return fail(
+            PeerMessageErrorCode.INVALID_MESSAGE_LENGTH,
+            'Peer message length does not match input size',
+        );
+    }
+
+    if (length === 0) {
+        return { type: 'keep-alive' };
+    }
+
+    const id = input[4];
+    const payload = input.subarray(5);
+
+    switch (id) {
+        case PeerMessageId.Choke:
+            assertPayloadLength(payload, 0, 'choke');
+            return { type: 'choke' };
+        case PeerMessageId.Unchoke:
+            assertPayloadLength(payload, 0, 'unchoke');
+            return { type: 'unchoke' };
+        case PeerMessageId.Interested:
+            assertPayloadLength(payload, 0, 'interested');
+            return { type: 'interested' };
+        case PeerMessageId.NotInterested:
+            assertPayloadLength(payload, 0, 'not-interested');
+            return { type: 'not-interested' };
+        case PeerMessageId.Have:
+            assertPayloadLength(payload, 4, 'have');
+            return { type: 'have', pieceIndex: readUInt32(payload, 0) };
+        case PeerMessageId.Bitfield:
+            return { type: 'bitfield', bitfield: payload };
+        case PeerMessageId.Request:
+            assertPayloadLength(payload, 12, 'request');
+            return {
+                type: 'request',
+                pieceIndex: readUInt32(payload, 0),
+                offset: readUInt32(payload, 4),
+                length: readUInt32(payload, 8),
+            };
+        case PeerMessageId.Piece:
+            assertMinPayloadLength(payload, 8, 'piece');
+            return {
+                type: 'piece',
+                pieceIndex: readUInt32(payload, 0),
+                offset: readUInt32(payload, 4),
+                block: payload.subarray(8),
+            };
+        case PeerMessageId.Cancel:
+            assertPayloadLength(payload, 12, 'cancel');
+            return {
+                type: 'cancel',
+                pieceIndex: readUInt32(payload, 0),
+                offset: readUInt32(payload, 4),
+                length: readUInt32(payload, 8),
+            };
+        default:
+            return fail(PeerMessageErrorCode.UNKNOWN_MESSAGE_ID, `Unknown peer message id: ${id}`);
+    }
+};
+
+export { PeerMessageError, PeerMessageErrorCode } from './error';
+export { PeerMessageId } from './types';
+export type {
+    BitfieldMessage,
+    CancelMessage,
+    ChokeMessage,
+    HaveMessage,
+    InterestedMessage,
+    KeepAliveMessage,
+    NotInterestedMessage,
+    PeerMessage,
+    PieceMessage,
+    RequestMessage,
+    UnchokeMessage,
+} from './types';
+
+const readUInt32 = (input: Uint8Array, offset: number): number => {
+    if (offset < 0 || offset + 4 > input.byteLength) {
+        return fail(
+            PeerMessageErrorCode.INVALID_PAYLOAD_LENGTH,
+            'Not enough payload bytes to read uint32',
+        );
+    }
+
+    return new DataView(input.buffer, input.byteOffset + offset, 4).getUint32(0, false);
+};
+
+const assertPayloadLength = (payload: Uint8Array, expected: number, type: string): void => {
+    if (payload.byteLength !== expected) {
+        return fail(
+            PeerMessageErrorCode.INVALID_PAYLOAD_LENGTH,
+            `${type} payload must be ${expected} bytes, got ${payload.byteLength}`,
+        );
+    }
+};
+
+const assertMinPayloadLength = (payload: Uint8Array, minimum: number, type: string): void => {
+    if (payload.byteLength < minimum) {
+        return fail(
+            PeerMessageErrorCode.INVALID_PAYLOAD_LENGTH,
+            `${type} payload must be at least ${minimum} bytes, got ${payload.byteLength}`,
+        );
+    }
+};
+
+const assertNever = (value: never): never =>
+    fail(PeerMessageErrorCode.UNSUPPORTED_MESSAGE, `Unsupported peer message: ${String(value)}`);
+
+const fail = (code: PeerMessageErrorCode, message: string): never => {
+    throw new PeerMessageError(code, message);
+};