bun-torrent 0.0.1-beta

package/src/tracker/http.ts

@@ -0,0 +1,137 @@
+import { decodeBencode, type BValue } from '@torrent/bencode';
+import type { TorrentMetadata } from '@torrent/types';
+import { DEFAULT_ANNOUNCE_PORT, type AnnounceOptions, type PeerInfo } from './types';
+import { TrackerError, TrackerErrorCode } from './tracker.error';
+
+const DEFAULT_HTTP_TRACKER_TIMEOUT_MS = 5_000;
+const textDecoder = new TextDecoder();
+
+export const announceHttp = async (
+    tracker: string,
+    meta: TorrentMetadata,
+    peerId: Uint8Array,
+    options: AnnounceOptions = {},
+): Promise<PeerInfo[]> => {
+    const controller = new AbortController();
+    const timeout = setTimeout(
+        () => controller.abort(),
+        options.timeoutMs ?? DEFAULT_HTTP_TRACKER_TIMEOUT_MS,
+    );
+
+    let response: Response;
+    try {
+        response = await fetch(buildHttpAnnounceUrl(tracker, meta, peerId, options), {
+            signal: controller.signal,
+        });
+    } catch (error) {
+        const code = controller.signal.aborted
+            ? TrackerErrorCode.ANNOUNCE_TIMEOUT
+            : TrackerErrorCode.HTTP_REQUEST_FAILED;
+        const message = controller.signal.aborted
+            ? 'HTTP tracker announce timeout'
+            : 'HTTP tracker request failed';
+
+        throw new TrackerError(code, message, [error]);
+    } finally {
+        clearTimeout(timeout);
+    }
+
+    if (!response.ok) {
+        throw new TrackerError(
+            TrackerErrorCode.HTTP_REQUEST_FAILED,
+            `HTTP tracker request failed with status ${response.status}`,
+        );
+    }
+
+    return parseHttpAnnounceResponse(new Uint8Array(await response.arrayBuffer()));
+};
+
+export const parseHttpAnnounceResponse = (data: Uint8Array): PeerInfo[] => {
+    let response: BValue;
+    try {
+        response = decodeBencode(data);
+    } catch (error) {
+        throw new TrackerError(
+            TrackerErrorCode.HTTP_RESPONSE_INVALID,
+            'HTTP tracker response must be bencoded',
+            [error],
+        );
+    }
+
+    if (!(response instanceof Map)) {
+        throw new TrackerError(
+            TrackerErrorCode.HTTP_RESPONSE_INVALID,
+            'HTTP tracker response must be a dictionary',
+        );
+    }
+
+    const failureReason = response.get('failure reason');
+    if (failureReason instanceof Uint8Array) {
+        throw new TrackerError(
+            TrackerErrorCode.FAILURE_RESPONSE,
+            `HTTP tracker failure response: ${textDecoder.decode(failureReason)}`,
+        );
+    }
+
+    const peersValue = response.get('peers');
+    if (!(peersValue instanceof Uint8Array)) {
+        throw new TrackerError(
+            TrackerErrorCode.HTTP_RESPONSE_INVALID,
+            'HTTP tracker response must include compact peers',
+        );
+    }
+
+    const peers = parseCompactPeers(peersValue);
+    if (peers.length === 0) {
+        throw new TrackerError(TrackerErrorCode.NO_PEERS, 'HTTP tracker returned no peers');
+    }
+
+    return peers;
+};
+
+const buildHttpAnnounceUrl = (
+    tracker: string,
+    meta: TorrentMetadata,
+    peerId: Uint8Array,
+    options: AnnounceOptions,
+): string => {
+    const url = new URL(tracker);
+    url.hash = '';
+
+    const params = [
+        `info_hash=${percentEncodeBytes(meta.infoHash)}`,
+        `peer_id=${percentEncodeBytes(peerId)}`,
+        `port=${options.announcePort ?? DEFAULT_ANNOUNCE_PORT}`,
+        'uploaded=0',
+        'downloaded=0',
+        `left=${meta.length}`,
+        'compact=1',
+        'event=started',
+    ];
+
+    return `${url.toString()}${url.search ? '&' : '?'}${params.join('&')}`;
+};
+
+const parseCompactPeers = (data: Uint8Array): PeerInfo[] => {
+    if (data.byteLength % 6 !== 0) {
+        throw new TrackerError(
+            TrackerErrorCode.HTTP_RESPONSE_INVALID,
+            'Compact peer list must be made of 6-byte peers',
+        );
+    }
+
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const peers: PeerInfo[] = [];
+
+    for (let offset = 0; offset < data.byteLength; offset += 6) {
+        peers.push({
+            ip: `${data[offset]}.${data[offset + 1]}.${data[offset + 2]}.${data[offset + 3]}`,
+            port: view.getUint16(offset + 4, false),
+        });
+    }
+
+    return peers;
+};
+
+const percentEncodeBytes = (bytes: Uint8Array): string =>
+    [...bytes].map((byte) => `%${byte.toString(16).padStart(2, '0').toUpperCase()}`).join('');

