proffesor-for-testing__agentic-qe/docs/QUIC-INTEGRATION-GUIDE.md

QUIC Transport Integration Guide

Overview

The QUIC Transport Integration provides distributed memory synchronization for SwarmMemoryManager across multiple nodes. This feature enables:

• Real-time synchronization of memory entries across distributed swarm instances
• Peer-to-peer coordination with automatic peer discovery
• High-performance transport using QUIC protocol (mock implementation, ready for production libraries)
• Graceful degradation when QUIC is unavailable
• Zero breaking changes - completely opt-in feature

Architecture

Components

1. QUICTransportWrapper: Core QUIC transport layer

   • Manages peer connections
   • Handles sync loop with configurable intervals
   • Tracks performance metrics
   • Provides graceful error handling

2. AgentDBIntegration: High-level integration manager

   • Wraps QUICTransportWrapper for easy usage
   • Provides lifecycle management
   • Handles event logging and monitoring

3. SwarmMemoryManager: Extended with QUIC capabilities

   • Optional QUIC integration (disabled by default)
   • Tracks entry modifications for sync
   • Provides QUIC-specific query methods

Data Flow

SwarmMemoryManager (Node A)
         ↓ store/update
    Track modifications
         ↓ sync interval
   QUICTransportWrapper
         ↓ QUIC protocol
   QUICTransportWrapper (Node B)
         ↓ apply changes
SwarmMemoryManager (Node B)

Configuration

Default Configuration

Located at .agentic-qe/config/transport.json:

{
  "quic": {
    "enabled": false,          // Opt-in: must explicitly enable
    "host": "localhost",
    "port": 9000,
    "syncInterval": 5000,      // Sync every 5 seconds
    "maxPeers": 10,
    "retryAttempts": 3,
    "retryDelay": 1000,
    "timeout": 5000
  },
  "peers": [
    {
      "name": "peer-1",
      "address": "192.168.1.100",
      "port": 9000,
      "enabled": false
    }
  ]
}

Configuration Options

Option	Type	Default	Description
enabled	boolean	false	Enable/disable QUIC transport
host	string	localhost	Host to bind QUIC server
port	number	9000	Port for QUIC server
syncInterval	number	5000	Sync interval in milliseconds
maxPeers	number	10	Maximum concurrent peers
retryAttempts	number	3	Connection retry attempts
retryDelay	number	1000	Delay between retries (ms)
timeout	number	5000	Connection timeout (ms)

Usage

Basic Usage

import { SwarmMemoryManager } from './src/core/memory/SwarmMemoryManager';

// Create memory manager (QUIC disabled by default)
const memoryManager = new SwarmMemoryManager('.agentic-qe/swarm.db');
await memoryManager.initialize();

// Normal operations work without QUIC
await memoryManager.store('key', { data: 'value' });
const value = await memoryManager.retrieve('key');

// Enable QUIC when needed (opt-in)
await memoryManager.enableQUIC({
  host: '0.0.0.0',
  port: 9000,
  syncInterval: 5000
});

// Add peers for synchronization
const peerId = await memoryManager.addQUICPeer('192.168.1.100', 9001);

// Check status
console.log('QUIC enabled:', memoryManager.isQUICEnabled());
console.log('Connected peers:', memoryManager.getQUICPeers());
console.log('Metrics:', memoryManager.getQUICMetrics());

// Disable when done
await memoryManager.disableQUIC();

Advanced Usage

// Enable with custom configuration
await memoryManager.enableQUIC({
  host: '0.0.0.0',
  port: 9999,
  syncInterval: 3000,      // Sync every 3 seconds
  maxPeers: 20,
  retryAttempts: 5
});

// Add multiple peers
const peers = [
  { address: '192.168.1.100', port: 9000 },
  { address: '192.168.1.101', port: 9000 },
  { address: '192.168.1.102', port: 9000 }
];

for (const peer of peers) {
  await memoryManager.addQUICPeer(peer.address, peer.port);
}

// Monitor metrics
setInterval(() => {
  const metrics = memoryManager.getQUICMetrics();
  console.log('Sync stats:', {
    totalSyncs: metrics?.totalSyncs,
    successRate: (metrics?.successfulSyncs / metrics?.totalSyncs * 100).toFixed(2) + '%',
    avgDuration: metrics?.averageSyncDuration.toFixed(2) + 'ms',
    activePeers: metrics?.activePeers
  });
}, 60000); // Every minute

