bun-torrent 0.0.1-beta

package/src/peer/pool/pool.test.ts

@@ -0,0 +1,305 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { PeerInfo } from '@tracker/types';
+import {
+    connectToPeers,
+    openPeerPool,
+    PeerPoolError,
+    PeerPoolErrorCode,
+    type PeerConnectionSession,
+} from '.';
+import { BunTorrentError } from '@utils/errors';
+
+const bytes20 = new Uint8Array(20);
+
+describe('openPeerPool', () => {
+    test('returns as soon as minConnections is satisfied and keeps refilling in the background', async () => {
+        const peers = makePeers(5);
+        const activity = { current: 0, max: 0 };
+        const outcomes = new Map([
+            ['10.0.0.1', { delayMs: 1, succeeds: true }],
+            ['10.0.0.2', { delayMs: 5, succeeds: false }],
+            ['10.0.0.3', { delayMs: 8, succeeds: true }],
+            ['10.0.0.4', { delayMs: 10, succeeds: true }],
+            ['10.0.0.5', { delayMs: 1, succeeds: true }],
+        ]);
+
+        const pool = await openPeerPool(peers, {
+            infoHash: bytes20,
+            peerId: bytes20,
+            targetConnections: 3,
+            minConnections: 1,
+            maxConnecting: 2,
+            createSession(peer) {
+                return new FakeSession(peer, outcomes.get(peer.ip)!, activity);
+            },
+        });
+
+        expect(pool.size).toBe(1);
+        expect(activity.max).toBeLessThanOrEqual(2);
+
+        const sessions = await pool.done;
+        expect(sessions).toHaveLength(3);
+        expect(sessions.map((session) => session.peer.ip)).toEqual([
+            '10.0.0.1',
+            '10.0.0.3',
+            '10.0.0.4',
+        ]);
+    });
+
+    test('notifies listeners when new sessions are added', async () => {
+        const seen: string[] = [];
+        const pool = await openPeerPool(makePeers(3), {
+            infoHash: bytes20,
+            peerId: bytes20,
+            targetConnections: 2,
+            minConnections: 1,
+            maxConnecting: 1,
+            createSession(peer) {
+                return new FakeSession(
+                    peer,
+                    { delayMs: peer.ip === '10.0.0.1' ? 1 : 3, succeeds: true },
+                    { current: 0, max: 0 },
+                );
+            },
+        });
+
+        const off = pool.onSession((session) => seen.push(session.peer.ip));
+        await pool.done;
+        off();
+
+        expect(seen).toEqual(['10.0.0.1', '10.0.0.2']);
+    });
+
+    test('rejects when minConnections cannot be satisfied', async () => {
+        expect(
+            openPeerPool(makePeers(2), {
+                infoHash: bytes20,
+                peerId: bytes20,
+                targetConnections: 2,
+                minConnections: 1,
+                maxConnecting: 2,
+                createSession(peer) {
+                    return new FakeSession(
+                        peer,
+                        { delayMs: 1, succeeds: false },
+                        { current: 0, max: 0 },
+                    );
+                },
+            }),
+        ).rejects.toThrow('Not enough connectable peers');
+
+        expect(
+            openPeerPool(makePeers(2), {
+                infoHash: bytes20,
+                peerId: bytes20,
+                targetConnections: 2,
+                minConnections: 1,
+                maxConnecting: 2,
+                createSession(peer) {
+                    return new FakeSession(
+                        peer,
+                        { delayMs: 1, succeeds: false },
+                        { current: 0, max: 0 },
+                    );
+                },
+            }),
+        ).rejects.toMatchObject({
+            code: PeerPoolErrorCode.NO_CONNECTABLE_PEERS,
+        });
+    });
+
+    test('allows zero minimum connections and reports failed attempts through stats', async () => {
+        const pool = await openPeerPool(makePeers(2), {
+            infoHash: bytes20,
+            peerId: bytes20,
+            targetConnections: 2,
+            minConnections: 0,
+            maxConnecting: 2,
+            createSession(peer) {
+                return new FakeSession(
+                    peer,
+                    { delayMs: 1, succeeds: false },
+                    { current: 0, max: 0 },
+                );
+            },
+        });
+
+        expect(pool.size).toBe(0);
+
+        const sessions = await pool.done;
+        expect(sessions).toEqual([]);
+        expect(pool.failed).toBe(2);
+    });
+
+    test('allows empty peer lists when zero connections are required', async () => {
+        const pool = await openPeerPool([], {
+            infoHash: bytes20,
+            peerId: bytes20,
+            targetConnections: 2,
+            minConnections: 0,
+        });
+
+        expect(pool.totalPeers).toBe(0);
+        expect(await pool.done).toEqual([]);
+    });
+
+    test('passes totalPieces to peer sessions', async () => {
+        const pool = await openPeerPool(makePeers(1), {
+            infoHash: bytes20,
+            peerId: bytes20,
+            targetConnections: 1,
+            minConnections: 1,
+            totalPieces: 923,
+            createSession(peer) {
+                return new FakeSession(
+                    peer,
+                    { delayMs: 1, succeeds: true },
+                    { current: 0, max: 0 },
+                );
+            },
+        });
+
+        const [session] = await pool.done;
+
+        expect(session?.connectOptions?.totalPieces).toBe(923);
+    });
+});
+
+describe('connectToPeers', () => {
+    test('waits until targetConnections is reached', async () => {
+        const sessions = await connectToPeers(makePeers(3), {
+            infoHash: bytes20,
+            peerId: bytes20,
+            targetConnections: 2,
+            minConnections: 1,
+            maxConnecting: 1,
+            createSession(peer) {
+                return new FakeSession(
+                    peer,
+                    { delayMs: 1, succeeds: true },
+                    { current: 0, max: 0 },
+                );
+            },
+        });
+
+        expect(sessions).toHaveLength(2);
+    });
+
+    test('returns partial sessions when minConnections is satisfied and peers are exhausted', async () => {
+        const sessions = await connectToPeers(makePeers(3), {
+            infoHash: bytes20,
+            peerId: bytes20,
+            targetConnections: 3,
+            minConnections: 2,
+            maxConnecting: 3,
+            createSession(peer) {
+                return new FakeSession(
+                    peer,
+                    { delayMs: 1, succeeds: peer.ip !== '10.0.0.2' },
+                    { current: 0, max: 0 },
+                );
+            },
+        });
+
+        expect(sessions).toHaveLength(2);
+        expect(sessions.map((session) => session.peer.ip)).toEqual(['10.0.0.1', '10.0.0.3']);
+    });
+
+    test('rejects invalid connection counts', async () => {
+        expect(
+            connectToPeers(makePeers(1), {
+                infoHash: bytes20,
+                peerId: bytes20,
+                targetConnections: 0,
+            }),
+        ).rejects.toThrow('targetConnections must be a positive integer');
+        expect(
+            connectToPeers(makePeers(1), {
+                infoHash: bytes20,
+                peerId: bytes20,
+                targetConnections: 0,
+            }),
+        ).rejects.toBeInstanceOf(PeerPoolError);
+        expect(
+            connectToPeers(makePeers(1), {
+                infoHash: bytes20,
+                peerId: bytes20,
+                targetConnections: 0,
+            }),
+        ).rejects.toBeInstanceOf(BunTorrentError);
+
+        expect(
+            connectToPeers(makePeers(1), {
+                infoHash: bytes20,
+                peerId: bytes20,
+                targetConnections: 1,
+                minConnections: 2,
+            }),
+        ).rejects.toThrow('minConnections cannot be greater than targetConnections');
+        expect(
+            connectToPeers(makePeers(1), {
+                infoHash: bytes20,
+                peerId: bytes20,
+                targetConnections: 1,
+                minConnections: 2,
+            }),
+        ).rejects.toMatchObject({
+            code: PeerPoolErrorCode.INVALID_OPTION,
+        });
+    });
+});
+
+const makePeers = (count: number): PeerInfo[] =>
+    Array.from({ length: count }, (_, index) => ({
+        ip: `10.0.0.${index + 1}`,
+        port: 6881 + index,
+    }));
+
+class FakeSession implements PeerConnectionSession {
+    public closed = false;
+    public connectOptions: Parameters<PeerConnectionSession['connect']>[2];
+    private settled = false;
+    private rejectConnect: ((error: Error) => void) | null = null;
+    private timer: ReturnType<typeof setTimeout> | null = null;
+
+    constructor(
+        public readonly peer: PeerInfo,
+        private readonly outcome: { delayMs: number; succeeds: boolean },
+        private readonly activity: { current: number; max: number },
+    ) {}
+
+    public async connect(
+        _infoHash?: Uint8Array,
+        _peerId?: Uint8Array,
+        options?: Parameters<PeerConnectionSession['connect']>[2],
+    ): Promise<void> {
+        this.connectOptions = options;
+        this.activity.current += 1;
+        this.activity.max = Math.max(this.activity.max, this.activity.current);
+
+        return new Promise((resolve, reject) => {
+            this.rejectConnect = reject;
+            this.timer = setTimeout(() => {
+                if (this.settled) return;
+
+                this.settled = true;
+                this.activity.current -= 1;
+                if (this.outcome.succeeds) resolve();
+                else reject(new Error('Fake connect failed'));
+            }, this.outcome.delayMs);
+        });
+    }
+
+    public close(): void {
+        if (this.closed) return;
+
+        this.closed = true;
+        if (this.settled) return;
+
+        this.settled = true;
+        if (this.timer) clearTimeout(this.timer);
+        this.activity.current -= 1;
+        this.rejectConnect?.(new Error('Fake session closed'));
+    }
+}