package/src/tracker/index.ts

@@ -0,0 +1,93 @@
+import type { TorrentMetadata } from '@torrent/types';
+import { announceHttp } from './http';
+import { DEFAULT_ANNOUNCE_PORT, type AnnounceTracker, type PeerInfo } from './types';
+import { announceUdp } from './udp';
+import { TrackerError, TrackerErrorCode } from './tracker.error';
+
+const DEFAULT_TRACKER_TIMEOUT_MS = 5_000;
+
+export const trackPeers = async ({
+    meta,
+    peerId,
+    announcePort = DEFAULT_ANNOUNCE_PORT,
+    timeoutMs = DEFAULT_TRACKER_TIMEOUT_MS,
+    udp = announceUdp,
+    http = announceHttp,
+}: {
+    meta: TorrentMetadata;
+    peerId: Uint8Array;
+    announcePort?: number;
+    timeoutMs?: number;
+    udp?: AnnounceTracker;
+    http?: AnnounceTracker;
+}): Promise<PeerInfo[]> => {
+    validateAnnouncePort(announcePort);
+
+    const trackers = [meta.announce, ...meta.announceList.flat()].filter(Boolean) as string[];
+    const announceRequests = trackers.flatMap((tracker) => {
+        if (tracker.startsWith('udp://')) return [{ tracker, announce: udp }];
+        if (tracker.startsWith('http://') || tracker.startsWith('https://')) {
+            return [{ tracker, announce: http }];
+        }
+        return [];
+    });
+
+    if (announceRequests.length === 0) {
+        throw new TrackerError(
+            TrackerErrorCode.NO_SUPPORTED_TRACKERS,
+            'No supported trackers found',
+        );
+    }
+
+    const results = await Promise.allSettled(
+        announceRequests.map(({ tracker, announce }) =>
+            announce(tracker, meta, peerId, { announcePort, timeoutMs }),
+        ),
+    );
+
+    const peers = results.flatMap((result) => (result.status === 'fulfilled' ? result.value : []));
+    const dedupedPeers = dedupePeers(peers);
+
+    if (dedupedPeers.length > 0) {
+        return dedupedPeers;
+    }
+
+    const causes = results.flatMap((result) =>
+        result.status === 'rejected' ? [result.reason] : [],
+    );
+
+    if (causes.every(isTrackerNoPeersError)) {
+        throw new TrackerError(TrackerErrorCode.NO_PEERS, 'Trackers returned no peers', causes);
+    }
+
+    throw new TrackerError(
+        TrackerErrorCode.ANNOUNCE_FAILED,
+        'All tracker announces failed',
+        causes,
+    );
+};
+
+const dedupePeers = (peers: PeerInfo[]) => {
+    const included = new Set();
+    return peers.filter((p) => {
+        const key = p.ip + ':' + p.port;
+        if (included.has(key)) return false;
+        included.add(key);
+        return true;
+    });
+};
+
+const isTrackerNoPeersError = (error: unknown): error is TrackerError =>
+    error instanceof TrackerError && error.code === TrackerErrorCode.NO_PEERS;
+
+const validateAnnouncePort = (port: number): void => {
+    if (Number.isInteger(port) && port >= 1 && port <= 65_535) return;
+
+    throw new TrackerError(
+        TrackerErrorCode.INVALID_PORT,
+        'Announce port must be an integer between 1 and 65535',
+    );
+};
+
+export { TrackerError, TrackerErrorCode } from './tracker.error';
+export type { PeerInfo } from './types';

