proffesor-for-testing__agentic-qe/v2/docs/websocket-server-quick-start.md

WebSocket Server Quick Start Guide

Quick Test

Run the standalone test to verify the WebSocket server works:

cd /workspaces/agentic-qe-cf
node scripts/test-websocket-standalone.js

Expected output:

🧪 Testing WebSocket Server Implementation
✅ HTTP/WebSocket server started on port 8080
✅ Port 8080 is bound and listening
✅ Client connected successfully
✅ All tests passed!

Verify Port Binding

netstat -an | grep 8080

Should show:

tcp6       0      0 :::8080                 :::*                    LISTEN

Connect with a Client

Using wscat (install with: npm install -g wscat)

wscat -c ws://localhost:8080

Using Node.js

const { WebSocket } = require('ws');
const client = new WebSocket('ws://localhost:8080');

client.on('open', () => {
  console.log('Connected');
  client.send(JSON.stringify({ type: 'ping' }));
});

client.on('message', (data) => {
  console.log('Received:', data.toString());
});

Integration Example

import { WebSocketServer } from './src/visualization/api/WebSocketServer';
import { EventStore } from './src/persistence/event-store';
import { ReasoningStore } from './src/persistence/reasoning-store';

async function startWebSocketServer() {
  // Create stores
  const eventStore = new EventStore();
  const reasoningStore = new ReasoningStore();

  // Create server
  const wsServer = new WebSocketServer(eventStore, reasoningStore, {
    port: 8080,
    heartbeatInterval: 30000,
    clientTimeout: 60000,
    maxBacklogSize: 1000,
    compression: true
  });

  // Setup event listeners
  wsServer.on('started', ({ port }) => {
    console.log(`WebSocket server listening on port ${port}`);
  });

  wsServer.on('client_connected', ({ clientId, subscriptions }) => {
    console.log(`Client ${clientId} connected with subscriptions:`, subscriptions);
  });

  wsServer.on('client_disconnected', ({ clientId, reason }) => {
    console.log(`Client ${clientId} disconnected: ${reason}`);
  });

  wsServer.on('error', ({ error, source }) => {
    console.error(`Error from ${source}:`, error);
  });

  // Start the server
  await wsServer.start();

  // Broadcast events to all connected clients
  wsServer.broadcastEvent({
    type: 'event',
    timestamp: new Date().toISOString(),
    data: {
      agent_id: 'test-generator',
      event_type: 'test_generated',
      test_count: 42
    }
  });

  // Get server statistics
  const stats = wsServer.getStatistics();
  console.log('Server stats:', stats);

  // Graceful shutdown
  process.on('SIGINT', async () => {
    console.log('Shutting down...');
    await wsServer.stop();
    process.exit(0);
  });
}

startWebSocketServer().catch(console.error);

Client Subscription Example

Connect with query parameters to filter events:

wscat -c "ws://localhost:8080?session_id=session-123&agent_id=test-gen&event_types=test_generated,test_passed"

Available subscription options:

• session_id - Filter by session ID
• agent_id - Filter by agent ID
• event_types - Comma-separated list of event types
• since - ISO timestamp to get events after

Message Types

Heartbeat

{
  "type": "heartbeat",
  "timestamp": "2025-11-21T13:00:00.000Z",
  "data": {
    "connected_clients": 5,
    "uptime_ms": 120000
  }
}

Event

{
  "type": "event",
  "timestamp": "2025-11-21T13:00:00.000Z",
  "data": {
    "agent_id": "test-gen",
    "event_type": "test_generated",
    "payload": { "test_count": 42 }
  }
}

Reasoning

{
  "type": "reasoning",
  "timestamp": "2025-11-21T13:00:00.000Z",
  "data": {
    "chain_id": "chain-123",
    "steps": [...],
    "verdict": "approved"
  }
}

Troubleshooting

Port already in use

# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

Connection refused

• Check if server is running
• Verify port number matches
• Check firewall settings

No messages received

• Verify subscription filters
• Check client connection status
• Review server logs for errors

Performance Tuning

High throughput scenarios

const wsServer = new WebSocketServer(eventStore, reasoningStore, {
  port: 8080,
  maxBacklogSize: 5000,        // Increase queue size
  compression: true,            // Enable compression
  heartbeatInterval: 60000,     // Reduce heartbeat frequency
});

Low latency scenarios

const wsServer = new WebSocketServer(eventStore, reasoningStore, {
  port: 8080,
  maxBacklogSize: 100,          // Smaller queue
  compression: false,           // Disable compression
  heartbeatInterval: 10000,     // More frequent heartbeats
});

Further Reading

• Full implementation details: docs/websocket-server-implementation.md
• WebSocket API docs: src/visualization/api/WebSocketServer.ts
• Test examples: scripts/test-websocket-standalone.js