teyyare 0.1.0

package/test/integration/chaos.test.js

@@ -0,0 +1,104 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { serve, send, FileResumeState } from '../../src/index.js';
+
+// Deterministic PRNG (Linear Congruential Generator)
+class PRNG {
+  constructor(seed = 0x12345678) {
+    this.state = seed >>> 0;
+  }
+
+  next() {
+    this.state = (1664525 * this.state + 1013904223) >>> 0;
+    return this.state / 0x100000000;
+  }
+
+  nextInt(min, max) {
+    return Math.floor(this.next() * (max - min + 1)) + min;
+  }
+}
+
+test('Integration - deterministic chaos test: duplicate chunks, interruptions, and recovery', async () => {
+  const prng = new PRNG(42);
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'teyyare-chaos-test-'));
+  const sourceFile = path.join(tmpDir, 'chaos-source.bin');
+  const destDir = path.join(tmpDir, 'dest');
+  await fs.mkdir(destDir, { recursive: true });
+
+  // 4 MB random test data
+  const size = 4 * 1024 * 1024;
+  const data = crypto.randomBytes(size);
+  await fs.writeFile(sourceFile, data);
+  const sourceHash = crypto.createHash('sha256').update(data).digest('hex');
+
+  const destFile = path.join(destDir, 'chaos-source.bin');
+  const partPath = `${destFile}.teyyare-part`;
+  const statePath = `${destFile}.teyyare-state`;
+
+  // Chaos Step 1: Simulate interrupted transfer with duplicate chunk writes
+  const handle = await fs.open(partPath, 'w+');
+  // Write chunks 0 and 1
+  await handle.write(data.subarray(0, 1024 * 1024), 0, 1024 * 1024, 0);
+  await handle.write(data.subarray(1024 * 1024, 2 * 1024 * 1024), 0, 1024 * 1024, 1024 * 1024);
+  // Duplicate chunk 1 write (idempotency simulation)
+  await handle.write(data.subarray(1024 * 1024, 2 * 1024 * 1024), 0, 1024 * 1024, 1024 * 1024);
+  await handle.sync();
+  await handle.close();
+
+  const partialState = new FileResumeState({
+    transferId: 'chaos-session',
+    fileId: 1,
+    fileSize: size,
+    chunkSize: 1024 * 1024,
+    sha256: sourceHash,
+    verifiedChunks: new Set([0, 1])
+  });
+  await partialState.save(statePath);
+
+  // Chaos Step 2: Start server with randomized write delay jitter
+  const port = 7526;
+  const server = await serve({
+    port,
+    destinationDir: destDir,
+    writeDelayMs: prng.nextInt(5, 15) // Random jitter
+  });
+
+  // Chaos Step 3: Run resume transfer
+  const knownResume = new Map([[1, partialState]]);
+  const senderMetrics = await send({
+    sourcePath: sourceFile,
+    host: '127.0.0.1',
+    port,
+    pipelineOptions: {
+      chunkSize: 1024 * 1024,
+      maxEntries: 2
+    },
+    knownResumeState: knownResume,
+    showProgress: false
+  });
+
+  await server.receiver.waitForCompletion();
+  await server.close();
+
+  // Verification after chaos recovery
+  assert.ok(existsSync(destFile), 'Destination file must exist');
+  assert.strictEqual(existsSync(partPath), false, 'Part file must be cleaned up');
+  assert.strictEqual(existsSync(statePath), false, 'State file must be cleaned up');
+
+  const destData = await fs.readFile(destFile);
+  assert.strictEqual(destData.length, size, 'Recovered file size must match');
+
+  const destHash = crypto.createHash('sha256').update(destData).digest('hex');
+  assert.strictEqual(destHash, sourceHash, 'Source hash === destination hash must always hold!');
+
+  const snap = senderMetrics.snapshot();
+  assert.strictEqual(snap.resumeHits, 2, 'Must record 2 resume hits');
+  assert.strictEqual(snap.chunksCreated, 2, 'Must transmit remaining 2 chunks');
+
+  await fs.rm(tmpDir, { recursive: true });
+});

package/test/integration/directory.test.js

