[Phase 5] Implement TCP server mode (Rust)

[konard]

Summary

Implement standalone TCP server mode for Rust, 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 using tokio
• 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

use links_queue::server::{LinksQueueServer, ServerConfig};

let server = LinksQueueServer::new(ServerConfig {
    host: "0.0.0.0".to_string(),
    port: 5000,
    backend: BackendConfig::LinkCli {
        path: PathBuf::from("./data/db.links"),
    },
    max_connections: 1000,
    idle_timeout: Duration::from_secs(60),
});

server.on_connection(|client| {
    println!("Client connected: {}", client.id());
});

server.start().await?;
println!("Server listening on port 5000");

// Graceful shutdown
tokio::select! {
    _ = shutdown_signal() => {
        server.shutdown(Duration::from_secs(30)).await?;
    }
}

Client Library

use links_queue::client::LinksQueueClient;

let client = LinksQueueClient::connect("tcp://localhost:5000").await?;

// Queue operations over network
client.enqueue("tasks", Link::new("job", "run")).await?;
let link = client.dequeue("tasks").await?;

// Subscribe to queue
let mut subscription = client.subscribe("tasks").await?;
while let Some(link) = subscription.next().await {
    println!("Received: {:?}", link);
    client.acknowledge("tasks", link.id).await?;
}

client.disconnect().await?;

Deliverables

1. src/server/mod.rs - TCP server implementation
2. src/server/connection.rs - Connection handling
3. src/server/router.rs - Request routing
4. src/client/mod.rs - Client library
5. src/client/connection.rs - 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 traits
• [Phase 2] Define Queue and QueueManager interfaces/traits (API Contract) #10 - Queue traits
• [Phase 2] Implement basic Queue and QueueManager (Rust) #12 - Queue implementation
• [Phase 4] Integrate links-notation for parsing and serialization #16 - Links Notation protocol

Can Be Worked In Parallel With

• JavaScript server mode (separate codebase)

References

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