bun-torrent 0.0.1-beta

package/src/peer/messages/messages.test.ts

@@ -0,0 +1,231 @@
+import { describe, expect, test } from 'bun:test';
+
+import { BunTorrentError } from '@utils/errors';
+import { PeerMessageError, PeerMessageErrorCode, decodePeerMessage, encodePeerMessage } from '.';
+import { readUInt32, writeUInt32 } from './helpers';
+
+const expectPeerMessageError = (callback: () => unknown, code: PeerMessageErrorCode): void => {
+    try {
+        callback();
+        throw new Error('Expected peer message operation to throw');
+    } catch (error) {
+        expect(error).toBeInstanceOf(PeerMessageError);
+        expect(error).toBeInstanceOf(BunTorrentError);
+        expect((error as PeerMessageError).code).toBe(code);
+    }
+};
+
+describe('peer message uint32 helpers', () => {
+    test('writes uint32 values in big-endian order', () => {
+        expect([...writeUInt32(0)]).toEqual([0, 0, 0, 0]);
+        expect([...writeUInt32(1)]).toEqual([0, 0, 0, 1]);
+        expect([...writeUInt32(13)]).toEqual([0, 0, 0, 13]);
+        expect([...writeUInt32(0x01020304)]).toEqual([1, 2, 3, 4]);
+    });
+
+    test('reads uint32 values in big-endian order', () => {
+        expect(readUInt32(new Uint8Array([0, 0, 0, 0]), 0)).toBe(0);
+        expect(readUInt32(new Uint8Array([0, 0, 0, 13]), 0)).toBe(13);
+        expect(readUInt32(new Uint8Array([9, 1, 2, 3, 4]), 1)).toBe(0x01020304);
+    });
+
+    test('rejects invalid uint32 values', () => {
+        expectPeerMessageError(() => writeUInt32(-1), PeerMessageErrorCode.INVALID_UINT32);
+        expectPeerMessageError(() => writeUInt32(1.5), PeerMessageErrorCode.INVALID_UINT32);
+        expectPeerMessageError(() => writeUInt32(0x100000000), PeerMessageErrorCode.INVALID_UINT32);
+    });
+
+    test('rejects reading past the end of the input', () => {
+        expectPeerMessageError(
+            () => readUInt32(new Uint8Array([0, 0, 0]), 0),
+            PeerMessageErrorCode.INVALID_LENGTH_PREFIX,
+        );
+    });
+});
+
+describe('encodePeerMessage', () => {
+    test('encodes keep-alive', () => {
+        expect([...encodePeerMessage({ type: 'keep-alive' })]).toEqual([0, 0, 0, 0]);
+    });
+
+    test('encodes choke', () => {
+        expect([...encodePeerMessage({ type: 'choke' })]).toEqual([0, 0, 0, 1, 0]);
+    });
+
+    test('encodes unchoke', () => {
+        expect([...encodePeerMessage({ type: 'unchoke' })]).toEqual([0, 0, 0, 1, 1]);
+    });
+
+    test('encodes interested', () => {
+        expect([...encodePeerMessage({ type: 'interested' })]).toEqual([0, 0, 0, 1, 2]);
+    });
+
+    test('encodes not-interested', () => {
+        expect([...encodePeerMessage({ type: 'not-interested' })]).toEqual([0, 0, 0, 1, 3]);
+    });
+
+    test('encodes have', () => {
+        expect([...encodePeerMessage({ type: 'have', pieceIndex: 7 })]).toEqual([
+            0, 0, 0, 5, 4, 0, 0, 0, 7,
+        ]);
+    });
+
+    test('encodes bitfield', () => {
+        expect([
+            ...encodePeerMessage({ type: 'bitfield', bitfield: new Uint8Array([0b10100000]) }),
+        ]).toEqual([0, 0, 0, 2, 5, 0b10100000]);
+    });
+
+    test('encodes request', () => {
+        expect([
+            ...encodePeerMessage({
+                type: 'request',
+                pieceIndex: 7,
+                offset: 16_384,
+                length: 16_384,
+            }),
+        ]).toEqual([0, 0, 0, 13, 6, 0, 0, 0, 7, 0, 0, 64, 0, 0, 0, 64, 0]);
+    });
+
+    test('encodes piece', () => {
+        expect([
+            ...encodePeerMessage({
+                type: 'piece',
+                pieceIndex: 7,
+                offset: 16_384,
+                block: new Uint8Array([1, 2, 3]),
+            }),
+        ]).toEqual([0, 0, 0, 12, 7, 0, 0, 0, 7, 0, 0, 64, 0, 1, 2, 3]);
+    });
+
+    test('encodes cancel', () => {
+        expect([
+            ...encodePeerMessage({ type: 'cancel', pieceIndex: 7, offset: 16_384, length: 16_384 }),
+        ]).toEqual([0, 0, 0, 13, 8, 0, 0, 0, 7, 0, 0, 64, 0, 0, 0, 64, 0]);
+    });
+
+    test('rejects invalid request fields', () => {
+        expectPeerMessageError(
+            () => encodePeerMessage({ type: 'request', pieceIndex: -1, offset: 0, length: 16_384 }),
+            PeerMessageErrorCode.INVALID_UINT32,
+        );
+    });
+});
+
+describe('decodePeerMessage', () => {
+    test('decodes keep-alive', () => {
+        expect(decodePeerMessage(new Uint8Array([0, 0, 0, 0]))).toEqual({ type: 'keep-alive' });
+    });
+
+    test('decodes control messages', () => {
+        expect(decodePeerMessage(new Uint8Array([0, 0, 0, 1, 0]))).toEqual({ type: 'choke' });
+        expect(decodePeerMessage(new Uint8Array([0, 0, 0, 1, 1]))).toEqual({ type: 'unchoke' });
+        expect(decodePeerMessage(new Uint8Array([0, 0, 0, 1, 2]))).toEqual({ type: 'interested' });
+        expect(decodePeerMessage(new Uint8Array([0, 0, 0, 1, 3]))).toEqual({
+            type: 'not-interested',
+        });
+    });
+
+    test('decodes have', () => {
+        expect(decodePeerMessage(new Uint8Array([0, 0, 0, 5, 4, 0, 0, 0, 7]))).toEqual({
+            type: 'have',
+            pieceIndex: 7,
+        });
+    });
+
+    test('decodes bitfield without copying payload bytes', () => {
+        const input = new Uint8Array([0, 0, 0, 2, 5, 0b10100000]);
+        const message = decodePeerMessage(input);
+
+        expect(message).toEqual({ type: 'bitfield', bitfield: new Uint8Array([0b10100000]) });
+        expect(message.type === 'bitfield' ? message.bitfield.buffer : undefined).toBe(
+            input.buffer,
+        );
+    });
+
+    test('decodes request', () => {
+        expect(
+            decodePeerMessage(
+                new Uint8Array([0, 0, 0, 13, 6, 0, 0, 0, 7, 0, 0, 64, 0, 0, 0, 64, 0]),
+            ),
+        ).toEqual({
+            type: 'request',
+            pieceIndex: 7,
+            offset: 16_384,
+            length: 16_384,
+        });
+    });
+
+    test('decodes piece', () => {
+        expect(
+            decodePeerMessage(new Uint8Array([0, 0, 0, 12, 7, 0, 0, 0, 7, 0, 0, 64, 0, 1, 2, 3])),
+        ).toEqual({
+            type: 'piece',
+            pieceIndex: 7,
+            offset: 16_384,
+            block: new Uint8Array([1, 2, 3]),
+        });
+    });
+
+    test('decodes cancel', () => {
+        expect(
+            decodePeerMessage(
+                new Uint8Array([0, 0, 0, 13, 8, 0, 0, 0, 7, 0, 0, 64, 0, 0, 0, 64, 0]),
+            ),
+        ).toEqual({
+            type: 'cancel',
+            pieceIndex: 7,
+            offset: 16_384,
+            length: 16_384,
+        });
+    });
+
+    test('rejects missing length prefix', () => {
+        expectPeerMessageError(
+            () => decodePeerMessage(new Uint8Array([0, 0, 0])),
+            PeerMessageErrorCode.INVALID_LENGTH_PREFIX,
+        );
+    });
+
+    test('rejects mismatched message length', () => {
+        expectPeerMessageError(
+            () => decodePeerMessage(new Uint8Array([0, 0, 0, 2, 5])),
+            PeerMessageErrorCode.INVALID_MESSAGE_LENGTH,
+        );
+    });
+
+    test('rejects invalid fixed payload length', () => {
+        expectPeerMessageError(
+            () => decodePeerMessage(new Uint8Array([0, 0, 0, 2, 0, 1])),
+            PeerMessageErrorCode.INVALID_PAYLOAD_LENGTH,
+        );
+    });
+
+    test('rejects piece payload shorter than index and offset', () => {
+        expectPeerMessageError(
+            () => decodePeerMessage(new Uint8Array([0, 0, 0, 8, 7, 0, 0, 0, 7, 0, 0, 64])),
+            PeerMessageErrorCode.INVALID_PAYLOAD_LENGTH,
+        );
+    });
+
+    test('rejects unknown message id', () => {
+        expectPeerMessageError(
+            () => decodePeerMessage(new Uint8Array([0, 0, 0, 1, 99])),
+            PeerMessageErrorCode.UNKNOWN_MESSAGE_ID,
+        );
+    });
+
+    test('roundtrips payload messages', () => {
+        const messages = [
+            { type: 'have', pieceIndex: 7 },
+            { type: 'bitfield', bitfield: new Uint8Array([0b10100000]) },
+            { type: 'request', pieceIndex: 7, offset: 16_384, length: 16_384 },
+            { type: 'piece', pieceIndex: 7, offset: 16_384, block: new Uint8Array([1, 2, 3]) },
+            { type: 'cancel', pieceIndex: 7, offset: 16_384, length: 16_384 },
+        ] as const;
+
+        for (const message of messages) {
+            expect(decodePeerMessage(encodePeerMessage(message))).toEqual(message);
+        }
+    });
+});