package/src/peer/session/index.ts

@@ -0,0 +1,276 @@
+import { HANDSHAKE_LENGTH } from '@peer/consts';
+import { decodeHandshake, encodeHandshake } from '@peer/handshake';
+import { decodePeerMessage, encodePeerMessage, type PeerMessage } from '@peer/messages';
+import { PeerPieceAvailability } from '@peer/availability';
+import type { PeerInfo } from '@tracker/types';
+import { concatBytes } from '@utils/buffers';
+import { BunTorrentError } from '@utils/errors';
+import { createConnection, type Socket } from 'node:net';
+import { PeerSessionError, PeerSessionErrorCode } from './session.error';
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 5_000;
+
+export type PeerSessionConnectOptions = {
+    timeoutMs?: number;
+    totalPieces?: number;
+};
+
+export class PeerSession {
+    private peerChoking: boolean = true;
+    private peerInterested: boolean = false;
+
+    private amChoking: boolean = true;
+    private amInterested: boolean = false;
+
+    private availability = new PeerPieceAvailability(0);
+    private readonly messageListeners = new Set<(message: PeerMessage) => void>();
+    private readonly closeListeners = new Set<() => void>();
+
+    private handshakeDone: boolean = false;
+    private buffer: Uint8Array = new Uint8Array(0);
+    private socket: Socket | null = null;
+    private closed: boolean = false;
+    private rejectPendingConnect: ((error: Error) => void) | null = null;
+
+    constructor(private readonly peer: PeerInfo) {}
+
+    public async connect(
+        infoHash: Uint8Array,
+        peerId: Uint8Array,
+        options: PeerSessionConnectOptions = {},
+    ): Promise<void> {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+        this.availability = new PeerPieceAvailability(options.totalPieces ?? 0);
+
+        return new Promise((resolve, reject) => {
+            if (this.closed) {
+                reject(
+                    new PeerSessionError(
+                        PeerSessionErrorCode.CLOSED,
+                        'Peer session is already closed',
+                    ),
+                );
+                return;
+            }
+
+            let settled = false;
+
+            const timeout = setTimeout(() => {
+                rejectOnce(
+                    new PeerSessionError(
+                        PeerSessionErrorCode.CONNECT_TIMEOUT,
+                        'Peer connection timed out',
+                    ),
+                );
+            }, timeoutMs);
+
+            const resolveOnce = () => {
+                if (settled) return;
+
+                settled = true;
+                clearTimeout(timeout);
+                this.rejectPendingConnect = null;
+                resolve();
+            };
+
+            const rejectOnce = (error: unknown) => {
+                if (settled) return;
+
+                settled = true;
+                clearTimeout(timeout);
+                this.rejectPendingConnect = null;
+                this.socket?.destroy();
+                this.socket = null;
+                reject(toPeerSessionError(error));
+            };
+
+            this.rejectPendingConnect = rejectOnce;
+
+            const socket = createConnection({
+                host: this.peer.ip,
+                port: this.peer.port,
+            });
+
+            this.socket = socket;
+            socket.setTimeout(timeoutMs);
+
+            socket.once('connect', () => {
+                if (this.closed) {
+                    socket.destroy();
+                    return;
+                }
+
+                socket.write(encodeHandshake({ infoHash, peerId }));
+            });
+
+            socket.on('data', (data) => {
+                try {
+                    const bytes =
+                        typeof data === 'string'
+                            ? new TextEncoder().encode(data)
+                            : new Uint8Array(data);
+                    this.handleData(bytes, infoHash, resolveOnce, rejectOnce);
+                } catch (error) {
+                    rejectOnce(error);
+                }
+            });
+
+            socket.once('timeout', () =>
+                rejectOnce(
+                    new PeerSessionError(
+                        PeerSessionErrorCode.CONNECT_TIMEOUT,
+                        'Peer connection timed out',
+                    ),
+                ),
+            );
+            socket.once('error', rejectOnce);
+            socket.once('close', () => {
+                this.socket = null;
+                this.notifyClosed();
+                if (!this.handshakeDone) {
+                    rejectOnce(
+                        new PeerSessionError(
+                            PeerSessionErrorCode.SOCKET_CLOSED_BEFORE_HANDSHAKE,
+                            'Socket closed before handshake',
+                        ),
+                    );
+                }
+            });
+        });
+    }
+
+    public close(): void {
+        if (this.closed) return;
+
+        this.closed = true;
+        this.socket?.destroy();
+        this.socket = null;
+        this.rejectPendingConnect?.(
+            new PeerSessionError(PeerSessionErrorCode.CLOSED, 'Peer session closed'),
+        );
+        this.notifyClosed();
+    }
+
+    public get peerAvailability(): PeerPieceAvailability {
+        return this.availability;
+    }
+
+    public get choked(): boolean {
+        return this.peerChoking;
+    }
+
+    public get interested(): boolean {
+        return this.amInterested;
+    }
+
+    public onMessage(callback: (message: PeerMessage) => void): () => void {
+        this.messageListeners.add(callback);
+
+        return () => {
+            this.messageListeners.delete(callback);
+        };
+    }
+
+    public onClose(callback: () => void): () => void {
+        this.closeListeners.add(callback);
+
+        return () => {
+            this.closeListeners.delete(callback);
+        };
+    }
+
+    public sendMessage(message: PeerMessage): void {
+        if (this.closed || !this.socket) {
+            throw new PeerSessionError(PeerSessionErrorCode.CLOSED, 'Peer session closed');
+        }
+
+        if (message.type === 'interested') this.amInterested = true;
+        if (message.type === 'not-interested') this.amInterested = false;
+
+        this.socket.write(encodePeerMessage(message));
+    }
+
+    private handleData(
+        incoming: Uint8Array,
+        infoHash: Uint8Array,
+        resolve: () => void,
+        reject: (err: Error) => void,
+    ) {
+        this.buffer = concatBytes([this.buffer, incoming]);
+
+        if (!this.handshakeDone) {
+            if (this.buffer.length < HANDSHAKE_LENGTH) return;
+
+            const handshake = decodeHandshake(this.buffer.slice(0, HANDSHAKE_LENGTH));
+
+            if (!handshake.infoHash.every((b, i) => b === infoHash[i])) {
+                reject(
+                    new PeerSessionError(
+                        PeerSessionErrorCode.INFO_HASH_MISMATCH,
+                        'Handshake info hash does not match torrent info hash',
+                    ),
+                );
+                return;
+            }
+
+            this.handshakeDone = true;
+            this.buffer = this.buffer.slice(HANDSHAKE_LENGTH);
+            resolve();
+        }
+
+        while (this.handshakeDone && this.buffer.byteLength >= 4) {
+            const frameLength = new DataView(
+                this.buffer.buffer,
+                this.buffer.byteOffset,
+                4,
+            ).getUint32(0, false);
+            const totalLength = 4 + frameLength;
+
+            if (this.buffer.byteLength < totalLength) return;
+
+            const frame = this.buffer.slice(0, totalLength);
+            this.buffer = this.buffer.slice(totalLength);
+            this.handleMessage(decodePeerMessage(frame));
+        }
+    }
+
+    private handleMessage(message: PeerMessage): void {
+        switch (message.type) {
+            case 'choke':
+                this.peerChoking = true;
+                break;
+            case 'unchoke':
+                this.peerChoking = false;
+                break;
+            case 'interested':
+                this.peerInterested = true;
+                break;
+            case 'not-interested':
+                this.peerInterested = false;
+                break;
+            case 'bitfield':
+                this.availability.setBitfield(message.bitfield);
+                break;
+            case 'have':
+                this.availability.markHave(message.pieceIndex);
+                break;
+        }
+
+        for (const listener of this.messageListeners) listener(message);
+    }
+
+    private notifyClosed(): void {
+        for (const listener of this.closeListeners) listener();
+    }
+}
+
+const toPeerSessionError = (error: unknown): Error => {
+    if (error instanceof BunTorrentError) return error;
+    if (error instanceof Error) {
+        return new PeerSessionError(PeerSessionErrorCode.SOCKET_ERROR, error.message, error);
+    }
+
+    return new PeerSessionError(PeerSessionErrorCode.SOCKET_ERROR, String(error), error);
+};
+
+export { PeerSessionError, PeerSessionErrorCode } from './session.error';