@@ -0,0 +1,75 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { serve, send } from '../../src/index.js';
+
+test('Integration - directory transfer with nested files and small-file packing', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'teyyare-dir-test-'));
+  const srcDir = path.join(tmpDir, 'source');
+  const destDir = path.join(tmpDir, 'dest');
+
+  // Create directory structure
+  await fs.mkdir(path.join(srcDir, 'assets'), { recursive: true });
+  await fs.mkdir(path.join(srcDir, 'src', 'utils'), { recursive: true });
+  await fs.mkdir(destDir, { recursive: true });
+
+  const filesToCreate = [
+    { rel: 'index.html', size: 512 },
+    { rel: 'style.css', size: 1200 },
+    { rel: 'assets/logo.svg', size: 3400 },
+    { rel: 'src/app.js', size: 15000 },
+    { rel: 'src/utils/math.js', size: 800 },
+    { rel: 'data.bin', size: 2 * 1024 * 1024 } // 2 MB
+  ];
+
+  const fileHashes = new Map();
+
+  for (const f of filesToCreate) {
+    const fullPath = path.join(srcDir, f.rel);
+    const data = crypto.randomBytes(f.size);
+    await fs.writeFile(fullPath, data);
+    fileHashes.set(f.rel, crypto.createHash('sha256').update(data).digest('hex'));
+  }
+
+  const port = 7522;
+  const server = await serve({ port, destinationDir: destDir });
+
+  const senderMetrics = await send({
+    sourcePath: srcDir,
+    host: '127.0.0.1',
+    port,
+    pipelineOptions: {
+      chunkSize: 512 * 1024,
+      maxEntries: 16
+    },
+    showProgress: false
+  });
+
+  await server.receiver.waitForCompletion();
+  await server.close();
+
+  // Verify all files reconstructed properly
+  for (const f of filesToCreate) {
+    const destPath = path.join(destDir, f.rel);
+    assert.ok(existsSync(destPath), `File ${f.rel} must exist in destination`);
+
+    const destData = await fs.readFile(destPath);
+    assert.strictEqual(destData.length, f.size, `Size must match for ${f.rel}`);
+
+    const destHash = crypto.createHash('sha256').update(destData).digest('hex');
+    assert.strictEqual(destHash, fileHashes.get(f.rel), `Hash must match for ${f.rel}`);
+
+    // Check no temp files left
+    assert.strictEqual(existsSync(`${destPath}.teyyare-part`), false);
+    assert.strictEqual(existsSync(`${destPath}.teyyare-state`), false);
+  }
+
+  const stats = senderMetrics.snapshot();
+  assert.strictEqual(stats.fileBytesRead, filesToCreate.reduce((a, b) => a + b.size, 0));
+
+  await fs.rm(tmpDir, { recursive: true });
+});

package/test/integration/resume.test.js