package/src/peer/messages/types.ts

@@ -0,0 +1,76 @@
+export enum PeerMessageId {
+    Choke = 0,
+    Unchoke = 1,
+    Interested = 2,
+    NotInterested = 3,
+    Have = 4,
+    Bitfield = 5,
+    Request = 6,
+    Piece = 7,
+    Cancel = 8,
+}
+
+export type KeepAliveMessage = {
+    type: 'keep-alive';
+};
+
+export type ChokeMessage = {
+    type: 'choke';
+};
+
+export type UnchokeMessage = {
+    type: 'unchoke';
+};
+
+export type InterestedMessage = {
+    type: 'interested';
+};
+
+export type NotInterestedMessage = {
+    type: 'not-interested';
+};
+
+export type HaveMessage = {
+    type: 'have';
+    pieceIndex: number;
+};
+
+export type BitfieldMessage = {
+    type: 'bitfield';
+    bitfield: Uint8Array;
+};
+
+export type RequestMessage = {
+    type: 'request';
+    pieceIndex: number;
+    offset: number;
+    length: number;
+};
+
+export type PieceMessage = {
+    type: 'piece';
+    pieceIndex: number;
+    offset: number;
+    block: Uint8Array;
+};
+
+export type CancelMessage = {
+    type: 'cancel';
+    pieceIndex: number;
+    offset: number;
+    length: number;
+};
+
+export type PeerMessage =
+    | KeepAliveMessage
+    | ChokeMessage
+    | UnchokeMessage
+    | InterestedMessage
+    | NotInterestedMessage
+    | HaveMessage
+    | BitfieldMessage
+    | RequestMessage
+    | PieceMessage
+    | CancelMessage;
+
+export { PeerMessageError, PeerMessageErrorCode } from './error';

