teyyare 0.1.1 → 0.2.1

package/bin/teyyare.js

@@ -5,7 +5,7 @@
  */
 
 import path from 'node:path';
-import { serve, send } from '../src/index.js';
+import { serve, send, pull } from '../src/index.js';
 
 function printUsage() {
   console.log(`
@@ -106,9 +106,35 @@ Protocol overhead:${snap.protocolOverheadPercent.toFixed(2)}%
 Peak RSS:         ${(snap.peakRSS / (1024 * 1024)).toFixed(2)} MB
 `);
   } else if (command === 'pull') {
-    console.log('Pull command: inverting peer roles to request remote transfer.');
-    // In point-to-point architecture, pull is receiver-initiated transfer
-    console.error('Pulling is handled via remote agent or server command.');
+    const source = args[1];
+    const target = args[2] || './';
+
+    if (!source) {
+      console.error('Error: teyyare pull requires <source> and [destination]');
+      printUsage();
+      process.exit(1);
+    }
+
+    const { host, port, destPath: remotePath } = parseDestination(source);
+    const metrics = await pull({
+      sourceRemotePath: remotePath,
+      host,
+      port,
+      destinationDir: target,
+      showProgress: true
+    });
+
+    const snap = metrics.snapshot();
+    console.log(`
+\x1b[1m\x1b[32mPull completed successfully!\x1b[0m
+Throughput:       \x1b[1m${snap.throughputMBs.toFixed(2)} MB/s\x1b[0m
+Duration:         ${(snap.elapsedMs / 1000).toFixed(2)}s
+Bytes:            ${(snap.fileBytesWritten / (1024 * 1024)).toFixed(2)} MB
+Generations:      ${snap.generations}
+Backpressure:     ${snap.backpressureCount}
+Protocol overhead:${snap.protocolOverheadPercent.toFixed(2)}%
+Peak RSS:         ${(snap.peakRSS / (1024 * 1024)).toFixed(2)} MB
+`);
   } else if (command === 'status') {
     console.log('\x1b[1m\x1b[36mTeyyare\x1b[0m v0.1.0 status: ready');
   } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teyyare",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "High-performance resumable file transfer engine and CLI built on muttafa and raptiye",
   "main": "src/index.js",
   "type": "module",

package/src/core/generation.js