@@ -0,0 +1,97 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { serve, send, FileResumeState } from '../../src/index.js';
+
+test('Integration - resume after interruption at 50%, bounded retransmission, SHA-256 match', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'teyyare-resume-test-'));
+  const sourceFile = path.join(tmpDir, 'large.bin');
+  const destDir = path.join(tmpDir, 'dest');
+  await fs.mkdir(destDir, { recursive: true });
+
+  // 8 MB file (8 x 1 MiB chunks)
+  const size = 8 * 1024 * 1024;
+  const data = crypto.randomBytes(size);
+  await fs.writeFile(sourceFile, data);
+  const sourceHash = crypto.createHash('sha256').update(data).digest('hex');
+
+  const destFile = path.join(destDir, 'large.bin');
+  const partPath = `${destFile}.teyyare-part`;
+  const statePath = `${destFile}.teyyare-state`;
+
+  // --- Phase 1: Transfer first 4 chunks (50%) ---
+  const port1 = 7523;
+  const server1 = await serve({ port: port1, destinationDir: destDir });
+
+  // Pre-seed receiver with first 4 chunks as if interrupted at 50%
+  const partialState = new FileResumeState({
+    transferId: 't-interrupted',
+    fileId: 1,
+    fileSize: size,
+    chunkSize: 1024 * 1024,
+    sha256: sourceHash,
+    verifiedChunks: new Set([0, 1, 2, 3])
+  });
+  await partialState.save(statePath);
+
+  // Write first 4 MB directly into part file
+  const handle = await fs.open(partPath, 'w+');
+  await handle.write(data.subarray(0, 4 * 1024 * 1024), 0, 4 * 1024 * 1024, 0);
+  await handle.sync();
+  await handle.close();
+
+  await server1.close();
+
+  assert.ok(existsSync(partPath), 'Part file must exist at 50%');
+  assert.ok(existsSync(statePath), 'State file must exist at 50%');
+
+  // --- Phase 2: Resume transfer ---
+  const port2 = 7524;
+  const server2 = await serve({ port: port2, destinationDir: destDir });
+
+  // Sender loads the verified state
+  const knownResume = new Map();
+  const loadedState = await FileResumeState.load(statePath);
+  knownResume.set(1, loadedState);
+
+  const tResumeStart = Date.now();
+  const senderMetrics = await send({
+    sourcePath: sourceFile,
+    host: '127.0.0.1',
+    port: port2,
+    pipelineOptions: {
+      chunkSize: 1024 * 1024,
+      maxEntries: 4
+    },
+    knownResumeState: knownResume,
+    showProgress: false
+  });
+
+  await server2.receiver.waitForCompletion();
+  const resumeDuration = Date.now() - tResumeStart;
+  await server2.close();
+
+  // --- Verification ---
+  assert.ok(existsSync(destFile), 'Destination file must be finalized');
+  assert.strictEqual(existsSync(partPath), false, 'Part file must be removed');
+  assert.strictEqual(existsSync(statePath), false, 'State file must be cleaned up');
+
+  const destData = await fs.readFile(destFile);
+  assert.strictEqual(destData.length, size, 'Final size must match');
+  const destHash = crypto.createHash('sha256').update(destData).digest('hex');
+  assert.strictEqual(destHash, sourceHash, 'Final SHA-256 must match source');
+
+  const snap = senderMetrics.snapshot();
+  // Retransmission must be BOUNDED: only 4 chunks sent, 4 chunks skipped as resume hits!
+  assert.strictEqual(snap.resumeHits, 4, 'Must have 4 resume hits (50% skipped)');
+  assert.strictEqual(snap.chunksCreated, 4, 'Only 4 new chunks should be created/read');
+  assert.strictEqual(snap.fileBytesRead, 4 * 1024 * 1024, 'Only 4 MB should be read from disk');
+
+  console.log(`Resume completed in ${resumeDuration}ms with 0 re-transmitted bytes for verified chunks.`);
+
+  await fs.rm(tmpDir, { recursive: true });
+});

package/test/integration/single-file.test.js

@@ -0,0 +1,64 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { serve, send } from '../../src/index.js';
+
+test('Integration - end-to-end 10 MB single file transfer with SHA-256 verification', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'teyyare-test-'));
+  const sourceFile = path.join(tmpDir, '10mb.bin');
+  const destDir = path.join(tmpDir, 'dest');
+  await fs.mkdir(destDir, { recursive: true });
+
+  // Generate 10 MB random binary data
+  const size = 10 * 1024 * 1024;
+  const data = crypto.randomBytes(size);
+  await fs.writeFile(sourceFile, data);
+
+  const sourceHash = crypto.createHash('sha256').update(data).digest('hex');
+
+  const port = 7521;
+  const server = await serve({ port, destinationDir: destDir });
+
+  const senderMetrics = await send({
+    sourcePath: sourceFile,
+    host: '127.0.0.1',
+    port,
+    pipelineOptions: {
+      chunkSize: 1024 * 1024, // 1 MiB
+      maxEntries: 4,          // 4 MiB generations
+      maxBytes: 4 * 1024 * 1024
+    },
+    showProgress: false
+  });
+
+  await server.receiver.waitForCompletion();
+  await server.close();
+
+  const destFile = path.join(destDir, '10mb.bin');
+  assert.ok(existsSync(destFile), 'Destination file must exist');
+
+  const destData = await fs.readFile(destFile);
+  assert.strictEqual(destData.length, size, 'File size must match');
+
+  const destHash = crypto.createHash('sha256').update(destData).digest('hex');
+  assert.strictEqual(destHash, sourceHash, 'SHA-256 checksum must match source');
+
+  // Verify atomic rename and state cleanup
+  assert.strictEqual(existsSync(`${destFile}.teyyare-part`), false, 'Part file must not remain');
+  assert.strictEqual(existsSync(`${destFile}.teyyare-state`), false, 'State file must be cleaned up');
+
+  const senderStats = senderMetrics.snapshot();
+  assert.strictEqual(senderStats.chunksCreated, 10);
+  assert.strictEqual(senderStats.fileBytesRead, size);
+  assert.ok(senderStats.throughputMBs > 0, 'Throughput must be greater than 0');
+
+  const receiverStats = server.metrics.snapshot();
+  assert.strictEqual(receiverStats.fileBytesWritten, size);
+  assert.strictEqual(receiverStats.chunksVerified, 10);
+
+  await fs.rm(tmpDir, { recursive: true });
+});

