raptiye 0.1.0

package/test/integration/node.test.js

@@ -0,0 +1,78 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Raptiye, MemoryNetwork, MemoryTransport, MemoryLog } from '../../index.js';
+
+test('Raptiye Node - 3-node cluster live replication and leadership transfer', async () => {
+  const net = new MemoryNetwork();
+
+  const appliedEntries = new Map([[1, []], [2, []], [3, []]]);
+
+  const node1 = new Raptiye({
+    id: 1,
+    peers: [2, 3],
+    storage: new MemoryLog(),
+    transport: new MemoryTransport(1, net),
+    apply: (e) => appliedEntries.get(1).push(e),
+    election: { minTimeout: 100, maxTimeout: 200 },
+    heartbeatInterval: 30
+  });
+
+  const node2 = new Raptiye({
+    id: 2,
+    peers: [1, 3],
+    storage: new MemoryLog(),
+    transport: new MemoryTransport(2, net),
+    apply: (e) => appliedEntries.get(2).push(e),
+    election: { minTimeout: 100, maxTimeout: 200 },
+    heartbeatInterval: 30
+  });
+
+  const node3 = new Raptiye({
+    id: 3,
+    peers: [1, 2],
+    storage: new MemoryLog(),
+    transport: new MemoryTransport(3, net),
+    apply: (e) => appliedEntries.get(3).push(e),
+    election: { minTimeout: 100, maxTimeout: 200 },
+    heartbeatInterval: 30
+  });
+
+  const nodes = [node1, node2, node3];
+
+  try {
+    await Promise.all(nodes.map(n => n.start()));
+
+    // Wait for a leader to be elected
+    const start = Date.now();
+    let leader = null;
+    while (!leader && Date.now() - start < 3000) {
+      leader = nodes.find(n => n.role() === 'LEADER');
+      if (!leader) await new Promise(r => setTimeout(r, 25));
+    }
+
+    assert.ok(leader, 'A leader must be elected');
+    const leaderId = leader.id;
+
+    // Submit 5 binary payloads
+    for (let i = 1; i <= 5; i++) {
+      const payload = new Uint8Array([10 * i, 20 * i, 30 * i]);
+      const seq = leader.submit(payload);
+      await leader.committed(seq);
+    }
+
+    const stats = leader.stats();
+    assert.equal(stats.role, 'LEADER');
+    assert.ok(stats.submitted >= 5);
+    assert.ok(stats.committed >= 5);
+    assert.equal(stats.copiedBytes, 0, 'Zero payload copies in steady state');
+
+    // Transfer leadership to an eligible peer
+    const targetPeer = nodes.find(n => n.id !== leaderId);
+    await leader.transferLeadership(targetPeer.id);
+
+    // Verify target became leader or leader stepped down
+    assert.notEqual(leader.role(), 'LEADER');
+  } finally {
+    await Promise.all(nodes.map(n => n.shutdown()));
+  }
+});

package/test/integration/replication-pipeline.test.js