package/src/tracker/tracker.error.ts

@@ -0,0 +1,26 @@
+import { BunTorrentError } from '@utils/errors';
+
+export enum TrackerErrorCode {
+    ANNOUNCE_FAILED = 'TRACKER_ANNOUNCE_FAILED',
+    ANNOUNCE_RESPONSE_TOO_SHORT = 'TRACKER_ANNOUNCE_RESPONSE_TOO_SHORT',
+    ANNOUNCE_TIMEOUT = 'TRACKER_ANNOUNCE_TIMEOUT',
+    CONNECT_RESPONSE_TOO_SHORT = 'TRACKER_CONNECT_RESPONSE_TOO_SHORT',
+    FAILURE_RESPONSE = 'TRACKER_FAILURE_RESPONSE',
+    HTTP_REQUEST_FAILED = 'TRACKER_HTTP_REQUEST_FAILED',
+    HTTP_RESPONSE_INVALID = 'TRACKER_HTTP_RESPONSE_INVALID',
+    INVALID_ACTION = 'TRACKER_INVALID_ACTION',
+    INVALID_PORT = 'TRACKER_INVALID_PORT',
+    NO_PEERS = 'TRACKER_NO_PEERS',
+    NO_SUPPORTED_TRACKERS = 'TRACKER_NO_SUPPORTED_TRACKERS',
+    TRANSACTION_ID_MISMATCH = 'TRACKER_TRANSACTION_ID_MISMATCH',
+}
+
+export class TrackerError extends BunTorrentError {
+    constructor(
+        code: TrackerErrorCode,
+        message: string,
+        public readonly causes: unknown[] = [],
+    ) {
+        super(message, code);
+    }
+}

package/src/tracker/types.ts

@@ -0,0 +1,17 @@
+import type { TorrentMetadata } from '@torrent/types';
+
+export type PeerInfo = { ip: string; port: number };
+
+export const DEFAULT_ANNOUNCE_PORT = 6881;
+
+export type AnnounceOptions = {
+    announcePort?: number;
+    timeoutMs?: number;
+};
+
+export type AnnounceTracker = (
+    tracker: string,
+    meta: TorrentMetadata,
+    peerId: Uint8Array,
+    options?: AnnounceOptions,
+) => Promise<PeerInfo[]>;