package/test/unit/ownership.test.js

@@ -0,0 +1,74 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { MutableBuffer, ArenaStore, IllegalStateTransitionError, LifecycleState } from 'muttafa';
+
+test('Ownership - generation lifecycle transitions: MUTABLE -> FROZEN -> FLUSHING -> FLUSHED -> RELEASED', () => {
+  const store = new ArenaStore();
+  const mutable = new MutableBuffer(1, store);
+
+  mutable.append(1, 1, new Uint8Array([1]), new Uint8Array([2]));
+  assert.strictEqual(mutable.lifecycle.state, LifecycleState.MUTABLE);
+
+  // Freeze
+  const frozen = mutable.freeze();
+  assert.strictEqual(frozen.lifecycle.state, LifecycleState.FROZEN);
+
+  // Mark in-flight (flushing)
+  frozen.markFlushing();
+  assert.strictEqual(frozen.lifecycle.state, LifecycleState.FLUSHING);
+
+  // Mark delivered (flushed)
+  frozen.markFlushed();
+  assert.strictEqual(frozen.lifecycle.state, LifecycleState.FLUSHED);
+
+  // Safe ownership release
+  frozen.release();
+  assert.strictEqual(frozen.lifecycle.state, LifecycleState.RELEASED);
+});
+
+test('Ownership - assertion detects release while in-flight', () => {
+  const store = new ArenaStore();
+  const mutable = new MutableBuffer(2, store);
+  mutable.append(1, 1, new Uint8Array([1]), new Uint8Array([2]));
+
+  const frozen = mutable.freeze();
+  frozen.markFlushing(); // In-flight
+
+  // Attempting release while in-flight must be rejected!
+  assert.throws(() => {
+    frozen.release();
+  }, IllegalStateTransitionError);
+});
+
+test('Ownership - assertion detects double release', () => {
+  const store = new ArenaStore();
+  const mutable = new MutableBuffer(3, store);
+  mutable.append(1, 1, new Uint8Array([1]), new Uint8Array([2]));
+
+  const frozen = mutable.freeze();
+  frozen.markFlushing();
+  frozen.markFlushed();
+  frozen.release();
+
+  // Second release must throw IllegalStateTransitionError
+  assert.throws(() => {
+    frozen.release();
+  }, IllegalStateTransitionError);
+});
+
+test('Ownership - assertion detects use after release', () => {
+  const store = new ArenaStore();
+  const mutable = new MutableBuffer(4, store);
+  mutable.append(1, 1, new Uint8Array([1]), new Uint8Array([2]));
+
+  const frozen = mutable.freeze();
+  frozen.markFlushing();
+  frozen.markFlushed();
+  frozen.release();
+
+  // Store is emptied and released
+  assert.strictEqual(frozen.length, 0);
+  const bufs = frozen.buffers();
+  assert.strictEqual(bufs[0].byteLength, 0);
+  assert.strictEqual(bufs[1].byteLength, 0);
+});

package/test/unit/protocol.test.js

