[Phase 5] Implement TCP server mode (JavaScript)

[konard]

Summary

Implement standalone TCP server mode for JavaScript, enabling Links Queue to run as a separate service that clients connect to.

Background

Server mode allows Links Queue to be deployed as a standalone service, separate from the application. Communication uses Links Notation protocol over TCP.

Requirements

Server Features

• TCP listener with configurable bind address/port
• Connection handling with concurrent clients
• Request routing to queue operations
• Connection pooling
• Graceful shutdown with drain period
• Health check endpoint

Protocol

• Links Notation message framing over TCP
• Request/response pattern
• Bidirectional streaming for subscriptions
• Heartbeat/ping-pong for connection health

Implementation

import { LinksQueueServer } from 'links-queue/server';

const server = new LinksQueueServer({
  host: '0.0.0.0',
  port: 5000,
  backend: { type: 'link-cli', path: './data/db.links' },
  maxConnections: 1000,
  idleTimeout: 60000
});

server.on('connection', (client) => {
  console.log('Client connected:', client.id);
});

server.on('error', (error) => {
  console.error('Server error:', error);
});

await server.start();
console.log('Server listening on port 5000');

// Graceful shutdown
process.on('SIGTERM', async () => {
  await server.shutdown({ drainTimeout: 30000 });
});

Client Library

import { LinksQueueClient } from 'links-queue/client';

const client = new LinksQueueClient('tcp://localhost:5000');
await client.connect();

// Queue operations over network
await client.enqueue('tasks', { source: 'job', target: 'run' });
const link = await client.dequeue('tasks');

// Subscribe to queue
const subscription = client.subscribe('tasks', async (link) => {
  console.log('Received:', link);
  await client.acknowledge('tasks', link.id);
});

await client.disconnect();

Deliverables

1. src/server/server.ts - TCP server implementation
2. src/server/connection.ts - Connection handling
3. src/server/router.ts - Request routing
4. src/client/client.ts - Client library
5. src/client/connection.ts - Client connection handling
6. Unit tests with mock connections
7. Integration tests with real server/client
8. CLI: links-queue server --config config.json

Dependencies

• [Phase 1] Define Link and LinkStore interfaces/traits (API Contract) #7 - Link interfaces
• [Phase 2] Define Queue and QueueManager interfaces/traits (API Contract) #10 - Queue interfaces
• [Phase 2] Implement basic Queue and QueueManager (JavaScript) #11 - Queue implementation
• [Phase 4] Integrate links-notation for parsing and serialization #16 - Links Notation protocol

Can Be Worked In Parallel With

• Rust server mode (separate codebase)

References

• ARCHITECTURE.md - Deployment Patterns
• REQUIREMENTS.md - REQ-PROTO-020 through REQ-PROTO-022
• ROADMAP.md - Phase 5: Server Mode