Send files directly between devices over the internet - no cloud storage, no size limits.
TypeScript cross-platformdata-transferdecentralizedfile-sharingfile-transferhole-punchingopen-sourcep2ppeer-to-peerprivacyprivacy-tools
Add drive: chunked file transfer package (#60)
Denis Lupookovc8cddf3eee64
diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.ymlindex b0f3328..07c9708 100644--- a/.github/workflows/checks.yml+++ b/.github/workflows/checks.yml@@ -38,6 +38,7 @@ jobs:- name: Type-checkrun: |npm run typecheck -w packages/core+ npm run typecheck -w packages/drivenpm run typecheck -w packages/localesnpm run typecheck -w packages/domainnpm run typecheck -w packages/componentsdiff --git a/.gitignore b/.gitignoreindex 4b1def3..24292f8 100644--- a/.gitignore+++ b/.gitignore@@ -54,6 +54,9 @@ yarn-error.log*# Internal — not for the public repoapp-marketing-context.md+# Local tooling config+.claude/+# Electronreleaseapps/desktop/distdiff --git a/knip.json b/knip.jsonindex 5d3df7a..a6f17cc 100644--- a/knip.json+++ b/knip.json@@ -13,6 +13,9 @@"entry": ["src/**/*.test.ts"],"ignore": ["schema/**"]},+ "packages/drive": {+ "entry": ["src/**/*.test.ts", "test/**/*.test.ts"]+ },"packages/domain": {"entry": ["src/**/*.test.ts"]},diff --git a/package-lock.json b/package-lock.jsonindex 0bdfb68..9dd7c35 100644--- a/package-lock.json+++ b/package-lock.json@@ -203,6 +203,10 @@"resolved": "packages/domain","link": true},+ "node_modules/@altersend/drive": {+ "resolved": "packages/drive",+ "link": true+ },"node_modules/@altersend/locales": {"resolved": "packages/locales","link": true@@ -12071,6 +12075,26 @@"readable-stream": "^3.4.0"}},+ "node_modules/blake2b": {+ "version": "2.1.4",+ "resolved": "https://registry.npmjs.org/blake2b/-/blake2b-2.1.4.tgz",+ "integrity": "sha512-AyBuuJNI64gIvwx13qiICz6H6hpmjvYS5DGkG6jbXMOT8Z3WUJ3V1X0FlhIoT1b/5JtHE3ki+xjtMvu1nn+t9A==",+ "license": "ISC",+ "dependencies": {+ "blake2b-wasm": "^2.4.0",+ "nanoassert": "^2.0.0"+ }+ },+ "node_modules/blake2b-wasm": {+ "version": "2.4.0",+ "resolved": "https://registry.npmjs.org/blake2b-wasm/-/blake2b-wasm-2.4.0.tgz",+ "integrity": "sha512-S1kwmW2ZhZFFFOghcx73+ZajEfKBqhP82JMssxtLVMxlaPea1p9uoLiUZ5WYyHn0KddwbLc+0vh4wR0KBNoT5w==",+ "license": "MIT",+ "dependencies": {+ "b4a": "^1.0.1",+ "nanoassert": "^2.0.0"+ }+ },"node_modules/blind-relay": {"version": "1.6.1","resolved": "https://registry.npmjs.org/blind-relay/-/blind-relay-1.6.1.tgz",@@ -27380,6 +27404,37 @@"zustand": "^5.0.12"}},+ "packages/drive": {+ "name": "@altersend/drive",+ "version": "1.6.0",+ "license": "Apache-2.0",+ "dependencies": {+ "blake2b": "^2.1.4"+ },+ "devDependencies": {+ "@types/node": "^22.10.0",+ "tsup": "^8.5.1",+ "typescript": "^5.9.3",+ "vitest": "^4.1.8"+ }+ },+ "packages/drive/node_modules/@types/node": {+ "version": "22.20.1",+ "resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.1.tgz",+ "integrity": "sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "undici-types": "~6.21.0"+ }+ },+ "packages/drive/node_modules/undici-types": {+ "version": "6.21.0",+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",+ "dev": true,+ "license": "MIT"+ },"packages/locales": {"name": "@altersend/locales","version": "1.6.0",diff --git a/package.json b/package.jsonindex a6c93cc..52877e0 100644--- a/package.json+++ b/package.json@@ -22,7 +22,7 @@"components:typecheck": "npm run typecheck -w packages/components","components:storybook": "npm run storybook -w packages/components","components:build-storybook": "npm run build-storybook -w packages/components",- "build": "npm run build -w packages/core && npm run build -w packages/locales && npm run build -w packages/domain && npm run build -w packages/components && npm run build --if-present -w apps/desktop",+ "build": "npm run build -w packages/core && npm run build -w packages/drive && npm run build -w packages/locales && npm run build -w packages/domain && npm run build -w packages/components && npm run build --if-present -w apps/desktop","test": "npm test --workspaces --if-present","lint": "eslint apps packages --max-warnings=0","format": "prettier --write \"apps/**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\" \"packages/**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\"",diff --git a/packages/drive/README.md b/packages/drive/README.mdnew file mode 100644index 0000000..d272a68--- /dev/null+++ b/packages/drive/README.md@@ -0,0 +1,73 @@+# @altersend/drive++Chunked file transfer over a caller-supplied channel. The sender reads byte+ranges from the source file (`pread`) and the receiver writes them to their+offsets in the destination (`pwrite`). Neither side makes an intermediate copy.++## Usage++```ts+import { Drive } from '@altersend/drive'++const drive = new Drive(receiveDir)+const savedTo = await drive.receive('photo.jpg', channelB)+await drive.send(filePath, channelA)+```++`receive` takes a name and saves it under the configured directory. `send` takes+a full path to any file on disk — the directory says where files arrive, not+where they may be sent from.++If the destination varies per transfer, skip `Drive` and pass full paths:++```ts+import { sendFile, receiveFile } from '@altersend/drive'++const savedTo = await receiveFile(destPath, channelB)+await sendFile(srcPath, channelA)+```++`transferId` is optional — the sender generates one, the receiver adopts it. Pass+one explicitly when a channel carries several transfers at once.++For a non-disk source, drive the sessions with your own reader/writer:++```ts+import { SenderSession, ReceiverSession, DiskReader, DiskWriter } from '@altersend/drive'++const receiver = new ReceiverSession(new DiskWriter(destPath), channelB, { transferId })+const savedTo = await receiver.receive()++const sender = new SenderSession(new DiskReader(srcPath), channelA, { transferId, name })+await sender.start()+await sender.close()+```++## Protocol++```+start { transferId, name, size, chunkSize } sender → receiver+need { indices } receiver → sender+<chunk> header{ index, hash } + bytes sender → receiver+complete { fileHash | null } sender → receiver+ack { savedTo } receiver → sender+cancel { reason? } either+```++Chunk size is a pure function of file size, so both sides derive the same+geometry from `start` alone. Each chunk carries a blake2b hash, verified on+arrival. `fileHash` is a hash over the chunk hashes.++## Interfaces++The engine imports no filesystem or socket. It drives three interfaces:++| Interface | Native | Browser (not built) |+| -------------- | ---------------- | ----------------------------- |+| `ChunkReader` | `bare-fs` pread | `File.slice().arrayBuffer()` |+| `ChunkWriter` | `bare-fs` pwrite | File System Access API / OPFS |+| `DriveChannel` | Protomux on UDX | WebSocket |++This build ships `DiskReader` / `DiskWriter` on `node:fs`; `bare-fs` has the same+`FileHandle` API, so the worklet swaps the import. The root export resolves to an+fs-free build under a browser condition.diff --git a/packages/drive/package.json b/packages/drive/package.jsonnew file mode 100644index 0000000..cd4c669--- /dev/null+++ b/packages/drive/package.json@@ -0,0 +1,43 @@+{+ "name": "@altersend/drive",+ "version": "1.6.0",+ "type": "module",+ "main": "./dist/native.js",+ "types": "./dist/native.d.ts",+ "browser": "./dist/index.js",+ "exports": {+ ".": {+ "browser": {+ "types": "./dist/index.d.ts",+ "default": "./dist/index.js"+ },+ "default": {+ "types": "./dist/native.d.ts",+ "default": "./dist/native.js"+ }+ }+ },+ "private": true,+ "license": "Apache-2.0",+ "author": "AlterSend",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/denislupookov/altersend.git"+ },+ "scripts": {+ "test": "vitest run",+ "test:watch": "vitest",+ "typecheck": "tsc --noEmit",+ "build": "tsup",+ "clean": "rm -rf dist"+ },+ "dependencies": {+ "blake2b": "^2.1.4"+ },+ "devDependencies": {+ "@types/node": "^22.10.0",+ "tsup": "^8.5.1",+ "typescript": "^5.9.3",+ "vitest": "^4.1.8"+ }+}diff --git a/packages/drive/src/adapters/disk-reader.ts b/packages/drive/src/adapters/disk-reader.tsnew file mode 100644index 0000000..72fe2e9--- /dev/null+++ b/packages/drive/src/adapters/disk-reader.ts@@ -0,0 +1,34 @@+import { open, stat, type FileHandle } from 'node:fs/promises'+import type { ChunkReader } from '../engine/types'+import { readRange } from './read-range'++export class DiskReader implements ChunkReader {+ private readonly path: string+ private opening: Promise<FileHandle> | null = null++ constructor(path: string) {+ this.path = path+ }++ private handle(): Promise<FileHandle> {+ if (!this.opening) this.opening = open(this.path, 'r')+ return this.opening+ }++ async size(): Promise<number> {+ return (await stat(this.path)).size+ }++ async read(offset: number, length: number): Promise<Uint8Array> {+ return readRange(await this.handle(), offset, length)+ }++ async close(): Promise<void> {+ const pending = this.opening+ this.opening = null+ if (!pending) return+ try {+ await (await pending).close()+ } catch {}+ }+}diff --git a/packages/drive/src/adapters/disk-writer.ts b/packages/drive/src/adapters/disk-writer.tsnew file mode 100644index 0000000..f2c8130--- /dev/null+++ b/packages/drive/src/adapters/disk-writer.ts@@ -0,0 +1,53 @@+import { open, rename, unlink, type FileHandle } from 'node:fs/promises'+import type { ChunkWriter } from '../engine/types'+import { readRange } from './read-range'++export class DiskWriter implements ChunkWriter {+ private readonly targetPath: string+ private readonly partPath: string+ private handle: FileHandle | null = null++ constructor(targetPath: string) {+ this.targetPath = targetPath+ this.partPath = `${targetPath}.part`+ }++ async allocate(size: number): Promise<void> {+ try {+ this.handle = await open(this.partPath, 'r+')+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err+ this.handle = await open(this.partPath, 'w+')+ }+ await this.handle.truncate(size)+ }++ async write(offset: number, data: Uint8Array): Promise<void> {+ if (!this.handle) throw new Error('DiskWriter.write before allocate')+ await this.handle.write(data, 0, data.length, offset)+ }++ async readBack(offset: number, length: number): Promise<Uint8Array | null> {+ if (!this.handle) return null+ return readRange(this.handle, offset, length)+ }++ async finalize(): Promise<string> {+ if (this.handle) {+ await this.handle.close()+ this.handle = null+ }+ await rename(this.partPath, this.targetPath)+ return this.targetPath+ }++ async abort(): Promise<void> {+ if (this.handle) {+ await this.handle.close()+ this.handle = null+ }+ try {+ await unlink(this.partPath)+ } catch {}+ }+}diff --git a/packages/drive/src/adapters/read-range.ts b/packages/drive/src/adapters/read-range.tsnew file mode 100644index 0000000..48eb70a--- /dev/null+++ b/packages/drive/src/adapters/read-range.ts@@ -0,0 +1,11 @@+import type { FileHandle } from 'node:fs/promises'++export async function readRange(+ handle: FileHandle,+ offset: number,+ length: number+): Promise<Uint8Array> {+ const buffer = new Uint8Array(length)+ const { bytesRead } = await handle.read(buffer, 0, length, offset)+ return bytesRead === length ? buffer : buffer.subarray(0, bytesRead)+}diff --git a/packages/drive/src/api/drive.test.ts b/packages/drive/src/api/drive.test.tsnew file mode 100644index 0000000..d5daade--- /dev/null+++ b/packages/drive/src/api/drive.test.ts@@ -0,0 +1,96 @@+import { describe, it, expect, afterEach } from 'vitest'+import { mkdtemp, writeFile, readFile, rm, stat } from 'node:fs/promises'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import { sendFile, receiveFile, Drive } from './drive'+import { createChannelPair } from '../../test/support'++let dir: string | null = null++afterEach(async () => {+ if (dir) {+ await rm(dir, { recursive: true, force: true })+ dir = null+ }+})++describe('sendFile / receiveFile end-to-end', () => {+ it('transfers a real file with no leftover .part', async () => {+ dir = await mkdtemp(join(tmpdir(), 'drive-'))+ const srcPath = join(dir, 'source.bin')+ const dstPath = join(dir, 'dest.bin')++ const input = new Uint8Array(600 * 1024)+ for (let i = 0; i < input.length; i++) input[i] = (i * 31 + 7) & 0xff+ await writeFile(srcPath, input)++ const [senderChannel, receiverChannel] = createChannelPair()+ const [savedTo] = await Promise.all([+ receiveFile(dstPath, receiverChannel, { transferId: 't' }),+ sendFile(srcPath, senderChannel, { transferId: 't' })+ ])++ expect(savedTo).toBe(dstPath)+ const out = new Uint8Array(await readFile(dstPath))+ expect(Buffer.from(out).equals(Buffer.from(input))).toBe(true)+ await expect(stat(`${dstPath}.part`)).rejects.toThrow()+ })++ it('defaults the sent name to the file basename', async () => {+ dir = await mkdtemp(join(tmpdir(), 'drive-'))+ const srcPath = join(dir, 'photo.jpg')+ const dstPath = join(dir, 'received.jpg')+ await writeFile(srcPath, new Uint8Array([1, 2, 3, 4, 5]))++ const [senderChannel, receiverChannel] = createChannelPair()+ let seenName = ''+ const forward = senderChannel.send.bind(senderChannel)+ senderChannel.send = (m) => {+ if (m.type === 'start') seenName = m.name+ forward(m)+ }++ await Promise.all([+ receiveFile(dstPath, receiverChannel, { transferId: 't' }),+ sendFile(srcPath, senderChannel, { transferId: 't' })+ ])++ expect(seenName).toBe('photo.jpg')+ })++ it('works with no transferId — receiver adopts the sender-generated id', async () => {+ dir = await mkdtemp(join(tmpdir(), 'drive-'))+ const srcPath = join(dir, 'source.bin')+ const dstPath = join(dir, 'dest.bin')+ const input = new Uint8Array(200 * 1024).map((_, i) => (i * 13) & 0xff)+ await writeFile(srcPath, input)++ const [senderChannel, receiverChannel] = createChannelPair()+ const [savedTo] = await Promise.all([+ receiveFile(dstPath, receiverChannel),+ sendFile(srcPath, senderChannel)+ ])++ expect(savedTo).toBe(dstPath)+ expect(Buffer.from(await readFile(dstPath)).equals(Buffer.from(input))).toBe(true)+ })+})++describe('Drive (rooted helper)', () => {+ it('receives by name under the configured root', async () => {+ dir = await mkdtemp(join(tmpdir(), 'drive-'))+ const srcPath = join(dir, 'source.bin')+ const input = new Uint8Array(200 * 1024).map((_, i) => (i * 17 + 3) & 0xff)+ await writeFile(srcPath, input)++ const drive = new Drive(dir)+ const [senderChannel, receiverChannel] = createChannelPair()+ const [savedTo] = await Promise.all([+ drive.receive('received.bin', receiverChannel),+ drive.send(srcPath, senderChannel)+ ])++ expect(savedTo).toBe(join(dir, 'received.bin'))+ expect(Buffer.from(await readFile(savedTo)).equals(Buffer.from(input))).toBe(true)+ })+})diff --git a/packages/drive/src/api/drive.ts b/packages/drive/src/api/drive.tsnew file mode 100644index 0000000..a50eaa9--- /dev/null+++ b/packages/drive/src/api/drive.ts@@ -0,0 +1,73 @@+import { basename, join } from 'node:path'+import type { DriveChannel } from '../engine/types'+import type { Bitmap } from '../engine/bitmap'+import { SenderSession } from '../engine/sender'+import { ReceiverSession } from '../engine/receiver'+import { DiskReader } from '../adapters/disk-reader'+import { DiskWriter } from '../adapters/disk-writer'++export interface SendFileOptions {+ transferId?: string+ name?: string+ highWaterMark?: number+ onProgress?: (sentBytes: number, totalBytes: number) => void+}++export async function sendFile(+ path: string,+ channel: DriveChannel,+ opts: SendFileOptions = {}+): Promise<string> {+ const reader = new DiskReader(path)+ const sender = new SenderSession(reader, channel, {+ transferId: opts.transferId ?? String(Math.random()),+ name: opts.name ?? basename(path),+ highWaterMark: opts.highWaterMark,+ onProgress: opts.onProgress+ })+ try {+ return await sender.start()+ } finally {+ await reader.close()+ }+}++export interface ReceiveFileOptions {+ transferId?: string+ resumeBits?: Uint8Array+ verifyFullFile?: boolean+ onProgress?: (receivedBytes: number, totalBytes: number) => void+ onChunkWritten?: (bitmap: Bitmap) => void+}++export function receiveFile(+ targetPath: string,+ channel: DriveChannel,+ opts: ReceiveFileOptions = {}+): Promise<string> {+ const writer = new DiskWriter(targetPath)+ const receiver = new ReceiverSession(writer, channel, {+ transferId: opts.transferId,+ resumeBits: opts.resumeBits,+ verifyFullFile: opts.verifyFullFile,+ onProgress: opts.onProgress,+ onChunkWritten: opts.onChunkWritten+ })+ return receiver.receive()+}++export class Drive {+ private readonly receiveDir: string++ constructor(receiveDir: string) {+ this.receiveDir = receiveDir+ }++ send(filePath: string, channel: DriveChannel, opts: SendFileOptions = {}): Promise<string> {+ return sendFile(filePath, channel, opts)+ }++ receive(name: string, channel: DriveChannel, opts: ReceiveFileOptions = {}): Promise<string> {+ return receiveFile(join(this.receiveDir, name), channel, opts)+ }+}diff --git a/packages/drive/src/blake2b.d.ts b/packages/drive/src/blake2b.d.tsnew file mode 100644index 0000000..84ea619--- /dev/null+++ b/packages/drive/src/blake2b.d.ts@@ -0,0 +1,9 @@+declare module 'blake2b' {+ interface Blake2bHash {+ update(input: Uint8Array): Blake2bHash+ digest(encoding: 'hex'): string+ digest(): Uint8Array+ }+ function blake2b(outLength: number): Blake2bHash+ export = blake2b+}diff --git a/packages/drive/src/engine/bitmap.test.ts b/packages/drive/src/engine/bitmap.test.tsnew file mode 100644index 0000000..d2ade39--- /dev/null+++ b/packages/drive/src/engine/bitmap.test.ts@@ -0,0 +1,48 @@+import { describe, it, expect } from 'vitest'+import { Bitmap } from './bitmap'++describe('Bitmap', () => {+ it('sets and reads individual bits', () => {+ const b = new Bitmap(20)+ expect(b.get(5)).toBe(false)+ b.set(5)+ expect(b.get(5)).toBe(true)+ expect(b.get(6)).toBe(false)+ })++ it('counts set bits and reports completeness', () => {+ const b = new Bitmap(3)+ expect(b.allSet()).toBe(false)+ b.set(0)+ b.set(1)+ b.set(2)+ expect(b.count()).toBe(3)+ expect(b.allSet()).toBe(true)+ })++ it('lists missing indices ascending', () => {+ const b = new Bitmap(5)+ b.set(1)+ b.set(3)+ expect(b.missing()).toEqual([0, 2, 4])+ })++ it('rejects out-of-range writes', () => {+ const b = new Bitmap(4)+ expect(() => b.set(4)).toThrow()+ })++ it('round-trips through serialize/deserialize', () => {+ const b = new Bitmap(10)+ b.set(0)+ b.set(9)+ const restored = Bitmap.deserialize(10, b.serialize())+ expect(restored.get(0)).toBe(true)+ expect(restored.get(9)).toBe(true)+ expect(restored.missing()).toEqual([1, 2, 3, 4, 5, 6, 7, 8])+ })++ it('treats an empty bitmap as complete', () => {+ expect(new Bitmap(0).allSet()).toBe(true)+ })+})diff --git a/packages/drive/src/engine/bitmap.ts b/packages/drive/src/engine/bitmap.tsnew file mode 100644index 0000000..eddd9e6--- /dev/null+++ b/packages/drive/src/engine/bitmap.ts@@ -0,0 +1,58 @@+export class Bitmap {+ readonly size: number+ private readonly bits: Uint8Array+ private setBits = 0++ constructor(size: number, bits?: Uint8Array) {+ this.size = size+ const byteLength = Math.ceil(size / 8)+ if (bits) {+ if (bits.length < byteLength) throw new Error('Bitmap bits too short for size')+ this.bits = bits.slice(0, byteLength)+ for (let i = 0; i < size; i++) {+ if (this.get(i)) this.setBits+++ }+ } else {+ this.bits = new Uint8Array(byteLength)+ }+ }++ get(index: number): boolean {+ if (index < 0 || index >= this.size) return false+ return (this.bits[Math.floor(index / 8)] & (1 << (index & 7))) !== 0+ }++ set(index: number): void {+ if (index < 0 || index >= this.size) throw new Error('Bitmap index out of range')+ const byte = Math.floor(index / 8)+ const mask = 1 << (index & 7)+ if ((this.bits[byte] & mask) === 0) {+ this.bits[byte] |= mask+ this.setBits+++ }+ }++ count(): number {+ return this.setBits+ }++ allSet(): boolean {+ return this.setBits === this.size+ }++ missing(): number[] {+ const out: number[] = []+ for (let i = 0; i < this.size; i++) {+ if (!this.get(i)) out.push(i)+ }+ return out+ }++ serialize(): Uint8Array {+ return this.bits.slice()+ }++ static deserialize(size: number, bits: Uint8Array): Bitmap {+ return new Bitmap(size, bits)+ }+}diff --git a/packages/drive/src/engine/chunker.test.ts b/packages/drive/src/engine/chunker.test.tsnew file mode 100644index 0000000..519ce1d--- /dev/null+++ b/packages/drive/src/engine/chunker.test.ts@@ -0,0 +1,47 @@+import { describe, it, expect } from 'vitest'+import { selectChunkSize, chunkCount, chunkRange } from './chunker'++const KB = 1024+const MB = 1024 * KB+const GB = 1024 * MB++describe('selectChunkSize', () => {+ it('scales chunk size up with file size', () => {+ expect(selectChunkSize(500 * KB)).toBe(64 * KB)+ expect(selectChunkSize(50 * MB)).toBe(256 * KB)+ expect(selectChunkSize(5 * GB)).toBe(1 * MB)+ expect(selectChunkSize(20 * GB)).toBe(4 * MB)+ })++ it('is deterministic at tier boundaries', () => {+ expect(selectChunkSize(1 * MB)).toBe(256 * KB)+ expect(selectChunkSize(1 * MB - 1)).toBe(64 * KB)+ })+})++describe('chunkCount', () => {+ it('is zero for empty files', () => {+ expect(chunkCount(0, 64 * KB)).toBe(0)+ })++ it('rounds up the final partial chunk', () => {+ expect(chunkCount(64 * KB, 64 * KB)).toBe(1)+ expect(chunkCount(64 * KB + 1, 64 * KB)).toBe(2)+ expect(chunkCount(200 * KB, 64 * KB)).toBe(4)+ })+})++describe('chunkRange', () => {+ it('computes contiguous offsets', () => {+ expect(chunkRange(0, 200 * KB, 64 * KB)).toEqual({ offset: 0, length: 64 * KB })+ expect(chunkRange(1, 200 * KB, 64 * KB)).toEqual({ offset: 64 * KB, length: 64 * KB })+ })++ it('shortens the final chunk', () => {+ expect(chunkRange(3, 200 * KB, 64 * KB)).toEqual({ offset: 192 * KB, length: 8 * KB })+ })++ it('returns a zero-length range past EOF', () => {+ expect(chunkRange(10, 100, 64)).toEqual({ offset: 100, length: 0 })+ })+})diff --git a/packages/drive/src/engine/chunker.ts b/packages/drive/src/engine/chunker.tsnew file mode 100644index 0000000..15649f3--- /dev/null+++ b/packages/drive/src/engine/chunker.ts@@ -0,0 +1,39 @@+interface Tier {+ maxFileSize: number+ chunkSize: number+}++const KB = 1024+const MB = 1024 * KB+const GB = 1024 * MB++const TIERS: readonly Tier[] = [+ { maxFileSize: 1 * MB, chunkSize: 64 * KB },+ { maxFileSize: 100 * MB, chunkSize: 256 * KB },+ { maxFileSize: 10 * GB, chunkSize: 1 * MB }+]++const LARGE_CHUNK_SIZE = 4 * MB++export function selectChunkSize(size: number): number {+ for (const tier of TIERS) {+ if (size < tier.maxFileSize) return tier.chunkSize+ }+ return LARGE_CHUNK_SIZE+}++export function chunkCount(size: number, chunkSize: number): number {+ if (size <= 0) return 0+ return Math.ceil(size / chunkSize)+}++export interface ChunkRange {+ offset: number+ length: number+}++export function chunkRange(index: number, size: number, chunkSize: number): ChunkRange {+ const offset = index * chunkSize+ if (offset >= size) return { offset: size, length: 0 }+ return { offset, length: Math.min(chunkSize, size - offset) }+}diff --git a/packages/drive/src/engine/hash.test.ts b/packages/drive/src/engine/hash.test.tsnew file mode 100644index 0000000..49228c3--- /dev/null+++ b/packages/drive/src/engine/hash.test.ts@@ -0,0 +1,35 @@+import { describe, it, expect } from 'vitest'+import { hashChunk, createHasher } from './hash'++describe('hashChunk', () => {+ it('is deterministic for the same bytes', () => {+ const data = new Uint8Array([1, 2, 3, 4, 5])+ expect(hashChunk(data)).toBe(hashChunk(data.slice()))+ })++ it('differs for different bytes', () => {+ expect(hashChunk(new Uint8Array([1, 2, 3]))).not.toBe(hashChunk(new Uint8Array([1, 2, 4])))+ })++ it('returns a 32-byte (64 hex char) digest', () => {+ expect(hashChunk(new Uint8Array([0]))).toMatch(/^[0-9a-f]{64}$/)+ })+})++describe('createHasher', () => {+ it('matches the one-shot hash when fed the whole buffer', () => {+ const data = new Uint8Array([10, 20, 30, 40, 50, 60])+ const h = createHasher()+ h.update(data)+ expect(h.digest()).toBe(hashChunk(data))+ })++ it('matches regardless of how bytes are split across updates', () => {+ const data = new Uint8Array([10, 20, 30, 40, 50, 60])+ const h = createHasher()+ h.update(data.subarray(0, 2))+ h.update(data.subarray(2, 5))+ h.update(data.subarray(5))+ expect(h.digest()).toBe(hashChunk(data))+ })+})diff --git a/packages/drive/src/engine/hash.ts b/packages/drive/src/engine/hash.tsnew file mode 100644index 0000000..c7b0592--- /dev/null+++ b/packages/drive/src/engine/hash.ts@@ -0,0 +1,49 @@+import blake2b from 'blake2b'++const DIGEST_BYTES = 32++export function hashChunk(data: Uint8Array): string {+ return blake2b(DIGEST_BYTES).update(data).digest('hex')+}++export interface StreamingHasher {+ update(data: Uint8Array): void+ digest(): string+}++export function createHasher(): StreamingHasher {+ const h = blake2b(DIGEST_BYTES)+ return {+ update(data) {+ h.update(data)+ },+ digest() {+ return h.digest('hex')+ }+ }+}++function hexToBytes(hex: string): Uint8Array {+ const bytes = new Uint8Array(hex.length / 2)+ for (let i = 0; i < bytes.length; i++) {+ bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)+ }+ return bytes+}++export interface FileHasher {+ add(chunkHash: string): void+ digest(): string+}++export function createFileHasher(): FileHasher {+ const h = createHasher()+ return {+ add(chunkHash) {+ h.update(hexToBytes(chunkHash))+ },+ digest() {+ return h.digest()+ }+ }+}diff --git a/packages/drive/src/engine/loopback.test.ts b/packages/drive/src/engine/loopback.test.tsnew file mode 100644index 0000000..87fd723--- /dev/null+++ b/packages/drive/src/engine/loopback.test.ts@@ -0,0 +1,540 @@+import { describe, it, expect, beforeEach, afterEach } from 'vitest'+import { mkdtemp, writeFile, readFile, rm, stat, open } from 'node:fs/promises'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import { SenderSession } from './sender'+import { ReceiverSession } from './receiver'+import { selectChunkSize, chunkCount, chunkRange } from './chunker'+import { hashChunk, createFileHasher } from './hash'+import { DiskReader } from '../adapters/disk-reader'+import { DiskWriter } from '../adapters/disk-writer'+import { createChannelPair } from '../../test/support'+import type {+ ChunkHeader,+ CompleteMessage,+ ControlMessage,+ DriveChannel,+ NeedMessage+} from './types'++let dir = ''++beforeEach(async () => {+ dir = await mkdtemp(join(tmpdir(), 'drive-'))+})++afterEach(async () => {+ await rm(dir, { recursive: true, force: true })+})++function pseudoRandom(length: number, seed = 1): Uint8Array {+ const out = new Uint8Array(length)+ let x = seed >>> 0+ for (let i = 0; i < length; i++) {+ x = (x * 1664525 + 1013904223) >>> 0+ out[i] = x & 0xff+ }+ return out+}++function sameBytes(a: Uint8Array, b: Uint8Array): boolean {+ return Buffer.from(a).equals(Buffer.from(b))+}++function fileRoot(input: Uint8Array): string {+ const chunkSize = selectChunkSize(input.length)+ const total = chunkCount(input.length, chunkSize)+ const root = createFileHasher()+ for (let i = 0; i < total; i++) {+ const { offset, length } = chunkRange(i, input.length, chunkSize)+ root.add(hashChunk(input.slice(offset, offset + length)))+ }+ return root.digest()+}++async function waitUntil(fn: () => boolean, tries = 200): Promise<void> {+ for (let i = 0; i < tries; i++) {+ if (fn()) return+ await new Promise((resolve) => setTimeout(resolve, 5))+ }+ throw new Error('waitUntil: condition never held')+}++function range(start: number, end: number): number[] {+ const out: number[] = []+ for (let i = start; i < end; i++) out.push(i)+ return out+}++async function readOut(path: string): Promise<Uint8Array> {+ return new Uint8Array(await readFile(path))+}++function frames(input: Uint8Array, transferId: string) {+ const chunkSize = selectChunkSize(input.length)+ const total = chunkCount(input.length, chunkSize)+ const list: Array<{ header: ChunkHeader; data: Uint8Array }> = []+ for (let i = 0; i < total; i++) {+ const { offset, length } = chunkRange(i, input.length, chunkSize)+ const data = input.slice(offset, offset + length)+ list.push({ header: { transferId, index: i, hash: hashChunk(data) }, data })+ }+ return { chunkSize, total, list }+}++function controlledChannel() {+ let messageHandler: ((m: ControlMessage) => void) | undefined+ let chunkHandler: ((h: ChunkHeader, d: Uint8Array) => void) | undefined+ const sent: ControlMessage[] = []+ const channel: DriveChannel = {+ send: (m) => sent.push(m),+ sendChunk: () => {},+ onMessage: (h) => (messageHandler = h),+ onChunk: (h) => (chunkHandler = h),+ bufferedAmount: () => 0,+ close: () => {}+ }+ return {+ channel,+ sent,+ deliverMessage: (m: ControlMessage) => messageHandler?.(m),+ deliverChunk: (h: ChunkHeader, d: Uint8Array) => chunkHandler?.(h, d)+ }+}++const CHUNK_64K = 64 * 1024++describe('full sender ↔ receiver loopback', () => {+ const sizes = [0, 1, 100, CHUNK_64K, CHUNK_64K + 1, 200 * 1024]++ for (const size of sizes) {+ it(`round-trips a ${size}-byte file`, async () => {+ const input = pseudoRandom(size)+ const src = join(dir, 'src.bin')+ const dst = join(dir, 'dst.bin')+ await writeFile(src, input)++ const [senderChannel, receiverChannel] = createChannelPair()+ const receiver = new ReceiverSession(new DiskWriter(dst), receiverChannel, {+ transferId: 't'+ })+ const sender = new SenderSession(new DiskReader(src), senderChannel, {+ transferId: 't',+ name: 'file.bin'+ })++ const [savedTo] = await Promise.all([receiver.receive(), sender.start()])+ await sender.close()++ expect(savedTo).toBe(dst)+ expect(sameBytes(await readOut(dst), input)).toBe(true)+ })+ }++ it('passes optional full-file verification', async () => {+ const input = pseudoRandom(200 * 1024)+ const src = join(dir, 'src.bin')+ const dst = join(dir, 'dst.bin')+ await writeFile(src, input)++ const [senderChannel, receiverChannel] = createChannelPair()+ const receiver = new ReceiverSession(new DiskWriter(dst), receiverChannel, {+ transferId: 't',+ verifyFullFile: true+ })+ const sender = new SenderSession(new DiskReader(src), senderChannel, {+ transferId: 't',+ name: 'file.bin'+ })++ await Promise.all([receiver.receive(), sender.start()])+ await sender.close()+ expect(sameBytes(await readOut(dst), input)).toBe(true)+ })++ it('reports progress up to the full size', async () => {+ const input = pseudoRandom(200 * 1024)+ const src = join(dir, 'src.bin')+ const dst = join(dir, 'dst.bin')+ await writeFile(src, input)++ const [senderChannel, receiverChannel] = createChannelPair()+ let lastReceived = 0+ const receiver = new ReceiverSession(new DiskWriter(dst), receiverChannel, {+ transferId: 't',+ onProgress: (bytes) => (lastReceived = bytes)+ })+ const sender = new SenderSession(new DiskReader(src), senderChannel, {+ transferId: 't',+ name: 'file.bin'+ })++ await Promise.all([receiver.receive(), sender.start()])+ await sender.close()+ expect(lastReceived).toBe(input.length)+ })+})++describe('receiver robustness', () => {+ it('reconstructs the file from out-of-order chunks', async () => {+ const input = pseudoRandom(200 * 1024)+ const dst = join(dir, 'dst.bin')+ const { list } = frames(input, 't')+ const { channel, sent, deliverMessage, deliverChunk } = controlledChannel()++ const receiver = new ReceiverSession(new DiskWriter(dst), channel, { transferId: 't' })+ const done = receiver.receive()++ deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ for (const { header, data } of [...list].reverse()) deliverChunk(header, data)+ deliverMessage({ type: 'complete', transferId: 't', fileHash: fileRoot(input) })++ await done+ expect(sameBytes(await readOut(dst), input)).toBe(true)+ expect(sent.some((m) => m.type === 'ack')).toBe(true)+ })++ it('rejects a non-integer chunk index', async () => {+ const input = pseudoRandom(200 * 1024)+ const dst = join(dir, 'dst.bin')+ const { list } = frames(input, 't')+ const { channel, deliverMessage, deliverChunk } = controlledChannel()++ const receiver = new ReceiverSession(new DiskWriter(dst), channel, { transferId: 't' })+ const done = receiver.receive()++ deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ deliverChunk({ ...list[0].header, index: 1.5 }, list[0].data)++ await expect(done).rejects.toThrow(/out of range/)+ })++ it('tells the peer to cancel when it fails locally', async () => {+ const input = pseudoRandom(200 * 1024)+ const dst = join(dir, 'dst.bin')+ const { list } = frames(input, 't')+ const { channel, sent, deliverMessage, deliverChunk } = controlledChannel()++ const receiver = new ReceiverSession(new DiskWriter(dst), channel, { transferId: 't' })+ const done = receiver.receive()++ deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ const corrupted = list[0].data.slice()+ corrupted[0] ^= 0xff+ deliverChunk(list[0].header, corrupted)++ await expect(done).rejects.toThrow(/hash verification/)+ expect(sent.some((m) => m.type === 'cancel')).toBe(true)+ })++ it('does not echo a cancel back to the peer that sent it', async () => {+ const dst = join(dir, 'dst.bin')+ const { channel, sent, deliverMessage } = controlledChannel()++ const receiver = new ReceiverSession(new DiskWriter(dst), channel, { transferId: 't' })+ const done = receiver.receive()++ deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: 200 * 1024,+ chunkSize: CHUNK_64K+ })+ deliverMessage({ type: 'cancel', transferId: 't', reason: 'peer went away' })++ await expect(done).rejects.toThrow(/peer went away/)+ expect(sent.some((m) => m.type === 'cancel')).toBe(false)+ })++ it('rejects a chunk that fails hash verification', async () => {+ const input = pseudoRandom(200 * 1024)+ const dst = join(dir, 'dst.bin')+ const { list } = frames(input, 't')+ const { channel, deliverMessage, deliverChunk } = controlledChannel()++ const receiver = new ReceiverSession(new DiskWriter(dst), channel, { transferId: 't' })+ const done = receiver.receive()++ deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ const corrupted = list[0].data.slice()+ corrupted[0] ^= 0xff+ deliverChunk(list[0].header, corrupted)++ await expect(done).rejects.toThrow(/hash verification/)+ await expect(stat(`${dst}.part`)).rejects.toThrow()+ })++ it('rejects a chunk whose length is wrong', async () => {+ const input = pseudoRandom(200 * 1024)+ const dst = join(dir, 'dst.bin')+ const { list } = frames(input, 't')+ const { channel, deliverMessage, deliverChunk } = controlledChannel()++ const receiver = new ReceiverSession(new DiskWriter(dst), channel, { transferId: 't' })+ const done = receiver.receive()++ deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ deliverChunk(list[0].header, list[0].data.subarray(0, 10))++ await expect(done).rejects.toThrow(/length/)+ })+})++describe('resume', () => {+ it('requests only the missing chunks on the second run', async () => {+ const input = pseudoRandom(200 * 1024)+ const dst = join(dir, 'dst.bin')+ const { list, total } = frames(input, 't')++ const first = controlledChannel()+ const receiver1 = new ReceiverSession(new DiskWriter(dst), first.channel, { transferId: 't' })+ receiver1.receive().catch(() => {})+ first.deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ first.deliverChunk(list[0].header, list[0].data)+ first.deliverChunk(list[1].header, list[1].data)+ await waitUntil(() => (receiver1.received?.count() ?? 0) === 2)++ const resumeBits = receiver1.received!.serialize().slice()++ const second = controlledChannel()+ const receiver2 = new ReceiverSession(new DiskWriter(dst), second.channel, {+ transferId: 't',+ resumeBits+ })+ const done = receiver2.receive()+ second.deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ await waitUntil(() => second.sent.some((m) => m.type === 'need'))++ const need = second.sent.find((m): m is NeedMessage => m.type === 'need')!+ expect(need.indices).toEqual(range(2, total))++ for (let i = 2; i < total; i++) second.deliverChunk(list[i].header, list[i].data)+ second.deliverMessage({ type: 'complete', transferId: 't', fileHash: fileRoot(input) })++ await done+ expect(sameBytes(await readOut(dst), input)).toBe(true)+ })++ it('rejects a resume whose complete omits the file hash', async () => {+ const input = pseudoRandom(200 * 1024)+ const dst = join(dir, 'dst.bin')+ const { list, total } = frames(input, 't')++ const first = controlledChannel()+ const receiver1 = new ReceiverSession(new DiskWriter(dst), first.channel, { transferId: 't' })+ receiver1.receive().catch(() => {})+ first.deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ first.deliverChunk(list[0].header, list[0].data)+ await waitUntil(() => (receiver1.received?.count() ?? 0) === 1)+ const resumeBits = receiver1.received!.serialize().slice()++ const second = controlledChannel()+ const receiver2 = new ReceiverSession(new DiskWriter(dst), second.channel, {+ transferId: 't',+ resumeBits+ })+ const done = receiver2.receive()+ second.deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ await waitUntil(() => second.sent.some((m) => m.type === 'need'))+ for (let i = 1; i < total; i++) second.deliverChunk(list[i].header, list[i].data)+ second.deliverMessage({+ type: 'complete',+ transferId: 't',+ fileHash: null as unknown as string+ })++ await expect(done).rejects.toThrow(/Missing file hash/)+ })++ it('fails a resume whose partial file was corrupted, leaving no output', async () => {+ const input = pseudoRandom(200 * 1024)+ const dst = join(dir, 'dst.bin')+ const { list, total } = frames(input, 't')++ const first = controlledChannel()+ const receiver1 = new ReceiverSession(new DiskWriter(dst), first.channel, { transferId: 't' })+ receiver1.receive().catch(() => {})+ first.deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ first.deliverChunk(list[0].header, list[0].data)+ first.deliverChunk(list[1].header, list[1].data)+ await waitUntil(() => (receiver1.received?.count() ?? 0) === 2)+ const resumeBits = receiver1.received!.serialize().slice()++ const fh = await open(`${dst}.part`, 'r+')+ await fh.write(new Uint8Array(CHUNK_64K), 0, CHUNK_64K, 0)+ await fh.close()++ const second = controlledChannel()+ const receiver2 = new ReceiverSession(new DiskWriter(dst), second.channel, {+ transferId: 't',+ resumeBits+ })+ const done = receiver2.receive()+ second.deliverMessage({+ type: 'start',+ transferId: 't',+ name: 'f',+ size: input.length,+ chunkSize: CHUNK_64K+ })+ await waitUntil(() => second.sent.some((m) => m.type === 'need'))+ for (let i = 2; i < total; i++) second.deliverChunk(list[i].header, list[i].data)+ second.deliverMessage({ type: 'complete', transferId: 't', fileHash: fileRoot(input) })++ await expect(done).rejects.toThrow(/hash mismatch/)+ await expect(stat(`${dst}.part`)).rejects.toThrow()+ })+})++describe('sender full-file hash', () => {+ it('sends the true full-file hash even for a partial (resume) send', async () => {+ const input = pseudoRandom(200 * 1024)+ const src = join(dir, 'src.bin')+ await writeFile(src, input)++ let msgHandler: ((m: ControlMessage) => void) | undefined+ const sent: ControlMessage[] = []+ const channel: DriveChannel = {+ send: (m) => sent.push(m),+ sendChunk: () => {},+ onMessage: (h) => (msgHandler = h),+ onChunk: () => {},+ bufferedAmount: () => 0,+ close: () => {}+ }+ const sender = new SenderSession(new DiskReader(src), channel, { transferId: 't', name: 'f' })+ sender.start().catch(() => {})+ await waitUntil(() => sent.some((m) => m.type === 'start'))+ msgHandler!({ type: 'need', transferId: 't', indices: [2, 3] })+ await waitUntil(() => sent.some((m) => m.type === 'complete'))+ await sender.close()++ const complete = sent.find((m): m is CompleteMessage => m.type === 'complete')!+ expect(complete.fileHash).toBe(fileRoot(input))+ })+})++describe('hostile input', () => {+ it('receiver rejects a start whose chunkSize is inconsistent with size', async () => {+ const dst = join(dir, 'dst.bin')+ const { channel, sent, deliverMessage } = controlledChannel()+ const receiver = new ReceiverSession(new DiskWriter(dst), channel, { transferId: 't' })+ const done = receiver.receive()++ deliverMessage({ type: 'start', transferId: 't', name: 'f', size: 200 * 1024, chunkSize: 1 })++ await expect(done).rejects.toThrow(/geometry/)+ expect(sent.some((m) => m.type === 'cancel')).toBe(true)+ })++ it('sender rejects a need with an out-of-range index', async () => {+ const input = pseudoRandom(200 * 1024)+ const src = join(dir, 'src.bin')+ await writeFile(src, input)+ const { total } = frames(input, 't')++ let msgHandler: ((m: ControlMessage) => void) | undefined+ const sent: ControlMessage[] = []+ const channel: DriveChannel = {+ send: (m) => sent.push(m),+ sendChunk: () => {},+ onMessage: (h) => (msgHandler = h),+ onChunk: () => {},+ bufferedAmount: () => 0,+ close: () => {}+ }+ const sender = new SenderSession(new DiskReader(src), channel, { transferId: 't', name: 'f' })+ const done = sender.start()+ await waitUntil(() => sent.some((m) => m.type === 'start'))+ msgHandler!({ type: 'need', transferId: 't', indices: [total + 5] })++ await expect(done).rejects.toThrow(/Rejected/)+ expect(sent.some((m) => m.type === 'cancel')).toBe(true)+ await sender.close()+ })++ it('sender rejects a need with duplicate indices', async () => {+ const input = pseudoRandom(200 * 1024)+ const src = join(dir, 'src.bin')+ await writeFile(src, input)++ let msgHandler: ((m: ControlMessage) => void) | undefined+ const sent: ControlMessage[] = []+ const channel: DriveChannel = {+ send: (m) => sent.push(m),+ sendChunk: () => {},+ onMessage: (h) => (msgHandler = h),+ onChunk: () => {},+ bufferedAmount: () => 0,+ close: () => {}+ }+ const sender = new SenderSession(new DiskReader(src), channel, { transferId: 't', name: 'f' })+ const done = sender.start()+ await waitUntil(() => sent.some((m) => m.type === 'start'))+ msgHandler!({ type: 'need', transferId: 't', indices: [0, 0] })++ await expect(done).rejects.toThrow(/Rejected/)+ await sender.close()+ })+})diff --git a/packages/drive/src/engine/receiver.ts b/packages/drive/src/engine/receiver.tsnew file mode 100644index 0000000..c43ce36--- /dev/null+++ b/packages/drive/src/engine/receiver.ts@@ -0,0 +1,174 @@+import type { ChunkWriter, DriveChannel, ChunkHeader, ControlMessage } from './types'+import { selectChunkSize, chunkCount, chunkRange } from './chunker'+import { hashChunk, createFileHasher } from './hash'+import { Bitmap } from './bitmap'++export interface ReceiverOptions {+ transferId?: string+ resumeBits?: Uint8Array+ verifyFullFile?: boolean+ onProgress?: (receivedBytes: number, totalBytes: number) => void+ onChunkWritten?: (bitmap: Bitmap) => void+}++export class ReceiverSession {+ private readonly writer: ChunkWriter+ private readonly channel: DriveChannel+ private readonly opts: ReceiverOptions++ private size = 0+ private chunkSize = 0+ private bitmap: Bitmap | null = null+ private receivedBytes = 0+ private resumed = false+ private transferId: string | null+ private settled = false+ private settle!: { resolve: (savedTo: string) => void; reject: (err: Error) => void }+ private readonly done: Promise<string>+ private tail: Promise<void> = Promise.resolve()++ constructor(writer: ChunkWriter, channel: DriveChannel, opts: ReceiverOptions) {+ this.writer = writer+ this.channel = channel+ this.opts = opts+ this.transferId = opts.transferId ?? null+ this.done = new Promise<string>((resolve, reject) => {+ this.settle = { resolve, reject }+ })+ this.channel.onMessage((message) => this.onMessage(message))+ this.channel.onChunk((header, data) => this.enqueue(() => this.onChunk(header, data)))+ }++ private enqueue(task: () => Promise<void>): void {+ this.tail = this.tail.then(task).catch((err) => this.fail(err))+ }++ receive(): Promise<string> {+ return this.done+ }++ get received(): Bitmap | null {+ return this.bitmap+ }++ private onMessage(message: ControlMessage): void {+ if (message.type === 'start') {+ if (this.transferId === null) this.transferId = message.transferId+ else if (message.transferId !== this.transferId) return+ this.enqueue(() => this.onStart(message.size, message.chunkSize))+ return+ }+ if (this.transferId === null || message.transferId !== this.transferId) return+ switch (message.type) {+ case 'complete':+ this.enqueue(() => this.onComplete(message.fileHash))+ break+ case 'cancel':+ this.enqueue(() =>+ this.fail(new Error(message.reason ?? 'Transfer cancelled by sender'), false)+ )+ break+ }+ }++ private validGeometry(size: number, chunkSize: number): boolean {+ return Number.isSafeInteger(size) && size >= 0 && chunkSize === selectChunkSize(size)+ }++ private async onStart(size: number, chunkSize: number): Promise<void> {+ if (this.settled) return+ if (!this.validGeometry(size, chunkSize)) {+ throw new Error(`Rejected transfer geometry: size=${size} chunkSize=${chunkSize}`)+ }+ this.size = size+ this.chunkSize = chunkSize+ const total = chunkCount(size, chunkSize)+ this.bitmap = this.opts.resumeBits+ ? Bitmap.deserialize(total, this.opts.resumeBits)+ : new Bitmap(total)+ this.resumed = this.bitmap.count() > 0++ for (let i = 0; i < total; i++) {+ if (this.bitmap.get(i)) this.receivedBytes += chunkRange(i, size, chunkSize).length+ }++ await this.writer.allocate(size)+ this.channel.send({+ type: 'need',+ transferId: this.transferId!,+ indices: this.bitmap.missing()+ })+ }++ private async onChunk(header: ChunkHeader, data: Uint8Array): Promise<void> {+ if (this.settled) return+ if (header.transferId !== this.transferId) return+ const bitmap = this.bitmap+ if (!bitmap) throw new Error('Received chunk before start')+ if (!Number.isInteger(header.index) || header.index < 0 || header.index >= bitmap.size) {+ throw new Error(`Chunk index ${header.index} out of range`)+ }+ if (bitmap.get(header.index)) return++ const { offset, length } = chunkRange(header.index, this.size, this.chunkSize)+ if (data.length !== length) {+ throw new Error(`Chunk ${header.index} length ${data.length}, expected ${length}`)+ }+ if (hashChunk(data) !== header.hash) {+ throw new Error(`Chunk ${header.index} failed hash verification`)+ }++ await this.writer.write(offset, data)+ bitmap.set(header.index)+ this.receivedBytes += length+ this.opts.onChunkWritten?.(bitmap)+ this.opts.onProgress?.(this.receivedBytes, this.size)+ }++ private async onComplete(fileHash: string | null): Promise<void> {+ if (this.settled) return+ const bitmap = this.bitmap+ if (!bitmap) throw new Error('Received complete before start')+ if (!bitmap.allSet()) {+ throw new Error(`Transfer incomplete: ${bitmap.count()}/${bitmap.size} chunks`)+ }++ if (this.opts.verifyFullFile || this.resumed) {+ if (!fileHash) throw new Error('Missing file hash: cannot verify the assembled file')+ await this.verifyFullFile(fileHash)+ }++ const savedTo = await this.writer.finalize()+ this.settled = true+ try {+ this.channel.send({ type: 'ack', transferId: this.transferId!, savedTo })+ } catch {}+ this.settle.resolve(savedTo)+ }++ private async verifyFullFile(expected: string): Promise<void> {+ const root = createFileHasher()+ const total = chunkCount(this.size, this.chunkSize)+ for (let i = 0; i < total; i++) {+ const { offset, length } = chunkRange(i, this.size, this.chunkSize)+ const bytes = await this.writer.readBack(offset, length)+ if (!bytes) throw new Error('Full-file verification could not read back file')+ root.add(hashChunk(bytes))+ }+ if (root.digest() !== expected) throw new Error('Full-file hash mismatch')+ }++ private async fail(err: Error, notifyPeer = true): Promise<void> {+ if (this.settled) return+ this.settled = true+ if (notifyPeer && this.transferId !== null) {+ try {+ this.channel.send({ type: 'cancel', transferId: this.transferId })+ } catch {}+ }+ try {+ await this.writer.abort()+ } catch {}+ this.settle.reject(err)+ }+}diff --git a/packages/drive/src/engine/sender.ts b/packages/drive/src/engine/sender.tsnew file mode 100644index 0000000..2a2f0d8--- /dev/null+++ b/packages/drive/src/engine/sender.ts@@ -0,0 +1,152 @@+import type { ChunkReader, DriveChannel, ControlMessage } from './types'+import { selectChunkSize, chunkCount, chunkRange } from './chunker'+import { hashChunk, createFileHasher } from './hash'++export interface SenderOptions {+ transferId: string+ name: string+ highWaterMark?: number+ onProgress?: (sentBytes: number, totalBytes: number) => void+}++const DEFAULT_HIGH_WATER = 8 * 1024 * 1024++export class SenderSession {+ private readonly reader: ChunkReader+ private readonly channel: DriveChannel+ private readonly opts: SenderOptions+ private readonly highWater: number+ private readonly done: Promise<string>++ private size = 0+ private chunkSize = 0+ private totalChunks = 0+ private started = false+ private sending = false+ private settled = false+ private settle!: { resolve: (savedTo: string) => void; reject: (err: Error) => void }++ constructor(reader: ChunkReader, channel: DriveChannel, opts: SenderOptions) {+ this.reader = reader+ this.channel = channel+ this.opts = opts+ this.highWater = opts.highWaterMark ?? DEFAULT_HIGH_WATER+ if (!Number.isFinite(this.highWater) || this.highWater < 0) {+ throw new RangeError('highWaterMark must be a finite non-negative number')+ }+ this.done = new Promise<string>((resolve, reject) => {+ this.settle = { resolve, reject }+ })+ this.channel.onMessage((message) => this.onMessage(message))+ }++ async start(): Promise<string> {+ if (this.started) throw new Error('SenderSession already started')+ this.started = true++ this.size = await this.reader.size()+ this.chunkSize = selectChunkSize(this.size)+ this.totalChunks = chunkCount(this.size, this.chunkSize)++ this.channel.send({+ type: 'start',+ transferId: this.opts.transferId,+ name: this.opts.name,+ size: this.size,+ chunkSize: this.chunkSize+ })++ return this.done+ }++ private onMessage(message: ControlMessage): void {+ if (message.transferId !== this.opts.transferId) return+ switch (message.type) {+ case 'need':+ this.sendChunks(message.indices).catch((err) => this.fail(err))+ break+ case 'ack':+ if (this.settled) break+ this.settled = true+ this.settle.resolve(message.savedTo)+ break+ case 'cancel':+ this.fail(new Error(message.reason ?? 'Transfer cancelled by receiver'), false)+ break+ }+ }++ private validIndices(indices: number[]): boolean {+ const seen = new Set<number>()+ for (const index of indices) {+ if (!Number.isInteger(index) || index < 0 || index >= this.totalChunks) return false+ if (seen.has(index)) return false+ seen.add(index)+ }+ return true+ }++ private async sendChunks(indices: number[]): Promise<void> {+ if (this.sending) return+ this.sending = true++ if (!this.validIndices(indices)) {+ this.fail(new Error('Rejected invalid chunk request'))+ return+ }++ const inOrderFull = indices.length === this.totalChunks && indices.every((idx, i) => idx === i)+ const root = inOrderFull ? createFileHasher() : null++ let sentBytes = 0+ for (const index of indices) {+ const { offset, length } = chunkRange(index, this.size, this.chunkSize)+ const data = await this.reader.read(offset, length)+ const hash = hashChunk(data)+ root?.add(hash)++ await this.drain()+ this.channel.sendChunk({ transferId: this.opts.transferId, index, hash }, data)++ sentBytes += data.length+ this.opts.onProgress?.(sentBytes, this.size)+ }++ const fileHash = root ? root.digest() : await this.fileRoot()+ this.channel.send({+ type: 'complete',+ transferId: this.opts.transferId,+ fileHash+ })+ }++ private async fileRoot(): Promise<string> {+ const root = createFileHasher()+ for (let i = 0; i < this.totalChunks; i++) {+ const { offset, length } = chunkRange(i, this.size, this.chunkSize)+ root.add(hashChunk(await this.reader.read(offset, length)))+ }+ return root.digest()+ }++ private async drain(): Promise<void> {+ while (this.channel.bufferedAmount() > this.highWater) {+ await new Promise((resolve) => setTimeout(resolve, 1))+ }+ }++ private fail(err: Error, notifyPeer = true): void {+ if (this.settled) return+ this.settled = true+ if (notifyPeer) {+ try {+ this.channel.send({ type: 'cancel', transferId: this.opts.transferId })+ } catch {}+ }+ this.settle.reject(err)+ }++ async close(): Promise<void> {+ await this.reader.close()+ }+}diff --git a/packages/drive/src/engine/types.ts b/packages/drive/src/engine/types.tsnew file mode 100644index 0000000..7cc8e23--- /dev/null+++ b/packages/drive/src/engine/types.ts@@ -0,0 +1,67 @@+export interface ChunkReader {+ size(): Promise<number>+ read(offset: number, length: number): Promise<Uint8Array>+ close(): Promise<void>+}++export interface ChunkWriter {+ allocate(size: number): Promise<void>+ write(offset: number, data: Uint8Array): Promise<void>+ readBack(offset: number, length: number): Promise<Uint8Array | null>+ finalize(): Promise<string>+ abort(): Promise<void>+}++export interface DriveChannel {+ send(message: ControlMessage): void+ sendChunk(header: ChunkHeader, data: Uint8Array): void+ onMessage(handler: (message: ControlMessage) => void): void+ onChunk(handler: (header: ChunkHeader, data: Uint8Array) => void): void+ bufferedAmount(): number+ close(): void+}++export interface ChunkHeader {+ transferId: string+ index: number+ hash: string+}++export type ControlMessage =+ | StartMessage+ | NeedMessage+ | CompleteMessage+ | AckMessage+ | CancelMessage++export interface StartMessage {+ type: 'start'+ transferId: string+ name: string+ size: number+ chunkSize: number+}++export interface NeedMessage {+ type: 'need'+ transferId: string+ indices: number[]+}++export interface CompleteMessage {+ type: 'complete'+ transferId: string+ fileHash: string+}++export interface AckMessage {+ type: 'ack'+ transferId: string+ savedTo: string+}++export interface CancelMessage {+ type: 'cancel'+ transferId: string+ reason?: string+}diff --git a/packages/drive/src/index.ts b/packages/drive/src/index.tsnew file mode 100644index 0000000..b6d3636--- /dev/null+++ b/packages/drive/src/index.ts@@ -0,0 +1,17 @@+export { SenderSession, type SenderOptions } from './engine/sender'+export { ReceiverSession, type ReceiverOptions } from './engine/receiver'+export { Bitmap } from './engine/bitmap'+export { selectChunkSize, chunkCount, chunkRange, type ChunkRange } from './engine/chunker'+export { hashChunk, createHasher, type StreamingHasher } from './engine/hash'+export type {+ ChunkReader,+ ChunkWriter,+ DriveChannel,+ ChunkHeader,+ ControlMessage,+ StartMessage,+ NeedMessage,+ CompleteMessage,+ AckMessage,+ CancelMessage+} from './engine/types'diff --git a/packages/drive/src/native.ts b/packages/drive/src/native.tsnew file mode 100644index 0000000..b5b08cc--- /dev/null+++ b/packages/drive/src/native.ts@@ -0,0 +1,4 @@+export * from './index'+export * from './adapters/disk-reader'+export * from './adapters/disk-writer'+export * from './api/drive'diff --git a/packages/drive/test/support.ts b/packages/drive/test/support.tsnew file mode 100644index 0000000..94e9143--- /dev/null+++ b/packages/drive/test/support.ts@@ -0,0 +1,55 @@+import type { DriveChannel, ChunkHeader, ControlMessage } from '../src/engine/types'++type MessageHandler = (message: ControlMessage) => void+type ChunkHandler = (header: ChunkHeader, data: Uint8Array) => void++class LoopbackChannel implements DriveChannel {+ peer!: LoopbackChannel+ private messageHandler?: MessageHandler+ private chunkHandler?: ChunkHandler+ private readonly pendingMessages: ControlMessage[] = []+ private readonly pendingChunks: Array<{ header: ChunkHeader; data: Uint8Array }> = []++ send(message: ControlMessage): void {+ queueMicrotask(() => this.peer.deliverMessage(message))+ }++ sendChunk(header: ChunkHeader, data: Uint8Array): void {+ const copy = data.slice()+ queueMicrotask(() => this.peer.deliverChunk(header, copy))+ }++ onMessage(handler: MessageHandler): void {+ this.messageHandler = handler+ for (const message of this.pendingMessages.splice(0)) handler(message)+ }++ onChunk(handler: ChunkHandler): void {+ this.chunkHandler = handler+ for (const { header, data } of this.pendingChunks.splice(0)) handler(header, data)+ }++ bufferedAmount(): number {+ return 0+ }++ close(): void {}++ private deliverMessage(message: ControlMessage): void {+ if (this.messageHandler) this.messageHandler(message)+ else this.pendingMessages.push(message)+ }++ private deliverChunk(header: ChunkHeader, data: Uint8Array): void {+ if (this.chunkHandler) this.chunkHandler(header, data)+ else this.pendingChunks.push({ header, data })+ }+}++export function createChannelPair(): [DriveChannel, DriveChannel] {+ const a = new LoopbackChannel()+ const b = new LoopbackChannel()+ a.peer = b+ b.peer = a+ return [a, b]+}diff --git a/packages/drive/test/transfer.test.ts b/packages/drive/test/transfer.test.tsnew file mode 100644index 0000000..e92487b--- /dev/null+++ b/packages/drive/test/transfer.test.ts@@ -0,0 +1,44 @@+import { describe, it, expect, afterEach } from 'vitest'+import { mkdtemp, writeFile, readFile, rm, stat } from 'node:fs/promises'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import { SenderSession } from '../src/engine/sender'+import { ReceiverSession } from '../src/engine/receiver'+import { DiskReader } from '../src/adapters/disk-reader'+import { DiskWriter } from '../src/adapters/disk-writer'+import { createChannelPair } from './support'++let dir = ''++afterEach(async () => {+ if (dir) await rm(dir, { recursive: true, force: true })+})++describe('end-to-end transfer', () => {+ it('delivers a file byte-for-byte through the real adapters', async () => {+ dir = await mkdtemp(join(tmpdir(), 'drive-e2e-'))+ const src = join(dir, 'input.bin')+ const dst = join(dir, 'output.bin')++ const input = new Uint8Array(1024 * 1024)+ for (let i = 0; i < input.length; i++) input[i] = (i * 131 + 7) & 0xff+ await writeFile(src, input)++ const [senderChannel, receiverChannel] = createChannelPair()+ const receiver = new ReceiverSession(new DiskWriter(dst), receiverChannel, {+ transferId: 'e2e'+ })+ const sender = new SenderSession(new DiskReader(src), senderChannel, {+ transferId: 'e2e',+ name: 'output.bin'+ })++ const [savedTo] = await Promise.all([receiver.receive(), sender.start()])+ await sender.close()++ expect(savedTo).toBe(dst)+ const output = new Uint8Array(await readFile(dst))+ expect(Buffer.from(output).equals(Buffer.from(input))).toBe(true)+ await expect(stat(`${dst}.part`)).rejects.toThrow()+ })+})diff --git a/packages/drive/tsconfig.json b/packages/drive/tsconfig.jsonnew file mode 100644index 0000000..ffd0f3c--- /dev/null+++ b/packages/drive/tsconfig.json@@ -0,0 +1,13 @@+{+ "extends": "../../tsconfig.json",+ "compilerOptions": {+ "target": "ESNext",+ "module": "ESNext",+ "moduleResolution": "Bundler",+ "declaration": true,+ "outDir": "./dist",+ "lib": ["ESNext"],+ "types": ["node"]+ },+ "include": ["src/**/*", "test/**/*"]+}diff --git a/packages/drive/tsup.config.ts b/packages/drive/tsup.config.tsnew file mode 100644index 0000000..9280aef--- /dev/null+++ b/packages/drive/tsup.config.ts@@ -0,0 +1,19 @@+import { defineConfig } from 'tsup'++export default defineConfig({+ entry: {+ index: 'src/index.ts',+ native: 'src/native.ts'+ },+ format: ['esm'],+ dts: true,+ target: 'esnext',+ outDir: 'dist',+ clean: true,+ bundle: true,+ splitting: true,+ sourcemap: false,+ esbuildOptions(options) {+ options.packages = 'external'+ }+})