@@ -0,0 +1,73 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import {
+  Opcodes,
+  CHUNK_META_SIZE,
+  packChunkMeta,
+  unpackChunkMeta,
+  packFileBegin,
+  unpackFileBegin,
+  packTransferBegin,
+  unpackTransferBegin,
+  packFileEnd,
+  unpackFileEnd
+} from '../../src/core/protocol.js';
+
+test('Protocol - pack and unpack chunk metadata', () => {
+  const meta = {
+    fileId: 42,
+    chunkIndex: 105,
+    offset: 104857600n,
+    length: 1048576,
+    checksum: 0x1a2b3c4d,
+    flags: 1
+  };
+
+  const packed = packChunkMeta(meta);
+  assert.strictEqual(packed.byteLength, CHUNK_META_SIZE);
+
+  const unpacked = unpackChunkMeta(packed);
+  assert.strictEqual(unpacked.fileId, meta.fileId);
+  assert.strictEqual(unpacked.chunkIndex, meta.chunkIndex);
+  assert.strictEqual(unpacked.offset, meta.offset);
+  assert.strictEqual(unpacked.length, meta.length);
+  assert.strictEqual(unpacked.checksum, meta.checksum);
+  assert.strictEqual(unpacked.flags, meta.flags);
+});
+
+test('Protocol - pack and unpack file begin and end', () => {
+  const fbegin = packFileBegin({
+    fileId: 7,
+    fileSize: 10737418240, // 10 GB
+    path: 'videos/action/movie.mkv',
+    sha256: 'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789'
+  });
+
+  const unpackedBegin = unpackFileBegin(fbegin);
+  assert.strictEqual(unpackedBegin.fileId, 7);
+  assert.strictEqual(unpackedBegin.fileSize, 10737418240n);
+  assert.strictEqual(unpackedBegin.path, 'videos/action/movie.mkv');
+  assert.strictEqual(unpackedBegin.sha256, 'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789');
+
+  const fend = packFileEnd({
+    fileId: 7,
+    sha256: 'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789'
+  });
+
+  const unpackedEnd = unpackFileEnd(fend);
+  assert.strictEqual(unpackedEnd.fileId, 7);
+  assert.strictEqual(unpackedEnd.sha256, 'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789');
+});
+
+test('Protocol - pack and unpack transfer begin', () => {
+  const tbegin = packTransferBegin({
+    transferId: 'session-uuid-12345',
+    fileCount: 250,
+    totalBytes: 53687091200
+  });
+
+  const unpacked = unpackTransferBegin(tbegin);
+  assert.strictEqual(unpacked.transferId, 'session-uuid-12345');
+  assert.strictEqual(unpacked.fileCount, 250);
+  assert.strictEqual(unpacked.totalBytes, 53687091200n);
+});

package/test/unit/state.test.js

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { FileResumeState } from '../../src/resume/state.js';
+
+test('FileResumeState - tracks verified chunks and missing chunks', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'teyyare-state-test-'));
+  const statePath = path.join(tmpDir, 'test.state');
+
+  const state = new FileResumeState({
+    transferId: 't1',
+    fileId: 1,
+    fileSize: 10 * 1024 * 1024, // 10 MB
+    chunkSize: 1024 * 1024 // 1 MiB -> 10 chunks
+  });
+
+  assert.strictEqual(state.totalChunks, 10);
+  assert.strictEqual(state.verifiedCount, 0);
+  assert.strictEqual(state.isComplete(), false);
+
+  state.markVerified(0);
+  state.markVerified(1);
+  state.markVerified(5);
+
+  assert.strictEqual(state.isVerified(0), true);
+  assert.strictEqual(state.isVerified(2), false);
+  assert.strictEqual(state.verifiedCount, 3);
+
+  const missing = state.getMissingChunks();
+  assert.deepStrictEqual(missing, [2, 3, 4, 6, 7, 8, 9]);
+
+  // Atomic save and reload
+  await state.save(statePath);
+
+  const reloaded = await FileResumeState.load(statePath);
+  assert.ok(reloaded);
+  assert.strictEqual(reloaded.transferId, 't1');
+  assert.strictEqual(reloaded.verifiedCount, 3);
+  assert.strictEqual(reloaded.isVerified(5), true);
+  assert.strictEqual(reloaded.isVerified(3), false);
+
+  await FileResumeState.cleanup(statePath);
+  const afterCleanup = await FileResumeState.load(statePath);
+  assert.strictEqual(afterCleanup, null);
+
+  await fs.rm(tmpDir, { recursive: true });
+});