@@ -0,0 +1,107 @@
+/**
+ * Zero-copy generation framing and buffer extraction utilities.
+ * Ensures complete compatibility across all versions of Muttafa and Raptiye.
+ */
+
+/**
+ * Extract scatter/gather buffers [metaBuf, payloadBuf] from any Muttafa generation.
+ * @param {object} batch
+ * @returns {Uint8Array[]}
+ */
+export function extractGenerationBuffers(batch) {
+  if (typeof batch.buffers === 'function') {
+    return batch.buffers();
+  }
+
+  const store = batch.store || batch;
+  if (typeof store.buffers === 'function') {
+    return store.buffers();
+  }
+
+  // Direct extraction from ArenaStore
+  const rawBuf = store._allocator?.rawBuffer;
+  const payload = rawBuf ? rawBuf.subarray(0, store._allocator.usedBytes) : new Uint8Array(0);
+  const metaBuf = new Uint8Array(store.length * 25);
+  const view = new DataView(metaBuf.buffer, metaBuf.byteOffset, metaBuf.byteLength);
+
+  let off = 0;
+  const chunks = store._chunks || [];
+  for (let c = 0; c < chunks.length; c++) {
+    const chunk = chunks[c];
+    for (let i = 0; i < chunk.count; i++) {
+      view.setFloat64(off, chunk.seqs[i], true);
+      view.setUint8(off + 8, chunk.types[i]);
+      view.setUint32(off + 9, chunk.keyOffsets[i], true);
+      view.setUint32(off + 13, chunk.keyLengths[i], true);
+      view.setUint32(off + 17, chunk.valOffsets[i], true);
+      view.setUint32(off + 21, chunk.valLengths[i], true);
+      off += 25;
+    }
+  }
+
+  return [metaBuf, payload];
+}
+
+/**
+ * Fast zero-copy generator / unpacker for received generation buffers.
+ * @param {Uint8Array} metaBuf
+ * @param {Uint8Array} payloadBuf
+ * @returns {Array<{ seq: number, type: number, key: Uint8Array, val: Uint8Array }>}
+ */
+export function unpackGeneration(metaBuf, payloadBuf) {
+  const entryCount = (metaBuf.byteLength / 25) | 0;
+  const view = new DataView(metaBuf.buffer, metaBuf.byteOffset, metaBuf.byteLength);
+  const entries = new Array(entryCount);
+
+  let off = 0;
+  for (let i = 0; i < entryCount; i++) {
+    const seq = view.getFloat64(off, true);
+    const type = view.getUint8(off + 8);
+    const keyOffset = view.getUint32(off + 9, true);
+    const keyLength = view.getUint32(off + 13, true);
+    const valOffset = view.getUint32(off + 17, true);
+    const valLength = view.getUint32(off + 21, true);
+    off += 25;
+
+    entries[i] = {
+      seq,
+      type,
+      key: payloadBuf.subarray(keyOffset, keyOffset + keyLength),
+      val: payloadBuf.subarray(valOffset, valOffset + valLength)
+    };
+  }
+
+  return entries;
+}
+
+/**
+ * Pack a single-mutation batch directly into scatter/gather wire buffers.
+ * @param {number} generationId
+ * @param {number} opcode
+ * @param {Uint8Array} key
+ * @param {Uint8Array} [val]
+ * @returns {object}
+ */
+export function packSingleMutationBatch(generationId, opcode, key, val = new Uint8Array(0)) {
+  const metaBuf = new Uint8Array(25);
+  const view = new DataView(metaBuf.buffer, metaBuf.byteOffset, 25);
+  view.setFloat64(0, 1, true); // seq
+  view.setUint8(8, opcode);
+  view.setUint32(9, 0, true); // keyOffset
+  view.setUint32(13, key.byteLength, true); // keyLength
+  view.setUint32(17, key.byteLength, true); // valOffset
+  view.setUint32(21, val.byteLength, true); // valLength
+
+  const payloadBuf = new Uint8Array(key.byteLength + val.byteLength);
+  payloadBuf.set(key, 0);
+  payloadBuf.set(val, key.byteLength);
+
+  return {
+    generationId,
+    firstSequence: 1,
+    lastSequence: 1,
+    entryCount: 1,
+    byteLength: metaBuf.byteLength + payloadBuf.byteLength,
+    buffers: [metaBuf, payloadBuf]
+  };
+}

package/src/core/protocol.js

@@ -11,7 +11,9 @@ export const Opcodes = Object.freeze({
   FILE_BEGIN: 11,
   CHUNK: 12,
   FILE_END: 13,
-  TRANSFER_END: 14
+  TRANSFER_END: 14,
+  PULL_REQUEST: 15,
+  PULL_ERROR: 16
 });
 
 export const CHUNK_META_SIZE = 25;
@@ -161,3 +163,44 @@ export function unpackTransferEnd(buf) {
   const transferId = decoder.decode(buf.subarray(3, 3 + idLen));
   return { transferId, status };
 }
+
+/**
+ * Pack PULL_REQUEST metadata.
+ */
+export function packPullRequest({ remotePath }) {
+  const pathBytes = encoder.encode(remotePath);
+  const buf = new Uint8Array(2 + pathBytes.byteLength);
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  view.setUint16(0, pathBytes.byteLength, false);
+  buf.set(pathBytes, 2);
+  return buf;
+}
+
+export function unpackPullRequest(buf) {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  const pathLen = view.getUint16(0, false);
+  const remotePath = decoder.decode(buf.subarray(2, 2 + pathLen));
+  return { remotePath };
+}
+
+/**
+ * Pack PULL_ERROR metadata.
+ */
+export function packPullError({ errorCode = 1, message = '' }) {
+  const msgBytes = encoder.encode(message);
+  const buf = new Uint8Array(6 + msgBytes.byteLength);
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  view.setUint32(0, errorCode, false);
+  view.setUint16(4, msgBytes.byteLength, false);
+  buf.set(msgBytes, 6);
+  return buf;
+}
+
+export function unpackPullError(buf) {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  const errorCode = view.getUint32(0, false);
+  const msgLen = view.getUint16(4, false);
+  const message = decoder.decode(buf.subarray(6, 6 + msgLen));
+  return { errorCode, message };
+}
+

package/src/index.js

@@ -3,6 +3,7 @@
  */
 
 import path from 'node:path';