@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { TCPTransport, ReplicationPipeline } from '../../index.js';
+
+test('ReplicationPipeline - point-to-point batch delivery over TCP with scatter-gather', async () => {
+  const p1Port = 9182;
+  const p2Port = 9183;
+  const t1 = new TCPTransport({ id: 1, port: p1Port, peerAddresses: new Map([[2, { host: '127.0.0.1', port: p2Port }]]) });
+  const t2 = new TCPTransport({ id: 2, port: p2Port, peerAddresses: new Map([[1, { host: '127.0.0.1', port: p1Port }]]) });
+
+  await t1.start();
+  await t2.start();
+
+  const p1 = new ReplicationPipeline({ transport: t1, localNode: 1, remoteNode: 2 });
+  const p2 = new ReplicationPipeline({ transport: t2, localNode: 2, remoteNode: 1 });
+
+  const receivedBatches = [];
+  p2.onBatch(async (batch) => {
+    receivedBatches.push(batch);
+  });
+
+  const metaBuf = new Uint8Array([10, 20, 30]);
+  const payloadBuf = new Uint8Array([100, 101, 102, 103, 104]);
+
+  const receipt = await p1.submitBatch({
+    generationId: 101,
+    firstSequence: 1n,
+    lastSequence: 5n,
+    entryCount: 5,
+    buffers: [metaBuf, payloadBuf]
+  });
+
+  const ack = await receipt.delivered();
+  assert.strictEqual(ack.generationId, 101);
+  assert.strictEqual(ack.status, 0);
+
+  assert.strictEqual(receivedBatches.length, 1);
+  assert.strictEqual(receivedBatches[0].generationId, 101);
+  assert.strictEqual(receivedBatches[0].buffers.length, 2);
+  assert.deepStrictEqual(Array.from(receivedBatches[0].buffers[0]), [10, 20, 30]);
+  assert.deepStrictEqual(Array.from(receivedBatches[0].buffers[1]), [100, 101, 102, 103, 104]);
+
+  await t1.close();
+  await t2.close();
+});

package/test/unit/core.test.js