// Query modified entries for manual sync
const since = Date.now() - 60000; // Last minute
const modifiedEntries = await memoryManager.getModifiedEntries(since);
console.log(`${modifiedEntries.length} entries modified in last minute`);

// Get last modification timestamp for specific entry
const lastModified = memoryManager.getLastModified('important-key');
if (lastModified) {
  console.log('Last modified:', new Date(lastModified).toISOString());
}

// Access low-level integration for advanced features
const integration = memoryManager.getQUICIntegration();
if (integration) {
  const transport = integration.getTransport();

  // Listen to transport events
  transport.on('sync-completed', (data) => {
    console.log('Sync completed:', data);
  });

  transport.on('peer-synced', (data) => {
    console.log('Peer synced:', data.peerId, data.entriesCount);
  });
}

Multi-Node Setup

Node 1 (Primary):

const memory1 = new SwarmMemoryManager('.agentic-qe/node1.db');
await memory1.initialize();

await memory1.enableQUIC({
  host: '0.0.0.0',
  port: 9000
});

// Store data
await memory1.store('shared-key', { data: 'from-node-1' });

Node 2 (Secondary):

const memory2 = new SwarmMemoryManager('.agentic-qe/node2.db');
await memory2.initialize();

await memory2.enableQUIC({
  host: '0.0.0.0',
  port: 9001
});

// Connect to Node 1
await memory2.addQUICPeer('192.168.1.100', 9000);

// After sync, data from Node 1 should be available
setTimeout(async () => {
  const value = await memory2.retrieve('shared-key');
  console.log('Received from Node 1:', value);
}, 6000); // Wait for sync interval

Performance Metrics

Available Metrics

interface QUICMetrics {
  totalSyncs: number;           // Total sync operations
  successfulSyncs: number;      // Successful syncs
  failedSyncs: number;          // Failed syncs
  averageSyncDuration: number;  // Avg duration in ms
  totalBytesTransferred: number;// Total bytes synced
  activePeers: number;          // Currently connected peers
  lastSyncTimestamp: number;    // Last sync timestamp
  errorRate: number;            // Error rate (0-1)
}

Monitoring Example

function monitorQUICPerformance(memoryManager: SwarmMemoryManager) {
  const metrics = memoryManager.getQUICMetrics();

  if (!metrics) {
    console.log('QUIC not enabled');
    return;
  }

  console.log('=== QUIC Performance ===');
  console.log('Total syncs:', metrics.totalSyncs);
  console.log('Success rate:',
    ((metrics.successfulSyncs / metrics.totalSyncs) * 100).toFixed(2) + '%');
  console.log('Avg sync duration:',
    metrics.averageSyncDuration.toFixed(2) + 'ms');
  console.log('Active peers:', metrics.activePeers);
  console.log('Error rate:',
    (metrics.errorRate * 100).toFixed(2) + '%');
  console.log('Total data transferred:',
    (metrics.totalBytesTransferred / 1024).toFixed(2) + 'KB');
  console.log('Last sync:',
    new Date(metrics.lastSyncTimestamp).toISOString());
}

Backward Compatibility

Zero Breaking Changes

The QUIC integration is completely backward compatible:

// Existing code continues to work without changes
const memory = new SwarmMemoryManager(':memory:');
await memory.initialize();

// All existing methods work exactly the same
await memory.store('key', { data: 'value' });
const value = await memory.retrieve('key');
await memory.postHint({ key: 'hint', value: 'data' });

// QUIC is disabled by default
console.log(memory.isQUICEnabled()); // false
console.log(memory.getQUICMetrics()); // null
console.log(memory.getQUICPeers()); // []

Migration Path

1. No changes required - existing code works as-is
2. Opt-in when ready - call enableQUIC() to activate
3. Gradual rollout - enable on specific nodes first
4. Easy rollback - call disableQUIC() to revert

Error Handling

Graceful Degradation

QUIC integration fails gracefully:

try {
  await memoryManager.enableQUIC();
} catch (error) {
  // QUIC failed to start, but memory manager still works
  console.warn('QUIC unavailable, continuing without sync:', error);
}

// Normal operations continue to work
await memoryManager.store('key', { data: 'value' });

