Skip to content

Send files directly between devices over the internet - no cloud storage, no size limits.

Add drive: chunked file transfer package (#60)

Denis Lupookovc8cddf3eee64
diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
index b0f3328..07c9708 100644
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@@ -38,6 +38,7 @@ jobs:
- name: Type-check
run: |
npm run typecheck -w packages/core
+ npm run typecheck -w packages/drive
npm run typecheck -w packages/locales
npm run typecheck -w packages/domain
npm run typecheck -w packages/components
diff --git a/.gitignore b/.gitignore
index 4b1def3..24292f8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -54,6 +54,9 @@ yarn-error.log*
# Internal — not for the public repo
app-marketing-context.md
+# Local tooling config
+.claude/
+
# Electron
release
apps/desktop/dist
diff --git a/knip.json b/knip.json
index 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.json
index 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.json
index 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.md
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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'
+ }
+})