package/src/tracker/udp.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { TorrentMetadata } from '@torrent/types';
+import { trackPeers, TrackerError, TrackerErrorCode } from './index';
+import type { AnnounceOptions } from './types';
+
+const peerId = new Uint8Array(20);
+
+const makeMeta = ({
+    announce,
+    announceList = [],
+}: {
+    announce?: string;
+    announceList?: string[][];
+} = {}): TorrentMetadata => ({
+    announce,
+    announceList,
+    infoHash: new Uint8Array(20),
+    name: 'file.bin',
+    pieceLength: 16_384,
+    pieces: [new Uint8Array(20)],
+    length: 12_345,
+    files: [{ path: ['file.bin'], length: 12_345, offset: 0 }],
+});
+
+describe('trackPeers', () => {
+    test('rejects when there are no supported trackers', async () => {
+        await expect(
+            trackPeers({
+                meta: makeMeta({
+                    announce: 'wss://tracker.test/announce',
+                    announceList: [['ftp://backup.test/announce']],
+                }),
+                peerId,
+            }),
+        ).rejects.toMatchObject({
+            code: TrackerErrorCode.NO_SUPPORTED_TRACKERS,
+        });
+    });
+
+    test('rejects with announce failure causes when all trackers fail', async () => {
+        const causes = [new Error('dns failed'), new Error('timeout')];
+        const calls: string[] = [];
+
+        try {
+            await trackPeers({
+                meta: makeMeta({
+                    announce: 'udp://tracker-a.test:80/announce',
+                    announceList: [['https://tracker-b.test/announce']],
+                }),
+                peerId,
+                udp: async (tracker) => {
+                    calls.push(tracker);
+                    throw causes[0];
+                },
+                http: async (tracker) => {
+                    calls.push(tracker);
+                    throw causes[1];
+                },
+            });
+            throw new Error('Expected trackPeers to throw');
+        } catch (error) {
+            expect(error).toBeInstanceOf(TrackerError);
+            expect((error as TrackerError).code).toBe(TrackerErrorCode.ANNOUNCE_FAILED);
+            expect((error as TrackerError).causes).toEqual(causes);
+            expect(calls).toEqual([
+                'udp://tracker-a.test:80/announce',
+                'https://tracker-b.test/announce',
+            ]);
+        }
+    });
+
+    test('rejects with no peers when trackers respond without peers', async () => {
+        const causes = [
+            new TrackerError(TrackerErrorCode.NO_PEERS, 'Tracker returned no peers'),
+            new TrackerError(TrackerErrorCode.NO_PEERS, 'Tracker returned no peers'),
+        ];
+        let callCount = 0;
+
+        await expect(
+            trackPeers({
+                meta: makeMeta({
+                    announce: 'udp://tracker-a.test:80/announce',
+                    announceList: [['udp://tracker-b.test:80/announce']],
+                }),
+                peerId,
+                udp: async () => {
+                    throw causes[callCount++];
+                },
+            }),
+        ).rejects.toMatchObject({
+            code: TrackerErrorCode.NO_PEERS,
+            causes,
+        });
+    });
+
+    test('dedupes peers from successful trackers', async () => {
+        const peers = await trackPeers({
+            meta: makeMeta({
+                announce: 'udp://tracker-a.test:80/announce',
+                announceList: [['https://tracker-b.test/announce']],
+            }),
+            peerId,
+            udp: async () => [
+                { ip: '127.0.0.1', port: 6881 },
+                { ip: '127.0.0.1', port: 6881 },
+            ],
+            http: async () => [
+                { ip: '127.0.0.1', port: 6881 },
+                { ip: '127.0.0.2', port: 6881 },
+            ],
+        });
+
+        expect(peers).toEqual([
+            { ip: '127.0.0.1', port: 6881 },
+            { ip: '127.0.0.2', port: 6881 },
+        ]);
+    });
+
+    test('passes announcePort separately from tracker URL ports', async () => {
+        const optionsSeen: AnnounceOptions[] = [];
+
+        const peers = await trackPeers({
+            meta: makeMeta({
+                announce: 'udp://tracker-a.test:6969/announce',
+                announceList: [['https://tracker-b.test:443/announce']],
+            }),
+            peerId,
+            announcePort: 51413,
+            udp: async (_tracker, _meta, _peerId, options) => {
+                optionsSeen.push(options ?? {});
+                return [{ ip: '127.0.0.1', port: 6881 }];
+            },
+            http: async (_tracker, _meta, _peerId, options) => {
+                optionsSeen.push(options ?? {});
+                return [{ ip: '127.0.0.2', port: 6881 }];
+            },
+        });
+
+        expect(peers).toHaveLength(2);
+        expect(optionsSeen.map((options) => options.announcePort)).toEqual([51413, 51413]);
+    });
+
+    test('rejects invalid announce ports', async () => {
+        await expect(
+            trackPeers({
+                meta: makeMeta({ announce: 'udp://tracker.test:6969/announce' }),
+                peerId,
+                announcePort: 70_000,
+            }),
+        ).rejects.toMatchObject({
+            code: TrackerErrorCode.INVALID_PORT,
+        });
+    });
+});

package/src/tracker/udp.ts