Common Issues

Issue: Peer connection fails

try {
  await memoryManager.addQUICPeer('invalid-host', 9000);
} catch (error) {
  console.error('Failed to connect to peer:', error.message);
  // Continue with other peers
}

Issue: Sync timeout

// Configure longer timeout for slow networks
await memoryManager.enableQUIC({
  timeout: 10000,        // 10 seconds
  retryAttempts: 5,
  retryDelay: 2000
});

Issue: Memory pressure

// Reduce sync frequency for low-resource environments
await memoryManager.enableQUIC({
  syncInterval: 30000,   // Sync every 30 seconds
  maxPeers: 3           // Limit concurrent connections
});

Testing

Unit Tests

# Run QUIC integration tests
npm run test:unit -- tests/unit/core/memory/AgentDBIntegration.test.ts

# Run SwarmMemoryManager QUIC tests
npm run test:unit -- tests/unit/core/memory/SwarmMemoryManager.quic.test.ts

# Run backward compatibility verification
npm run test:unit -- tests/verification/quic-backward-compatibility.test.ts

Integration Testing

describe('QUIC Multi-Node Sync', () => {
  it('should sync data between two nodes', async () => {
    const node1 = new SwarmMemoryManager(':memory:');
    const node2 = new SwarmMemoryManager(':memory:');

    await node1.initialize();
    await node2.initialize();

    await node1.enableQUIC({ port: 9000 });
    await node2.enableQUIC({ port: 9001 });

    // Connect nodes
    await node2.addQUICPeer('localhost', 9000);

    // Store on node1
    await node1.store('shared-key', { data: 'test' });

    // Wait for sync
    await new Promise(resolve => setTimeout(resolve, 6000));

    // Verify on node2
    const entries = await node2.getModifiedEntries(Date.now() - 10000);
    expect(entries.find(e => e.key === 'shared-key')).toBeDefined();
  });
});

Security Considerations

Current Implementation

The current implementation is a mock/stub for development and testing:

• ✅ Provides complete interface
• ✅ Simulates network operations
• ⚠️ No actual encryption
• ⚠️ No authentication
• ⚠️ No TLS/SSL

Production Recommendations

For production deployment, integrate with real QUIC libraries:

1. Use production QUIC library:

   npm install @quic/quic-js
   # or
   npm install node-quic
   

2. Enable TLS:

   {
     "security": {
       "tls": {
         "enabled": true,
         "certPath": "/path/to/cert.pem",
         "keyPath": "/path/to/key.pem"
       }
     }
   }
   

3. Add authentication:

   {
     "security": {
       "authentication": {
         "enabled": true,
         "method": "psk",
         "secretKey": "your-secret-key"
       }
     }
   }
   

4. Network isolation:

   • Use VPC/private networks
   • Configure firewall rules
   • Implement rate limiting

Troubleshooting

Debug Mode

// Enable verbose logging
const integration = memoryManager.getQUICIntegration();
if (integration) {
  const transport = integration.getTransport();

  transport.on('info', (msg) => console.log('[INFO]', msg));
  transport.on('error', (err) => console.error('[ERROR]', err));
  transport.on('peer-added', (data) => console.log('[PEER+]', data));
  transport.on('peer-removed', (data) => console.log('[PEER-]', data));
  transport.on('sync-completed', (data) => console.log('[SYNC]', data));
}

Common Questions

Q: Is QUIC required? A: No, QUIC is completely optional. SwarmMemoryManager works perfectly without it.

Q: What's the performance impact? A: Minimal (<5%) when enabled, zero when disabled (default).

Q: Can I use with existing databases? A: Yes, QUIC is a transport layer and works with any database backend.

Q: How do I upgrade to real QUIC? A: Replace QUICTransportWrapper implementation with actual QUIC library calls. The interface remains the same.

Roadmap

• Integration with production QUIC libraries
• TLS/SSL encryption
• Authentication mechanisms
• Compression support
• Conflict resolution strategies
• Advanced peer discovery (mDNS, DNS-SD)
• WebTransport support for browsers

References

• QUIC Protocol RFC 9000
• WebTransport
• AgentDB Documentation
• SwarmMemoryManager API

Support

For issues or questions:

• GitHub Issues: agentic-qe/issues
• Documentation: docs/