package/src/peer/session/session.error.ts

@@ -0,0 +1,19 @@
+import { BunTorrentError } from '@utils/errors';
+
+export enum PeerSessionErrorCode {
+    CLOSED = 'PEER_SESSION_CLOSED',
+    CONNECT_TIMEOUT = 'PEER_SESSION_CONNECT_TIMEOUT',
+    INFO_HASH_MISMATCH = 'PEER_SESSION_INFO_HASH_MISMATCH',
+    SOCKET_CLOSED_BEFORE_HANDSHAKE = 'PEER_SESSION_SOCKET_CLOSED_BEFORE_HANDSHAKE',
+    SOCKET_ERROR = 'PEER_SESSION_SOCKET_ERROR',
+}
+
+export class PeerSessionError extends BunTorrentError {
+    constructor(
+        code: PeerSessionErrorCode,
+        message: string,
+        public override readonly cause?: unknown,
+    ) {
+        super(message, code);
+    }
+}

package/src/peer/session/session.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from 'bun:test';
+
+import { encodeHandshake } from '@peer/handshake';
+import { decodePeerMessage, encodePeerMessage } from '@peer/messages';
+import { PeerPieceAvailability } from '@peer/availability';
+import { BunTorrentError } from '@utils/errors';
+import { concatBytes } from '@utils/buffers';
+import { PeerSession, PeerSessionError, PeerSessionErrorCode } from '.';
+
+const bytes20 = new Uint8Array(20);
+const peerId = new Uint8Array(20).fill(1);
+
+describe('PeerSession', () => {
+    test('rejects connecting a closed session with a peer session error', async () => {
+        const session = new PeerSession({ ip: '127.0.0.1', port: 1 });
+        session.close();
+
+        expect(session.connect(bytes20, bytes20)).rejects.toBeInstanceOf(PeerSessionError);
+        expect(session.connect(bytes20, bytes20)).rejects.toBeInstanceOf(BunTorrentError);
+        expect(session.connect(bytes20, bytes20)).rejects.toMatchObject({
+            code: PeerSessionErrorCode.CLOSED,
+        });
+    });
+
+    test('tracks peer availability and choke state from incoming messages', async () => {
+        const session = new PeerSession({ ip: '127.0.0.1', port: 1 });
+        const testSession = asTestableSession(session);
+        const messages: string[] = [];
+        session.onMessage((message) => messages.push(message.type));
+
+        testSession.availability = new PeerPieceAvailability(10);
+        testSession.handleData(
+            concatBytes([
+                encodeHandshake({ infoHash: bytes20, peerId }),
+                encodePeerMessage({
+                    type: 'bitfield',
+                    bitfield: new Uint8Array([0b1010_0001, 0b1000_0000]),
+                }),
+                encodePeerMessage({ type: 'have', pieceIndex: 9 }),
+                encodePeerMessage({ type: 'unchoke' }),
+            ]),
+            bytes20,
+            () => undefined,
+            (error) => {
+                throw error;
+            },
+        );
+
+        expect(messages).toEqual(['bitfield', 'have', 'unchoke']);
+        expect(session.peerAvailability.toPieceIndexes()).toEqual([0, 2, 7, 8, 9]);
+        expect(session.choked).toBe(false);
+    });
+
+    test('sends encoded peer messages after connecting', async () => {
+        const session = new PeerSession({ ip: '127.0.0.1', port: 1 });
+        const testSession = asTestableSession(session);
+        const received = new Uint8ArrayCollector();
+
+        testSession.socket = {
+            write(bytes: Uint8Array) {
+                received.push(bytes);
+                return true;
+            },
+        };
+
+        session.sendMessage({ type: 'interested' });
+
+        expect(decodePeerMessage(received.bytes())).toEqual({ type: 'interested' });
+        expect(session.interested).toBe(true);
+    });
+
+    test('notifies close listeners once when closed explicitly', () => {
+        const session = new PeerSession({ ip: '127.0.0.1', port: 1 });
+        let closeCount = 0;
+        session.onClose(() => {
+            closeCount += 1;
+        });
+
+        session.close();
+        session.close();
+
+        expect(closeCount).toBe(1);
+    });
+});
+
+type TestablePeerSession = {
+    availability: PeerPieceAvailability;
+    handleData(
+        incoming: Uint8Array,
+        infoHash: Uint8Array,
+        resolve: () => void,
+        reject: (error: Error) => void,
+    ): void;
+    socket: { write(bytes: Uint8Array): boolean } | null;
+};
+
+const asTestableSession = (session: PeerSession): TestablePeerSession =>
+    session as unknown as TestablePeerSession;
+
+class Uint8ArrayCollector {
+    private chunks: Uint8Array[] = [];
+
+    public push(bytes: Uint8Array): void {
+        this.chunks.push(bytes);
+    }
+
+    public bytes(): Uint8Array {
+        return concatBytes(this.chunks);
+    }
+}