@@ -0,0 +1,163 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { ConsensusEngine } from '../../src/core/engine.js';
+import { MemoryLog } from '../../src/storage/memory-log.js';
+import { Role, MessageType, EffectType, EventType } from '../../src/types.js';
+
+test('ConsensusEngine - PreVote and Election flow', () => {
+  const log1 = new MemoryLog();
+  const node1 = new ConsensusEngine({
+    id: 1,
+    peers: [2, 3],
+    storage: log1
+  });
+
+  assert.equal(node1.role, Role.FOLLOWER);
+  assert.equal(node1.currentTerm, 0n);
+
+  // 1. Election timeout triggers Pre-Vote
+  const effects1 = node1.step({ type: EventType.ELECTION_TIMEOUT });
+  assert.equal(node1.role, Role.PRE_CANDIDATE);
+  assert.equal(node1.currentTerm, 0n, 'Term must not increment during pre-vote phase');
+
+  // Should send PRE_VOTE_REQUEST to peers 2 and 3 with candidateTerm = 1n
+  const preVoteSends = effects1.filter(e => e.type === EffectType.SEND && e.message.type === MessageType.PRE_VOTE_REQUEST);
+  assert.equal(preVoteSends.length, 2);
+  assert.equal(preVoteSends[0].message.term, 1n);
+
+  // 2. Peer 2 grants pre-vote
+  const effects2 = node1.step({
+    type: EventType.MESSAGE,
+    message: {
+      type: MessageType.PRE_VOTE_RESPONSE,
+      term: 0n,
+      sourceNode: 2,
+      destNode: 1,
+      voteGranted: true
+    }
+  });
+
+  // Now node1 has 2 votes (itself + node 2) -> Quorum reached!
+  // Node1 must transition to CANDIDATE, increment term to 1n, and broadcast VOTE_REQUEST
+  assert.equal(node1.role, Role.CANDIDATE);
+  assert.equal(node1.currentTerm, 1n);
+  assert.equal(node1.votedFor, 1);
+
+  const voteSends = effects2.filter(e => e.type === EffectType.SEND && e.message.type === MessageType.VOTE_REQUEST);
+  assert.equal(voteSends.length, 2);
+  assert.equal(voteSends[0].message.term, 1n);
+
+  // 3. Peer 2 grants real vote
+  const effects3 = node1.step({
+    type: EventType.MESSAGE,
+    message: {
+      type: MessageType.VOTE_RESPONSE,
+      term: 1n,
+      sourceNode: 2,
+      destNode: 1,
+      voteGranted: true
+    }
+  });
+
+  // Quorum reached -> Node1 becomes LEADER!
+  assert.equal(node1.role, Role.LEADER);
+  assert.equal(node1.leaderId, 1);
+
+  // Must append NOOP entry and broadcast to followers
+  const becomeLeaderEffect = effects3.find(e => e.type === EffectType.BECOME_LEADER);
+  assert.ok(becomeLeaderEffect);
+
+  const appendSends = effects3.filter(e => e.type === EffectType.SEND && e.message.type === MessageType.APPEND_REQUEST);
+  assert.equal(appendSends.length, 2);
+  assert.equal(log1.lastIndex(), 1n);
+});
+
+test('ConsensusEngine - Replication, Quorum Commit and Apply', () => {
+  const leaderLog = new MemoryLog();
+  const leader = new ConsensusEngine({
+    id: 1,
+    peers: [2, 3],
+    storage: leaderLog
+  });
+
+  // Force node1 to leader for term 1
+  leader.currentTerm = 1n;
+  leader.role = Role.LEADER;
+  leader.leaderId = 1;
+  leader._initPeerProgress();
+
+  const followerLog = new MemoryLog();
+  const follower = new ConsensusEngine({
+    id: 2,
+    peers: [1, 3],
+    storage: followerLog
+  });
+  follower.currentTerm = 1n;
+
+  // Submit payload on leader
+  const payload = new Uint8Array([42, 43, 44]);
+  const submitEffects = leader.step({
+    type: EventType.SUBMIT,
+    payload
+  });
+
+  assert.equal(leaderLog.lastIndex(), 1n);
+  assert.equal(leader.commitIndex, 0n, 'Uncommitted before quorum');
+
+  const appendReq = submitEffects.find(e => e.type === EffectType.SEND && e.to === 2).message;
+  assert.equal(appendReq.type, MessageType.APPEND_REQUEST);
+  assert.equal(appendReq.entries.length, 1);
+
+  // Step on follower
+  const followerEffects = follower.step({
+    type: EventType.MESSAGE,
+    message: appendReq
+  });
+
+  assert.equal(followerLog.lastIndex(), 1n);
+  const appendResp = followerEffects.find(e => e.type === EffectType.SEND).message;
+  assert.equal(appendResp.type, MessageType.APPEND_RESPONSE);
+  assert.equal(appendResp.success, true);
+  assert.equal(appendResp.matchIndex, 1n);
+
+  // Pass append response back to leader
+  const leaderAckEffects = leader.step({
+    type: EventType.MESSAGE,
+    message: appendResp
+  });
+
+  // Quorum (Leader + Follower 2 = 2 of 3) achieved!
+  assert.equal(leader.commitIndex, 1n);
+  assert.equal(leader.lastApplied, 1n);
+
+  const commitNotify = leaderAckEffects.find(e => e.type === EffectType.NOTIFY_COMMITTED);
+  assert.ok(commitNotify);
+  assert.equal(commitNotify.index, 1n);
+
+  const applyEffect = leaderAckEffects.find(e => e.type === EffectType.APPLY);
+  assert.ok(applyEffect);
+  assert.deepEqual(applyEffect.entry.payload, payload);
+});
+
+test('ConsensusEngine - Leadership Transfer', () => {
+  const leaderLog = new MemoryLog();
+  leaderLog.append({ term: 1n, index: 1n, payload: new Uint8Array([1]) });
+
+  const leader = new ConsensusEngine({
+    id: 1,
+    peers: [2, 3],
+    storage: leaderLog
+  });
+  leader.currentTerm = 1n;
+  leader.role = Role.LEADER;
+  leader.matchIndex.set(2, 1n);
+
+  // Trigger leadership transfer to peer 2
+  const transferEffects = leader.step({
+    type: EventType.TRANSFER_LEADERSHIP,
+    targetPeer: 2
+  });
+
+  const timeoutNow = transferEffects.find(e => e.type === EffectType.SEND && e.to === 2 && e.message.type === MessageType.TIMEOUT_NOW);
+  assert.ok(timeoutNow, 'Should immediately dispatch TIMEOUT_NOW to fully caught-up peer');
+});

package/test/unit/protocol.test.js