+import { existsSync } from 'node:fs';
 import { TCPTransport, ReplicationPipeline } from 'raptiye';
 import { SenderPipeline } from './sender/pipeline.js';
 import { ReceiverPipeline } from './receiver/pipeline.js';
@@ -10,7 +11,16 @@ import { TransferManifest } from './manifest/manifest.js';
 import { FileResumeState } from './resume/state.js';
 import { MetricsCollector } from './metrics/collector.js';
 import { ProgressReporter } from './cli/progress.js';
-import { Opcodes, packChunkMeta, unpackChunkMeta } from './core/protocol.js';
+import { packSingleMutationBatch, unpackGeneration } from './core/generation.js';
+import {
+  Opcodes,
+  packChunkMeta,
+  unpackChunkMeta,
+  packPullRequest,
+  unpackPullRequest,
+  packPullError,
+  unpackPullError
+} from './core/protocol.js';
 
 export {
   SenderPipeline,
@@ -21,11 +31,22 @@ export {
   ProgressReporter,
   Opcodes,
   packChunkMeta,
-  unpackChunkMeta
+  unpackChunkMeta,
+  packPullRequest,
+  unpackPullRequest,
+  packPullError,
+  unpackPullError
 };
 
+async function submitSingleMutation(replication, opcode, key, value = new Uint8Array(0)) {
+  const batch = packSingleMutationBatch(Date.now() & 0x7fffffff, opcode, key, value);
+  const receipt = await replication.submitBatch(batch);
+  await receipt.delivered();
+}
+
 /**
- * Start a Teyyare receiver server.
+ * Start a Teyyare receiver/file server.
+ * Handles both incoming push transfers (send) and remote pull requests (pull).
  * @param {object} options
  * @param {number} [options.port=7421]
  * @param {string} [options.host='0.0.0.0']
@@ -61,7 +82,42 @@ export async function serve({
     replication,
     destinationDir,
     metrics,
-    writeDelayMs
+    writeDelayMs,
+    autoHookBatch: false
+  });
+
+  replication.onBatch(async (msg) => {
+    if (!msg.buffers || msg.buffers.length < 2) return;
+    const [metaBuf, payloadBuf] = msg.buffers;
+    const entries = unpackGeneration(metaBuf, payloadBuf);
+    if (entries.length > 0 && entries[0].type === Opcodes.PULL_REQUEST) {
+      const { remotePath } = unpackPullRequest(entries[0].key);
+      let resolved = path.isAbsolute(remotePath) ? remotePath : path.resolve(destinationDir, remotePath);
+      if (!existsSync(resolved)) {
+        const alt = path.resolve(destinationDir, remotePath);
+        if (existsSync(alt)) resolved = alt;
+      }
+
+      if (!existsSync(resolved)) {
+        await submitSingleMutation(
+          replication,
+          Opcodes.PULL_ERROR,
+          packPullError({ errorCode: 404, message: `Path not found on remote: ${remotePath}` })
+        );
+        return;
+      }
+
+      const manifest = await TransferManifest.build(resolved);
+      const sender = new SenderPipeline({
+        replication,
+        manifest,
+        metrics
+      });
+      await sender.transfer();
+      return;
+    }
+
+    await receiver._processGenerationBatch(msg);
   });
 
   return {
@@ -137,3 +193,71 @@ export async function send({
 
   return metrics;
 }
+
+/**
+ * Pull a file or directory from a remote Teyyare server.
+ * @param {object} options
+ * @param {string} options.sourceRemotePath
+ * @param {string} [options.host='127.0.0.1']
+ * @param {number} [options.port=7421]
+ * @param {string} [options.destinationDir='./']
+ * @param {object} [options.pipelineOptions]
+ * @param {boolean} [options.showProgress=true]
+ * @returns {Promise<MetricsCollector>}
+ */
+export async function pull({
+  sourceRemotePath,
+  host = '127.0.0.1',
+  port = 7421,
+  destinationDir = './',
+  pipelineOptions = {},
+  showProgress = true
+}) {
+  const metrics = new MetricsCollector();
+  const progress = showProgress ? new ProgressReporter() : null;
+  if (progress) progress.start();
+
+  const clientPort = 10000 + Math.floor(Math.random() * 20000);
+  const transport = new TCPTransport({
+    id: 1,
+    port: clientPort,
+    host: '127.0.0.1',
+    peerAddresses: new Map([[2, { host, port }]])
+  });
+
+  await transport.start();
+
+  const replication = new ReplicationPipeline({
+    transport,
+    localNode: 1,
+    remoteNode: 2,
+    maxInflightBatches: pipelineOptions.maxInflightBatches || 16,
+    maxInflightBytes: pipelineOptions.maxInflightBytes || 64 * 1024 * 1024
+  });
+
+  const receiver = new ReceiverPipeline({
+    replication,
+    destinationDir,
+    metrics,
+    progress
+  });
+
+  try {
+    // Submit PULL_REQUEST batch
+    await submitSingleMutation(
+      replication,
+      Opcodes.PULL_REQUEST,
+      packPullRequest({ remotePath: sourceRemotePath })
+    );
+
+    // Wait for receiver pipeline to receive and write all files
+    await receiver.waitForCompletion();
+  } finally {
+    if (progress) progress.stop();
+    metrics.stop();
+    await transport.close();
+  }
+
+  return metrics;
+}
+

package/src/receiver/pipeline.js

@@ -8,9 +8,9 @@ import fs from 'node:fs/promises';
 import { existsSync, createReadStream } from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { FrozenArenaStore } from 'muttafa';
 import { crc32 } from 'raptiye';
-import { Opcodes, unpackChunkMeta, unpackFileBegin, unpackTransferBegin, unpackFileEnd } from '../core/protocol.js';
+import { Opcodes, unpackChunkMeta, unpackFileBegin, unpackTransferBegin, unpackFileEnd, unpackPullError } from '../core/protocol.js';
+import { unpackGeneration } from '../core/generation.js';
 import { FileResumeState } from '../resume/state.js';
 
 export class ReceiverPipeline {
@@ -25,27 +25,38 @@ export class ReceiverPipeline {
     replication,
     destinationDir,
     metrics = null,
-    writeDelayMs = 0
+    progress = null,
+    writeDelayMs = 0,
+    autoHookBatch = true
   }) {
     this.replication = replication;
     this.destinationDir = path.resolve(destinationDir);
     this.metrics = metrics;
+    this.progress = progress;
     this.writeDelayMs = writeDelayMs;
 
     this.activeFiles = new Map(); // fileId -> { destPath, partPath, statePath, fileHandle, resumeState, ... }
     this.completedFiles = new Set();
     this.transferFinished = false;
+    this.transferError = null;
     this._finishResolvers = [];
+    this._errorRejecters = [];
 
-    // Hook up Raptiye batch handler
-    this.replication.onBatch(async (msg) => {
-      await this._processGenerationBatch(msg);
-    });
+    // Hook up Raptiye batch handler if autoHookBatch is true
+    if (this.replication && autoHookBatch) {
+      this.replication.onBatch(async (msg) => {
+        await this._processGenerationBatch(msg);
+      });
+    }
   }
 
   async waitForCompletion() {
+    if (this.transferError) throw this.transferError;
     if (this.transferFinished) return;
-    return new Promise((resolve) => this._finishResolvers.push(resolve));
+    return new Promise((resolve, reject) => {
+      this._finishResolvers.push(resolve);
+      this._errorRejecters.push(reject);
+    });
   }
 
   async _processGenerationBatch(msg) {
@@ -59,14 +70,12 @@ export class ReceiverPipeline {
       this.metrics.generationBytes += (metaBuf.byteLength + payloadBuf.byteLength);
     }
 
-    // Zero-copy reconstruction of Muttafa generation
-    const store = FrozenArenaStore.fromBuffers(metaBuf, payloadBuf);
-    const count = store.length;
+    // Zero-copy unpacking of generation entries
+    const entries = unpackGeneration(metaBuf, payloadBuf);
+    const count = entries.length;
 
     for (let i = 0; i < count; i++) {
-      const type = store.getType(i);
-      const key = store.getKey(i);
-      const val = store.getValue(i);
+      const { type, key, val } = entries[i];
 
       if (this.metrics) {
         this.metrics.mutations++;
@@ -74,6 +83,8 @@ export class ReceiverPipeline {
 
       switch (type) {
         case Opcodes.TRANSFER_BEGIN: {
+          this.transferFinished = false;
+          this.transferError = null;
           const tinfo = unpackTransferBegin(key);
           break;
         }
@@ -99,8 +110,21 @@ export class ReceiverPipeline {
             resolve();
           }
           this._finishResolvers = [];
+          this._errorRejecters = [];
           break;
         }
+
+        case Opcodes.PULL_ERROR: {
+          const { errorCode, message } = unpackPullError(key);
+          const err = new Error(`Remote pull error [${errorCode}]: ${message}`);
+          this.transferError = err;
+          for (const reject of this._errorRejecters) {
+            reject(err);
+          }
+          this._finishResolvers = [];
+          this._errorRejecters = [];
+          return;
+        }
       }
     }
   }
@@ -138,6 +162,13 @@ export class ReceiverPipeline {
       sha256: info.sha256,
       chunksWrittenSinceSave: 0
     });
+
+    if (this.progress) {
+      this.progress.update({
+        fileName: info.path,
+        totalBytes: Number(info.fileSize)
+      });
+    }
   }
 
   async _handleChunk(key, val) {
@@ -184,6 +215,14 @@ export class ReceiverPipeline {
       this.metrics.chunksVerified++;
     }
 
+    if (this.progress) {
+      this.progress.update({
+        fileName: file.relativePath,
+        bytesDone: this.metrics ? this.metrics.fileBytesWritten : 0,
+        chunksDone: this.metrics ? this.metrics.chunksVerified : 0
+      });
+    }
+
     file.resumeState.markVerified(meta.chunkIndex);
     file.chunksWrittenSinceSave++;
 

package/src/sender/pipeline.js

@@ -17,6 +17,8 @@ import {
   packTransferBegin,
   packTransferEnd
 } from '../core/protocol.js';
+import { extractGenerationBuffers } from '../core/generation.js';
+import { FileResumeState } from '../resume/state.js';
 
 class RaptiyeSink extends Sink {
   /**
@@ -36,20 +38,23 @@ class RaptiyeSink extends Sink {
    * @param {import('muttafa').ImmutableBuffer} batch
    */
   async flush(batch) {
-    const buffers = batch.buffers();
+    const buffers = extractGenerationBuffers(batch);
     const t0 = Date.now();
+    const generationId = batch.generationId || batch.generation || 1;
+    const entryCount = batch.entryCount || batch.store?.length || 1;
+    const byteLength = batch.byteLength || (buffers[0].byteLength + buffers[1].byteLength);
 
     if (this.metrics) {
       this.metrics.generations++;
-      this.metrics.generationBytes += batch.byteLength;
+      this.metrics.generationBytes += byteLength;
     }
 
     const receipt = await this.replication.submitBatch({
-      generationId: batch.generationId,
-      firstSequence: batch.firstSequence,
-      lastSequence: batch.lastSequence,
-      entryCount: batch.entryCount,
-      byteLength: batch.byteLength,
+      generationId,
+      firstSequence: batch.firstSequence || 1,
+      lastSequence: batch.lastSequence || 1,
+      entryCount,
+      byteLength,
       buffers
     });
 

package/test/integration/pull.test.js

@@ -0,0 +1,131 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { serve, pull } from '../../src/index.js';
+
+async function computeSha256(filePath) {
+  const content = await fs.readFile(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+test('Integration - end-to-end file pull with SHA-256 verification', async () => {
+  const testDir = path.resolve('tmp/pull-test-single');
+  const serverDir = path.join(testDir, 'server');
+  const clientDir = path.join(testDir, 'client');
+
+  await fs.rm(testDir, { recursive: true, force: true });
+  await fs.mkdir(serverDir, { recursive: true });
+  await fs.mkdir(clientDir, { recursive: true });
+
+  // Create 5 MB test file
+  const testFile = path.join(serverDir, 'archive.bin');
+  const size = 5 * 1024 * 1024;
+  const buf = Buffer.alloc(size);
+  for (let i = 0; i < size; i += 4096) {
+    buf.writeUInt32LE((i * 17) >>> 0, i);
+  }
+  await fs.writeFile(testFile, buf);
+  const sourceSha = await computeSha256(testFile);
+
+  const port = 8821;
+  const server = await serve({ port, destinationDir: serverDir });
+
+  try {
+    const metrics = await pull({
+      sourceRemotePath: 'archive.bin',
+      host: '127.0.0.1',
+      port,
+      destinationDir: clientDir,
+      showProgress: false
+    });
+
+    const pulledFile = path.join(clientDir, 'archive.bin');
+    assert.strictEqual(await fs.stat(pulledFile).then(s => s.size), size);
+
+    const pulledSha = await computeSha256(pulledFile);
+    assert.strictEqual(pulledSha, sourceSha);
+
+    const snap = metrics.snapshot();
+    assert.strictEqual(snap.fileBytesWritten, size);
+  } finally {
+    await server.close();
+    await fs.rm(testDir, { recursive: true, force: true });
+  }
+});
+
+test('Integration - directory pull with nested structure', async () => {
+  const testDir = path.resolve('tmp/pull-test-dir');
+  const serverDir = path.join(testDir, 'server');
+  const clientDir = path.join(testDir, 'client');
+
+  await fs.rm(testDir, { recursive: true, force: true });
+  await fs.mkdir(serverDir, { recursive: true });
+  await fs.mkdir(clientDir, { recursive: true });
+
+  const tree = {
+    'docs/readme.txt': 'Hello world documentation',
+    'src/index.js': 'console.log("hello");',
+    'src/nested/deep.json': JSON.stringify({ ok: true, nested: [1, 2, 3] })
+  };
+
+  for (const [relPath, content] of Object.entries(tree)) {
+    const fullPath = path.join(serverDir, 'my-pkg', relPath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    await fs.writeFile(fullPath, content);
+  }
+
+  const port = 8822;
+  const server = await serve({ port, destinationDir: serverDir });
+
+  try {
+    await pull({
+      sourceRemotePath: 'my-pkg',
+      host: '127.0.0.1',
+      port,
+      destinationDir: clientDir,
+      showProgress: false
+    });
+
+    for (const [relPath, content] of Object.entries(tree)) {
+      const destFile = path.join(clientDir, relPath);
+      const read = await fs.readFile(destFile, 'utf8');
+      assert.strictEqual(read, content);
+    }
+  } finally {
+    await server.close();
+    await fs.rm(testDir, { recursive: true, force: true });
+  }
+});
+
+test('Integration - pull non-existent path throws remote error', async () => {
+  const testDir = path.resolve('tmp/pull-test-err');
+  const serverDir = path.join(testDir, 'server');
+  const clientDir = path.join(testDir, 'client');
+
+  await fs.rm(testDir, { recursive: true, force: true });
+  await fs.mkdir(serverDir, { recursive: true });
+  await fs.mkdir(clientDir, { recursive: true });
+
+  const port = 8823;
+  const server = await serve({ port, destinationDir: serverDir });
+
+  try {
+    await assert.rejects(
+      async () => {
+        await pull({
+          sourceRemotePath: 'does-not-exist.tar',
+          host: '127.0.0.1',
+          port,
+          destinationDir: clientDir,
+          showProgress: false
+        });
+      },
+      /Remote pull error \[404\]: Path not found on remote/
+    );
+  } finally {
+    await server.close();
+    await fs.rm(testDir, { recursive: true, force: true });
+  }
+});

package/test/unit/protocol.test.js

@@ -10,7 +10,11 @@ import {
   packTransferBegin,
   unpackTransferBegin,
   packFileEnd,
-  unpackFileEnd
+  unpackFileEnd,
+  packPullRequest,
+  unpackPullRequest,
+  packPullError,
+  unpackPullError
 } from '../../src/core/protocol.js';
 
 test('Protocol - pack and unpack chunk metadata', () => {
@@ -71,3 +75,17 @@ test('Protocol - pack and unpack transfer begin', () => {
   assert.strictEqual(unpacked.fileCount, 250);
   assert.strictEqual(unpacked.totalBytes, 53687091200n);
 });
+
+test('Protocol - pack and unpack pull request', () => {
+  const req = packPullRequest({ remotePath: '/root/cdn/app.zip' });
+  const unpacked = unpackPullRequest(req);
+  assert.strictEqual(unpacked.remotePath, '/root/cdn/app.zip');
+});
+
+test('Protocol - pack and unpack pull error', () => {
+  const err = packPullError({ errorCode: 404, message: 'File not found: /nonexistent' });
+  const unpacked = unpackPullError(err);
+  assert.strictEqual(unpacked.errorCode, 404);
+  assert.strictEqual(unpacked.message, 'File not found: /nonexistent');
+});
+