package/src/peer/peer-id.ts

@@ -0,0 +1,9 @@
+import { ALPHABET, PEER_ID_PREFIX } from './consts';
+
+const textEncoder = new TextEncoder('utf-8');
+
+export const createPeerId = (): Uint8Array => {
+    const random = crypto.getRandomValues(new Uint8Array(12));
+    const suffix = [...random].map((byte) => ALPHABET[byte % ALPHABET.length]).join('');
+    return textEncoder.encode(`${PEER_ID_PREFIX}${suffix}`);
+};

package/src/peer/pool/index.ts

@@ -0,0 +1,301 @@
+import { PeerSession, type PeerSessionConnectOptions } from '@peer/session';
+import type { PeerInfo } from '@tracker/types';
+import { PeerPoolError, PeerPoolErrorCode } from './pool.error';
+
+const DEFAULT_MAX_CONNECTING = 20;
+const DEFAULT_CONNECT_TIMEOUT_MS = 3_000;
+
+export type PeerConnectionSession = {
+    connect(
+        infoHash: Uint8Array,
+        peerId: Uint8Array,
+        options?: PeerSessionConnectOptions,
+    ): Promise<void>;
+    close(): void;
+};
+
+export type PeerPoolOptions<TSession extends PeerConnectionSession = PeerSession> = {
+    infoHash: Uint8Array;
+    peerId: Uint8Array;
+    targetConnections: number;
+    totalPieces?: number;
+    minConnections?: number;
+    maxConnecting?: number;
+    timeoutMs?: number;
+    createSession?: (peer: PeerInfo) => TSession;
+};
+
+type NormalizedPeerPoolOptions<TSession extends PeerConnectionSession> = {
+    infoHash: Uint8Array;
+    peerId: Uint8Array;
+    targetConnections: number;
+    totalPieces?: number;
+    minConnections: number;
+    maxConnecting: number;
+    timeoutMs: number;
+    createSession: (peer: PeerInfo) => TSession;
+};
+
+export class PeerPool<TSession extends PeerConnectionSession = PeerSession> {
+    private readonly connected: TSession[] = [];
+    private readonly inFlight = new Set<TSession>();
+    private readonly sessionListeners = new Set<(session: TSession) => void>();
+    private readonly errors: unknown[] = [];
+
+    private nextPeerIndex = 0;
+    private closed = false;
+    private readySettled = false;
+    private doneSettled = false;
+
+    public readonly ready: Promise<this>;
+    public readonly done: Promise<TSession[]>;
+
+    private resolveReady!: (pool: this) => void;
+    private rejectReady!: (error: unknown) => void;
+    private resolveDone!: (sessions: TSession[]) => void;
+    private rejectDone!: (error: unknown) => void;
+
+    public constructor(
+        private readonly peers: PeerInfo[],
+        private readonly options: NormalizedPeerPoolOptions<TSession>,
+    ) {
+        this.ready = new Promise((resolve, reject) => {
+            this.resolveReady = resolve;
+            this.rejectReady = reject;
+        });
+
+        this.done = new Promise((resolve, reject) => {
+            this.resolveDone = resolve;
+            this.rejectDone = reject;
+        });
+        void this.done.catch(() => undefined);
+    }
+
+    public start(): void {
+        this.resolveReadyIfNeeded();
+        this.connectNext();
+        this.finishIfDone();
+    }
+
+    public get size(): number {
+        return this.connected.length;
+    }
+
+    public get connecting(): number {
+        return this.inFlight.size;
+    }
+
+    public get attempted(): number {
+        return this.nextPeerIndex;
+    }
+
+    public get failed(): number {
+        return this.errors.length;
+    }
+
+    public get totalPeers(): number {
+        return this.peers.length;
+    }
+
+    public get targetConnections(): number {
+        return this.options.targetConnections;
+    }
+
+    public get sessions(): TSession[] {
+        return [...this.connected];
+    }
+
+    public onSession(callback: (session: TSession) => void): () => void {
+        this.sessionListeners.add(callback);
+        for (const session of this.connected) callback(session);
+
+        return () => {
+            this.sessionListeners.delete(callback);
+        };
+    }
+
+    public close(): void {
+        if (this.closed) return;
+
+        this.closed = true;
+        for (const session of this.connected) session.close();
+        for (const session of this.inFlight) session.close();
+        this.inFlight.clear();
+        this.resolveReadyIfNeeded();
+        this.resolveDoneIfNeeded();
+    }
+
+    private connectNext(): void {
+        if (this.closed) return;
+
+        while (
+            this.inFlight.size < this.options.maxConnecting &&
+            this.connected.length + this.inFlight.size < this.options.targetConnections &&
+            this.nextPeerIndex < this.peers.length
+        ) {
+            const peer = this.peers[this.nextPeerIndex]!;
+            this.nextPeerIndex += 1;
+
+            const session = this.options.createSession(peer);
+            this.inFlight.add(session);
+
+            void session
+                .connect(this.options.infoHash, this.options.peerId, {
+                    timeoutMs: this.options.timeoutMs,
+                    totalPieces: this.options.totalPieces,
+                })
+                .then(() => this.handleConnected(session))
+                .catch((error) => this.handleFailed(session, error));
+        }
+    }
+
+    private handleConnected(session: TSession): void {
+        this.inFlight.delete(session);
+
+        if (this.closed) {
+            session.close();
+            this.finishIfDone();
+            return;
+        }
+
+        this.connected.push(session);
+        for (const listener of this.sessionListeners) listener(session);
+
+        this.resolveReadyIfNeeded();
+        this.connectNext();
+        this.finishIfDone();
+    }
+
+    private handleFailed(session: TSession, error: unknown): void {
+        this.inFlight.delete(session);
+        session.close();
+        this.errors.push(error);
+
+        this.connectNext();
+        this.finishIfDone();
+    }
+
+    private finishIfDone(): void {
+        if (this.doneSettled) return;
+
+        if (this.connected.length >= this.options.targetConnections) {
+            this.doneSettled = true;
+            this.resolveReadyIfNeeded();
+            this.resolveDone(this.sessions);
+            return;
+        }
+
+        if (this.inFlight.size > 0 || this.nextPeerIndex < this.peers.length) return;
+
+        this.doneSettled = true;
+
+        if (this.connected.length >= this.options.minConnections) {
+            this.resolveReadyIfNeeded();
+            this.resolveDone(this.sessions);
+            return;
+        }
+
+        const error = new PeerPoolError(
+            PeerPoolErrorCode.NO_CONNECTABLE_PEERS,
+            'Not enough connectable peers',
+            this.errors,
+        );
+        for (const session of this.connected) session.close();
+        this.rejectReadyIfNeeded(error);
+        this.rejectDone(error);
+    }
+
+    private resolveReadyIfNeeded(): void {
+        if (this.readySettled || this.connected.length < this.options.minConnections) return;
+
+        this.readySettled = true;
+        this.resolveReady(this);
+    }
+
+    private rejectReadyIfNeeded(error: unknown): void {
+        if (this.readySettled) return;
+
+        this.readySettled = true;
+        this.rejectReady(error);
+    }
+
+    private resolveDoneIfNeeded(): void {
+        if (this.doneSettled) return;
+
+        this.doneSettled = true;
+        this.resolveDone(this.sessions);
+    }
+}
+
+export const openPeerPool = async <TSession extends PeerConnectionSession = PeerSession>(
+    peers: PeerInfo[],
+    options: PeerPoolOptions<TSession>,
+): Promise<PeerPool<TSession>> => {
+    const normalizedOptions = normalizeOptions(options);
+
+    if (peers.length === 0 && normalizedOptions.minConnections > 0) {
+        throw new PeerPoolError(PeerPoolErrorCode.NO_PEERS, 'No peers to connect to');
+    }
+
+    const pool = new PeerPool(peers, normalizedOptions);
+    pool.start();
+    return await pool.ready;
+};
+
+export const connectToPeers = async <TSession extends PeerConnectionSession = PeerSession>(
+    peers: PeerInfo[],
+    options: PeerPoolOptions<TSession>,
+): Promise<TSession[]> => {
+    const pool = await openPeerPool(peers, options);
+    return await pool.done;
+};
+
+const normalizeOptions = <TSession extends PeerConnectionSession>(
+    options: PeerPoolOptions<TSession>,
+): NormalizedPeerPoolOptions<TSession> => {
+    const targetConnections = assertPositiveInteger(options.targetConnections, 'targetConnections');
+    const minConnections = assertNonNegativeInteger(options.minConnections ?? 1, 'minConnections');
+    if (minConnections > targetConnections) {
+        throw new PeerPoolError(
+            PeerPoolErrorCode.INVALID_OPTION,
+            'minConnections cannot be greater than targetConnections',
+        );
+    }
+
+    return {
+        infoHash: options.infoHash,
+        peerId: options.peerId,
+        targetConnections,
+        totalPieces: options.totalPieces,
+        minConnections,
+        maxConnecting: Math.max(1, options.maxConnecting ?? DEFAULT_MAX_CONNECTING),
+        timeoutMs: options.timeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+        createSession:
+            options.createSession ??
+            ((peer: PeerInfo) => new PeerSession(peer) as unknown as TSession),
+    };
+};
+
+const assertPositiveInteger = (value: number, name: string): number => {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new PeerPoolError(
+            PeerPoolErrorCode.INVALID_OPTION,
+            `${name} must be a positive integer`,
+        );
+    }
+
+    return value;
+};
+
+const assertNonNegativeInteger = (value: number, name: string): number => {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new PeerPoolError(
+            PeerPoolErrorCode.INVALID_OPTION,
+            `${name} must be a non-negative integer`,
+        );
+    }
+
+    return value;
+};
+
+export { PeerPoolError, PeerPoolErrorCode } from './pool.error';

package/src/peer/pool/pool.error.ts

@@ -0,0 +1,17 @@
+import { BunTorrentError } from '@utils/errors';
+
+export enum PeerPoolErrorCode {
+    INVALID_OPTION = 'PEER_POOL_INVALID_OPTION',
+    NO_CONNECTABLE_PEERS = 'PEER_POOL_NO_CONNECTABLE_PEERS',
+    NO_PEERS = 'PEER_POOL_NO_PEERS',
+}
+
+export class PeerPoolError extends BunTorrentError {
+    constructor(
+        code: PeerPoolErrorCode,
+        message: string,
+        public readonly causes: unknown[] = [],
+    ) {
+        super(message, code);
+    }
+}