@@ -0,0 +1,181 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { crc32, crc32Buffers } from '../../src/protocol/checksum.js';
+import {
+  encodeMessage,
+  decodeMessage,
+  flattenChunks,
+  readHeader,
+  HEADER_SIZE,
+  WireMetrics
+} from '../../src/protocol/wire.js';
+import { MessageType, EntryType } from '../../src/types.js';
+
+test('CRC32 checksum calculations', () => {
+  const data = new TextEncoder().encode('123456789');
+  const sum = crc32(data);
+  // Standard check value for "123456789" is 0xCBF43926
+  assert.equal(sum, 0xCBF43926);
+
+  // Test multi-buffer scatter/gather CRC
+  const b1 = new TextEncoder().encode('1234');
+  const b2 = new TextEncoder().encode('56789');
+  const multiSum = crc32Buffers([b1, b2]);
+  assert.equal(multiSum, 0xCBF43926);
+});
+
+test('Binary wire protocol - PreVote and Vote request/response', () => {
+  const metrics = new WireMetrics();
+
+  // Pre-Vote Request
+  const preVoteReq = {
+    type: MessageType.PRE_VOTE_REQUEST,
+    term: 5n,
+    sourceNode: 1,
+    destNode: 2,
+    candidateId: 1,
+    lastLogIndex: 100n,
+    lastLogTerm: 4n
+  };
+
+  const chunks = encodeMessage(preVoteReq, metrics);
+  assert.equal(metrics.copiedBytes, 0, 'No payload copies should occur during encoding');
+  const flat = flattenChunks(chunks, metrics);
+  const decoded = decodeMessage(flat);
+
+  assert.equal(decoded.type, MessageType.PRE_VOTE_REQUEST);
+  assert.equal(decoded.term, 5n);
+  assert.equal(decoded.sourceNode, 1);
+  assert.equal(decoded.destNode, 2);
+  assert.equal(decoded.candidateId, 1);
+  assert.equal(decoded.lastLogIndex, 100n);
+  assert.equal(decoded.lastLogTerm, 4n);
+
+  // Vote Response
+  const voteResp = {
+    type: MessageType.VOTE_RESPONSE,
+    term: 5n,
+    sourceNode: 2,
+    destNode: 1,
+    voteGranted: true
+  };
+  const respFlat = flattenChunks(encodeMessage(voteResp));
+  const decodedResp = decodeMessage(respFlat);
+  assert.equal(decodedResp.type, MessageType.VOTE_RESPONSE);
+  assert.equal(decodedResp.term, 5n);
+  assert.equal(decodedResp.voteGranted, true);
+});
+
+test('Binary wire protocol - AppendRequest with multiple entries (zero-copy scatter/gather)', () => {
+  const payload1 = new Uint8Array([10, 20, 30, 40]);
+  const payload2 = new Uint8Array([100, 101, 102, 103, 104, 105]);
+
+  const appendReq = {
+    type: MessageType.APPEND_REQUEST,
+    term: 10n,
+    sourceNode: 1,
+    destNode: 2,
+    leaderId: 1,
+    prevLogIndex: 50n,
+    prevLogTerm: 9n,
+    leaderCommit: 48n,
+    entries: [
+      {
+        term: 10n,
+        index: 51n,
+        type: EntryType.NORMAL,
+        payload: payload1
+      },
+      {
+        term: 10n,
+        index: 52n,
+        type: EntryType.NORMAL,
+        payload: payload2
+      }
+    ]
+  };
+
+  const metrics = new WireMetrics();
+  const chunks = encodeMessage(appendReq, metrics);
+  assert.equal(metrics.copiedBytes, 0, 'Encoding must not copy payload bytes');
+  // Chunks should be: [header, metadata, payload1, payload2]
+  assert.equal(chunks.length, 4);
+  assert.strictEqual(chunks[2], payload1, 'Scatter/gather must retain payload reference without copying');
+  assert.strictEqual(chunks[3], payload2, 'Scatter/gather must retain payload reference without copying');
+
+  const flat = flattenChunks(chunks);
+  const decoded = decodeMessage(flat);
+
+  assert.equal(decoded.type, MessageType.APPEND_REQUEST);
+  assert.equal(decoded.term, 10n);
+  assert.equal(decoded.leaderId, 1);
+  assert.equal(decoded.prevLogIndex, 50n);
+  assert.equal(decoded.prevLogTerm, 9n);
+  assert.equal(decoded.leaderCommit, 48n);
+  assert.equal(decoded.entries.length, 2);
+
+  assert.equal(decoded.entries[0].term, 10n);
+  assert.equal(decoded.entries[0].index, 51n);
+  assert.deepEqual(decoded.entries[0].payload, payload1);
+
+  assert.equal(decoded.entries[1].term, 10n);
+  assert.equal(decoded.entries[1].index, 52n);
+  assert.deepEqual(decoded.entries[1].payload, payload2);
+});
+
+test('Binary wire protocol - Heartbeat, Snapshots, TimeoutNow', () => {
+  // Heartbeat
+  const hb = {
+    type: MessageType.HEARTBEAT,
+    term: 3n,
+    sourceNode: 1,
+    destNode: 2,
+    leaderId: 1,
+    leaderCommit: 25n
+  };
+  const decodedHb = decodeMessage(flattenChunks(encodeMessage(hb)));
+  assert.equal(decodedHb.type, MessageType.HEARTBEAT);
+  assert.equal(decodedHb.leaderCommit, 25n);
+
+  // Snapshot Begin
+  const snapBegin = {
+    type: MessageType.SNAPSHOT_BEGIN,
+    term: 4n,
+    sourceNode: 1,
+    destNode: 2,
+    leaderId: 1,
+    snapshotIndex: 200n,
+    snapshotTerm: 3n,
+    totalBytes: 5000n
+  };
+  const decodedSnap = decodeMessage(flattenChunks(encodeMessage(snapBegin)));
+  assert.equal(decodedSnap.snapshotIndex, 200n);
+  assert.equal(decodedSnap.totalBytes, 5000n);
+
+  // Snapshot Chunk
+  const chunkData = new Uint8Array([1, 2, 3, 4, 5]);
+  const snapChunk = {
+    type: MessageType.SNAPSHOT_CHUNK,
+    term: 4n,
+    sourceNode: 1,
+    destNode: 2,
+    snapshotIndex: 200n,
+    offset: 0n,
+    chunkData
+  };
+  const decodedChunk = decodeMessage(flattenChunks(encodeMessage(snapChunk)));
+  assert.equal(decodedChunk.snapshotIndex, 200n);
+  assert.deepEqual(decodedChunk.chunkData, chunkData);
+
+  // Timeout Now
+  const timeoutNow = {
+    type: MessageType.TIMEOUT_NOW,
+    term: 4n,
+    sourceNode: 1,
+    destNode: 2,
+    leaderId: 1
+  };
+  const decodedTimeout = decodeMessage(flattenChunks(encodeMessage(timeoutNow)));
+  assert.equal(decodedTimeout.type, MessageType.TIMEOUT_NOW);
+  assert.equal(decodedTimeout.leaderId, 1);
+});