@@ -0,0 +1,234 @@
+import type { TorrentMetadata } from '@torrent/types';
+import { lookup } from 'dns/promises';
+import { DEFAULT_ANNOUNCE_PORT, type AnnounceOptions, type PeerInfo } from './types';
+import { TrackerError, TrackerErrorCode } from './tracker.error';
+
+export const announceUdp = async (
+    tracker: string,
+    meta: TorrentMetadata,
+    peerId: Uint8Array,
+    options: AnnounceOptions = {},
+): Promise<PeerInfo[]> => {
+    const url = new URL(tracker);
+    const { address: host } = await lookup(url.hostname);
+
+    const trackerPort = parseInt(url.port, 10);
+    const timeoutMs = options.timeoutMs ?? 1_000;
+    const announcePort = options.announcePort ?? DEFAULT_ANNOUNCE_PORT;
+
+    let phase: 'connect' | 'announce' = 'connect';
+    const connectTxId = randomU32();
+    let announceTxId = 0;
+    let connHigh = 0;
+    let connLow = 0;
+
+    let resolveFn!: (peers: PeerInfo[]) => void;
+    let rejectFn!: (err: unknown) => void;
+    let settled = false;
+
+    const promise = new Promise<PeerInfo[]>((resolve, reject) => {
+        resolveFn = resolve;
+        rejectFn = reject;
+    });
+
+    const clearAnnounceTimeout = () => clearTimeout(timeout);
+
+    const resolveOnce = (peers: PeerInfo[]) => {
+        if (settled) return;
+        settled = true;
+        clearAnnounceTimeout();
+        resolveFn(peers);
+    };
+
+    const rejectOnce = (error: unknown) => {
+        if (settled) return;
+        settled = true;
+        clearAnnounceTimeout();
+        rejectFn(error);
+    };
+
+    const socket = await Bun.udpSocket({
+        socket: {
+            data(socket, data) {
+                try {
+                    const bytes = new Uint8Array(data);
+
+                    if (phase === 'connect') {
+                        ({ connHigh, connLow } = parseConnectResponse(bytes, connectTxId));
+
+                        announceTxId = randomU32();
+                        phase = 'announce';
+
+                        socket.send(
+                            buildAnnounceRequest(
+                                connHigh,
+                                connLow,
+                                announceTxId,
+                                meta,
+                                peerId,
+                                announcePort,
+                            ),
+                            trackerPort,
+                            host,
+                        );
+
+                        return;
+                    }
+
+                    const peers = parseAnnounceResponse(bytes, announceTxId);
+                    socket.close();
+                    if (peers.length === 0) {
+                        rejectOnce(
+                            new TrackerError(
+                                TrackerErrorCode.NO_PEERS,
+                                'Tracker returned no peers',
+                            ),
+                        );
+                        return;
+                    }
+                    resolveOnce(peers);
+                } catch (err) {
+                    socket.close();
+                    rejectOnce(err);
+                }
+            },
+
+            error(socket, err) {
+                socket.close();
+                rejectOnce(err);
+            },
+        },
+    });
+
+    const timeout = setTimeout(() => {
+        socket.close();
+        rejectOnce(new TrackerError(TrackerErrorCode.ANNOUNCE_TIMEOUT, 'Tracker announce timeout'));
+    }, timeoutMs);
+
+    socket.send(buildConnectRequest(connectTxId), trackerPort, host);
+
+    return promise;
+};
+
+const MAGIC_HIGH = 0x00000417;
+const MAGIC_LOW = 0x27101980;
+
+const randomU32 = (): number => (Math.random() * 0xffffffff) >>> 0;
+
+const buildConnectRequest = (txId: number): Uint8Array => {
+    const buf = new Uint8Array(16);
+    const view = new DataView(buf.buffer);
+    view.setUint32(0, MAGIC_HIGH, false);
+    view.setUint32(4, MAGIC_LOW, false);
+    view.setUint32(8, 0, false); // action = connect
+    view.setUint32(12, txId, false);
+    return buf;
+};
+
+const parseConnectResponse = (data: Uint8Array, txId: number) => {
+    if (data.byteLength < 16) {
+        throw new TrackerError(
+            TrackerErrorCode.CONNECT_RESPONSE_TOO_SHORT,
+            'Connect response too short',
+        );
+    }
+    const view = new DataView(data.buffer, data.byteOffset);
+    if (view.getUint32(0, false) !== 0) {
+        throw new TrackerError(TrackerErrorCode.INVALID_ACTION, 'Expected tracker action=0');
+    }
+    if (view.getUint32(4, false) !== txId) {
+        throw new TrackerError(
+            TrackerErrorCode.TRANSACTION_ID_MISMATCH,
+            'Tracker transaction ID mismatch',
+        );
+    }
+    return {
+        connHigh: view.getUint32(8, false),
+        connLow: view.getUint32(12, false),
+    };
+};
+
+const buildAnnounceRequest = (
+    connHigh: number,
+    connLow: number,
+    txId: number,
+    meta: TorrentMetadata,
+    peerId: Uint8Array,
+    announcePort: number,
+): Uint8Array => {
+    const buf = new Uint8Array(98);
+    const view = new DataView(buf.buffer);
+    let o = 0;
+
+    view.setUint32(o, connHigh, false);
+    o += 4;
+    view.setUint32(o, connLow, false);
+    o += 4;
+    view.setUint32(o, 1, false);
+    o += 4; // action = announce
+    view.setUint32(o, txId, false);
+    o += 4;
+
+    buf.set(meta.infoHash, o);
+    o += 20;
+    buf.set(peerId, o);
+    o += 20;
+
+    // downloaded = 0
+    view.setUint32(o, 0, false);
+    o += 4;
+    view.setUint32(o, 0, false);
+    o += 4;
+
+    // left = meta.length
+    const left = BigInt(meta.length);
+    view.setUint32(o, Number(left >> 32n), false);
+    o += 4;
+    view.setUint32(o, Number(left & 0xffffffffn), false);
+    o += 4;
+
+    // uploaded = 0
+    view.setUint32(o, 0, false);
+    o += 4;
+    view.setUint32(o, 0, false);
+    o += 4;
+
+    view.setUint32(o, 2, false);
+    o += 4; // event = started
+    view.setUint32(o, 0, false);
+    o += 4; // ip = default
+    view.setUint32(o, randomU32(), false);
+    o += 4; // key
+    view.setInt32(o, -1, false);
+    o += 4; // num_want = -1 (default)
+    view.setUint16(o, announcePort, false); // client listen port
+
+    return buf;
+};
+
+const parseAnnounceResponse = (data: Uint8Array, txId: number): PeerInfo[] => {
+    if (data.byteLength < 20) {
+        throw new TrackerError(
+            TrackerErrorCode.ANNOUNCE_RESPONSE_TOO_SHORT,
+            'Announce response too short',
+        );
+    }
+    const view = new DataView(data.buffer, data.byteOffset);
+    if (view.getUint32(0, false) !== 1) {
+        throw new TrackerError(TrackerErrorCode.INVALID_ACTION, 'Expected tracker action=1');
+    }
+    if (view.getUint32(4, false) !== txId) {
+        throw new TrackerError(
+            TrackerErrorCode.TRANSACTION_ID_MISMATCH,
+            'Tracker transaction ID mismatch',
+        );
+    }
+
+    const peers: PeerInfo[] = [];
+    for (let o = 20; o + 6 <= data.byteLength; o += 6) {
+        const ip = `${data[o]}.${data[o + 1]}.${data[o + 2]}.${data[o + 3]}`;
+        const port = view.getUint16(o + 4, false);
+        peers.push({ ip, port });
+    }
+    return peers;
+};

package/src/utils/__tests__/sha1.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from 'bun:test';
+
+import { bytesToHex } from '@utils/buffers';
+import { sha1 } from '@utils/sha1';
+
+const bytes = (value: string): Uint8Array => new TextEncoder().encode(value);
+
+describe('sha1', () => {
+    test('hashes known test vector', () => {
+        expect(bytesToHex(sha1(bytes('abc')))).toBe('a9993e364706816aba3e25717850c26c9cd0d89d');
+    });
+
+    test('returns 20 bytes', () => {
+        expect(sha1(bytes('abc')).byteLength).toBe(20);
+    });
+});