package/test/unit/storage.test.js

@@ -0,0 +1,127 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { MemoryLog } from '../../src/storage/memory-log.js';
+
+test('MemoryLog - basic appends, lookups, and terms', () => {
+  const log = new MemoryLog();
+  assert.equal(log.lastIndex(), 0n);
+  assert.equal(log.lastTerm(), 0n);
+  assert.equal(log.firstIndex(), 1n);
+
+  log.append({ term: 1n, index: 1n, payload: new Uint8Array([1]) });
+  log.append({ term: 1n, index: 2n, payload: new Uint8Array([2]) });
+  log.append({ term: 2n, index: 3n, payload: new Uint8Array([3]) });
+
+  assert.equal(log.lastIndex(), 3n);
+  assert.equal(log.lastTerm(), 2n);
+  assert.equal(log.term(1n), 1n);
+  assert.equal(log.term(2n), 1n);
+  assert.equal(log.term(3n), 2n);
+  assert.equal(log.term(4n), null);
+
+  const range = log.entries(1n, 2n);
+  assert.equal(range.length, 2);
+  assert.equal(range[0].index, 1n);
+  assert.equal(range[1].index, 2n);
+});
+
+test('MemoryLog - truncation', () => {
+  const log = new MemoryLog();
+  log.appendMany([
+    { term: 1n, index: 1n, payload: new Uint8Array([1]) },
+    { term: 1n, index: 2n, payload: new Uint8Array([2]) },
+    { term: 2n, index: 3n, payload: new Uint8Array([3]) },
+    { term: 2n, index: 4n, payload: new Uint8Array([4]) }
+  ]);
+
+  log.truncateFrom(3n);
+  assert.equal(log.lastIndex(), 2n);
+  assert.equal(log.lastTerm(), 1n);
+  assert.equal(log.term(3n), null);
+  assert.equal(log.entries(1n, 4n).length, 2);
+});
+
+test('MemoryLog - compaction and snapshot', () => {
+  const log = new MemoryLog();
+  for (let i = 1n; i <= 10n; i++) {
+    log.append({ term: 1n, index: i, payload: new Uint8Array([Number(i)]) });
+  }
+
+  assert.equal(log.lastIndex(), 10n);
+
+  // Save snapshot at index 5
+  log.saveSnapshot({
+    index: 5n,
+    term: 1n,
+    data: new Uint8Array([55])
+  });
+
+  assert.equal(log.firstIndex(), 6n);
+  assert.equal(log.lastIndex(), 10n);
+  assert.equal(log.term(5n), 1n, 'Term of snapshot index should be available');
+  assert.equal(log.term(4n), null, 'Compacted terms should return null');
+
+  const remaining = log.entries(1n, 10n);
+  assert.equal(remaining.length, 5);
+  assert.equal(remaining[0].index, 6n);
+  assert.equal(remaining[4].index, 10n);
+
+  const snap = log.getSnapshot();
+  assert.equal(snap.index, 5n);
+  assert.deepEqual(snap.data, new Uint8Array([55]));
+});
+
+test('MemoryLog - hard state persistence', () => {
+  const log = new MemoryLog();
+  assert.equal(log.getHardState().currentTerm, 0n);
+  assert.equal(log.getHardState().votedFor, null);
+
+  log.setHardState({ currentTerm: 7n, votedFor: 3 });
+  assert.equal(log.getHardState().currentTerm, 7n);
+  assert.equal(log.getHardState().votedFor, 3);
+});
+
+import { FileLog } from '../../src/storage/file-log.js';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+test('FileLog - crash recovery, persistence across reopen, and corruption truncation', () => {
+  const tmpDir = path.join(os.tmpdir(), `raptiye-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  
+  // 1. Initial write
+  let fileLog = new FileLog(tmpDir);
+  fileLog.setHardState({ currentTerm: 4n, votedFor: 2 });
+  fileLog.append({ term: 4n, index: 1n, payload: new Uint8Array([1, 2, 3]) });
+  fileLog.append({ term: 4n, index: 2n, payload: new Uint8Array([4, 5, 6]) });
+  fileLog.close();
+
+  // 2. Reopen and verify state preserved
+  fileLog = new FileLog(tmpDir);
+  assert.equal(fileLog.getHardState().currentTerm, 4n);
+  assert.equal(fileLog.getHardState().votedFor, 2);
+  assert.equal(fileLog.lastIndex(), 2n);
+  assert.equal(fileLog.term(1n), 4n);
+  assert.equal(fileLog.term(2n), 4n);
+  assert.deepEqual(fileLog.entries(1n, 1n)[0].payload, new Uint8Array([1, 2, 3]));
+  assert.deepEqual(fileLog.entries(2n, 2n)[0].payload, new Uint8Array([4, 5, 6]));
+
+  // 3. Simulate corrupt partial write at tail of wal.log
+  fileLog.close();
+  const walPath = path.join(tmpDir, 'wal.log');
+  // Append 5 garbage bytes
+  fs.appendFileSync(walPath, Buffer.from([0xDE, 0xAD, 0xBE, 0xEF, 0x00]));
+
+  // 4. Reopen -> should recover valid entries and truncate garbage
+  fileLog = new FileLog(tmpDir);
+  assert.equal(fileLog.lastIndex(), 2n);
+  assert.equal(fileLog.term(2n), 4n);
+
+  // Can append new entry normally after recovery
+  fileLog.append({ term: 4n, index: 3n, payload: new Uint8Array([7, 8, 9]) });
+  assert.equal(fileLog.lastIndex(), 3n);
+  fileLog.close();
+
+  // Clean up
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});

package/test/unit/transport.test.js

@@ -0,0 +1,90 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { MemoryNetwork, MemoryTransport } from '../../src/transport/memory-transport.js';
+import { TCPTransport } from '../../src/transport/tcp-transport.js';
+import { encodeMessage } from '../../src/protocol/wire.js';
+import { MessageType } from '../../src/types.js';
+
+test('MemoryTransport - send and receive messages', async () => {
+  const net = new MemoryNetwork();
+  const t1 = new MemoryTransport(1, net);
+  const t2 = new MemoryTransport(2, net);
+
+  await t1.start();
+  await t2.start();
+
+  let received = null;
+  t2.onMessage((from, msg) => {
+    received = { from, msg };
+  });
+
+  const msg = {
+    type: MessageType.PRE_VOTE_REQUEST,
+    term: 1n,
+    sourceNode: 1,
+    destNode: 2,
+    candidateId: 1,
+    lastLogIndex: 10n,
+    lastLogTerm: 1n
+  };
+
+  const chunks = encodeMessage(msg);
+  t1.sendv(2, chunks);
+
+  assert.ok(received);
+  assert.equal(received.from, 1);
+  assert.equal(received.msg.type, MessageType.PRE_VOTE_REQUEST);
+  assert.equal(received.msg.term, 1n);
+
+  await t1.close();
+  await t2.close();
+});
+
+test('TCPTransport - peer communication and framing over loopback', async () => {
+  const port1 = 19101;
+  const port2 = 19102;
+
+  const peerAddrs1 = new Map([[2, { host: '127.0.0.1', port: port2 }]]);
+  const peerAddrs2 = new Map([[1, { host: '127.0.0.1', port: port1 }]]);
+
+  const tcp1 = new TCPTransport({ id: 1, port: port1, peerAddresses: peerAddrs1 });
+  const tcp2 = new TCPTransport({ id: 2, port: port2, peerAddresses: peerAddrs2 });
+
+  try {
+    await tcp1.start();
+    await tcp2.start();
+
+    const receivedPromise = new Promise((resolve) => {
+      tcp2.onMessage((from, msg) => {
+        resolve({ from, msg });
+      });
+    });
+
+    const msg = {
+      type: MessageType.APPEND_REQUEST,
+      term: 5n,
+      sourceNode: 1,
+      destNode: 2,
+      leaderId: 1,
+      prevLogIndex: 2n,
+      prevLogTerm: 1n,
+      leaderCommit: 2n,
+      entries: [
+        { term: 5n, index: 3n, payload: new Uint8Array([10, 20, 30]) }
+      ]
+    };
+
+    const chunks = encodeMessage(msg);
+    tcp1.sendv(2, chunks);
+
+    const received = await receivedPromise;
+    assert.equal(received.from, 1);
+    assert.equal(received.msg.type, MessageType.APPEND_REQUEST);
+    assert.equal(received.msg.term, 5n);
+    assert.equal(received.msg.entries.length, 1);
+    assert.deepEqual(received.msg.entries[0].payload, new Uint8Array([10, 20, 30]));
+  } finally {
+    await tcp1.close();
+    await tcp2.close();
+  }
+});