@hardlydifficult/worker-server 1.0.6 → 1.0.8

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/worker-server
 
-WebSocket-based worker server with health monitoring, request routing, and load balancing.
+A WebSocket-based worker server for managing remote worker connections with health monitoring, request routing, and load balancing.
 
 ## Installation
 
@@ -13,204 +13,218 @@ npm install @hardlydifficult/worker-server
 ```typescript
 import { WorkerServer } from "@hardlydifficult/worker-server";
 
-const server = new WorkerServer({
-  port: 8080,
-  authToken: "my-secret-token", // optional
-  logger: console, // optional, defaults to no-op
-});
+const server = new WorkerServer({ port: 3000 });
 
-// Handle worker registrations and messages
 server.onWorkerConnected((worker) => {
-  console.log(`Worker ${worker.name} (${worker.id}) connected`);
-});
-
-server.onWorkerDisconnected((worker, pendingRequestIds) => {
-  console.log(`Worker ${worker.id} disconnected with ${pendingRequestIds.size} pending requests`);
+  console.log("Worker connected:", worker.id);
 });
 
-server.onWorkerMessage("work_complete", (worker, message) => {
-  console.log(`Work completed: ${message.requestId}`);
+server.onWorkerMessage("work_request", async (worker, message) => {
+  console.log("Received request from", worker.id, message);
+  server.send(worker.id, { type: "work_complete", requestId: message.requestId });
 });
 
-// Start the server
 await server.start();
-
-// Get an available worker supporting a model
-const worker = server.getAvailableWorker("gpt-4");
-if (worker) {
-  server.send(worker.id, { type: "work_request", requestId: "req-1" });
-}
-
-// Stop when done
-await server.stop();
+console.log("Worker server running on port 3000");
 ```
 
 ## Core Concepts
 
-### Worker Lifecycle Management
+### Worker Registration
 
-The server handles worker connections, registrations, and disconnections with automatic health monitoring.
-
-#### Registration and Authentication
-
-Workers connect via WebSocket and send a `worker_registration` message with an optional `authToken`. If the server is configured with `authToken`, the worker must provide a matching token.
+Workers connect via WebSocket and register with identity and capabilities. The server supports optional authentication and tracks worker health via heartbeat protocol.
 
 ```typescript
-import { WorkerServer } from "@hardlydifficult/worker-server";
-
-const server = new WorkerServer({
-  port: 8080,
-  authToken: "secret",
+server.onWorkerConnected((worker) => {
+  // Worker capabilities include supported models and concurrency limits
+  console.log(
+    `Worker ${worker.name} supports: ${worker.capabilities.models.map(m => m.modelId).join(", ")}`
+  );
 });
+```
 
-server.onWorkerConnected((worker) => {
-  console.log(`Worker registered: ${worker.id}`);
+### Message Routing
+
+Messages are dispatched by `type` field to registered handlers.
+
+```typescript
+server.onWorkerMessage("work_complete", (worker, message) => {
+  console.log("Work completed for", message.requestId);
 });
 
-await server.start();
+server.send(workerId, { type: "work_request", requestId: "req-1" });
+server.broadcast({ type: "shutdown" });
 ```
 
-#### Heartbeat and Health Monitoring
+### Request Tracking & Load Balancing
 
-Workers must send periodic `heartbeat` messages. The server tracks the last heartbeat timestamp and closes connections that miss the timeout.
+Track active requests and select the least-loaded available worker.
 
 ```typescript
-const server = new WorkerServer({
-  port: 8080,
-  heartbeatTimeoutMs: 60_000,      // Missed for 60s → unhealthy
-  healthCheckIntervalMs: 10_000,   // Check every 10s
-  heartbeatIntervalMs: 15_000,     // Communicate 15s interval to workers
-});
+const worker = server.getAvailableWorker("sonnet", "inference");
+if (worker) {
+  server.trackRequest(worker.id, requestId, "inference");
+  server.send(worker.id, { type: "start", requestId });
+}
+
+// Later, release the request
+server.releaseRequest(requestId, { incrementCompleted: true });
 ```
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `heartbeatTimeoutMs` | 60000 | Time before worker is marked unhealthy |
-| `healthCheckIntervalMs` | 10000 | Frequency of health checks |
-| `heartbeatIntervalMs` | 15000 | Heartbeat interval communicated to workers |
+## Core Components
+
+### WorkerServer
+
+Main server class managing WebSocket connections, HTTP endpoints, and worker pool.
 
-#### Disconnection Handling
+#### Constructor
 
-When a worker disconnects, the `onWorkerDisconnected` handler is called with its pending request IDs.
+| Parameter | Type | Default | Description |
+|--|------|---------|-----|
+| `port` | `number` | — | HTTP + WebSocket server port |
+| `authToken` | `string` (optional) | — | Token required for worker registration |
+| `heartbeatTimeoutMs` | `number` | 60000 | Timeout before marking worker unhealthy |
+| `healthCheckIntervalMs` | `number` | 10000 | Interval for health checks |
+| `heartbeatIntervalMs` | `number` | 15000 | Heartbeat interval communicated to workers |
+| `logger` | `WorkerServerLogger` (optional) | No-op | Logger instance |
+
+#### Lifecycle Management
 
 ```typescript
-server.onWorkerDisconnected((worker, pendingRequestIds) => {
-  // Reassign pending requests as needed
-  console.log(`Pending: ${[...pendingRequestIds].join(", ")}`);
-});
+const server = new WorkerServer({ port: 8080, authToken: "secret" });
+
+// Start the server
+await server.start();
+
+// Stop the server gracefully
+await server.stop();
 ```
 
-### Request Tracking and Load Balancing
+#### Registration Handlers
 
-Requests are tracked per-worker to avoid overloading and to support category-specific limits.
+```typescript
+// Called when a worker successfully registers
+const unsubscribeConnected = server.onWorkerConnected((worker) => {
+  console.log(`Worker connected: ${worker.name}`);
+});
 
-#### Request Lifecycle
+// Called when a worker disconnects
+const unsubscribeDisconnected = server.onWorkerDisconnected((worker, pending) => {
+  console.log(`Worker disconnected with ${pending.size} pending requests`);
+});
+```
 
-Track a request as assigned to a worker, then release it when complete.
+#### Message Handling
 
 ```typescript
-// Assign request to worker
-const worker = server.getAvailableWorker("gpt-4");
-if (worker) {
-  server.trackRequest(worker.id, "req-1");
-  server.send(worker.id, { type: "work_request", requestId: "req-1" });
-}
+// Register handlers for domain-specific messages by type
+server.onWorkerMessage("work_request", (worker, message) => {
+  // Process work request from worker
+});
 
-// Worker sends completion message
-server.onWorkerMessage("work_complete", (worker, message) => {
-  server.releaseRequest(message.requestId, { incrementCompleted: true });
+server.onWorkerMessage("status_update", (worker, message) => {
+  // Handle status updates from worker
 });
 ```
 
-#### Available Worker Selection
+#### Sending Messages
+
+```typescript
+// Send to a specific worker
+const success = server.send("worker-1", { type: "stop", reason: "shutdown" });
+
+// Broadcast to all connected workers
+server.broadcast({ type: "maintenance_start" });
+```
 
-Workers are selected based on capacity and model support.
+#### Pool Queries
 
 ```typescript
-// Get least-loaded worker supporting a model
-const worker = server.getAvailableWorker("gpt-4");
-// → least-loaded worker that supports "gpt-4"
+// Get least-loaded worker supporting a specific model
+const worker = server.getAvailableWorker("sonnet-3.5");
 
 // Get any available worker (model-agnostic)
 const anyWorker = server.getAnyAvailableWorker();
-// → any worker (Available or Busy status)
-```
 
-Workers are marked `Busy` when `activeRequests >= maxConcurrentRequests`.
-
-#### Per-Category Concurrency Limits
+// Get all worker info
+const workers = server.getWorkerInfo(); // Returns WorkerInfo[]
+```
 
-Workers can define per-category limits in their capabilities. The pool enforces these when `trackRequest` is called with a category.
+#### Request Tracking
 
 ```typescript
-// Worker capabilities include:
-{
-  models: [{ modelId: "gpt-4", ... }],
-  maxConcurrentRequests: 5,
-  concurrencyLimits: {
-    inference: 2,
-    embedding: 4,
-  }
-}
+// Track a request assigned to a worker
+server.trackRequest("worker-1", "req-123", "inference");
 
-// Track request in a category
-server.trackRequest(worker.id, "req-1", "inference");
+// Release a completed request
+server.releaseRequest("req-123", { incrementCompleted: true });
 ```
 
-### Message Routing
+#### Extensibility
+
+| Method | Description |
+|--|---|
+| `addHttpHandler(handler)` | Add an HTTP handler (called in order until one returns `true`) |
+| `addWebSocketEndpoint(path, handler)` | Add a WebSocket endpoint at a custom path |
 
-Messages are routed by the `type` field to registered handlers.
+#### Event Handlers
 
-```typescript
-server.onWorkerMessage("work_complete", (worker, message) => {
-  console.log(`Worker ${worker.id} completed ${message.requestId}`);
-});
+| Method | Return | Description |
+|--|--|---|
+| `onWorkerConnected(handler)` | `() => void` | Called when worker registers |
+| `onWorkerDisconnected(handler)` | `() => void` | Called when worker disconnects (includes pending requests) |
+| `onWorkerMessage(type, handler)` | `() => void` | Register handler for a message type |
 
-server.onWorkerMessage("metrics", (worker, message) => {
-  console.log(`Worker ${worker.id} metrics:`, message.metrics);
-});
-```
+### WorkerPool
 
-Returns an unsubscribe function:
+Internal class managing worker state and selection. Exposed via `WorkerServer`.
 
-```typescript
-const unsubscribe = server.onWorkerMessage("status", handler);
-// later...
-unsubscribe();
-```
+| Method | Description |
+|--|---|
+| `getAvailableWorker(model, category?)` | Get least-loaded available worker supporting model |
+| `getAnyAvailableWorker()` | Get any available/busy worker |
+| `trackRequest(workerId, requestId, category?)` | Mark request as in-progress |
+| `releaseRequest(requestId, { incrementCompleted? })` | Release tracked request |
+| `getWorkerInfoList()` | Get public info for all workers |
+| `checkHealth(timeoutMs)` | Return IDs of dead workers (heartbeat > 3x timeout) |
+| `send(workerId, message)` | Send message to specific worker |
+| `broadcast(message)` | Broadcast to all workers |
+| `closeAll()` | Close all worker connections |
 
-### Sending Messages
+### ConnectionHandler
 
-#### Targeted Send
+Handles WebSocket connection lifecycle and protocol message routing.
+
+#### Message Routing
 
 ```typescript
-const success = server.send(workerId, { type: "ping" });
-// Returns false if worker not found or WebSocket not open
-```
+import { ConnectionHandler } from "@hardlydifficult/worker-server";
 
-#### Broadcast
+const handler = new ConnectionHandler(pool, config, logger);
 
-```typescript
-server.broadcast({ type: "shutdown" });
-// Sends to all connected workers with open sockets
+// Register handlers for custom message types
+const unregister = handler.onMessage("custom_type", (worker, message) => {
+  console.log(`Received from ${worker.id}:`, message);
+});
 ```
 
-### Server Extensibility
-
-#### Additional WebSocket Endpoints
+#### Event Handlers
 
 ```typescript
-// Create a custom WebSocket endpoint
-server.addWebSocketEndpoint("/ws/metrics", (ws) => {
-  ws.on("message", (data) => {
-    console.log("Metrics client message:", data.toString());
-  });
+handler.onWorkerConnected((worker) => {
+  console.log("Worker connected:", worker.id);
 });
 
-// Clients connect to ws://localhost:8080/ws/metrics
+handler.onWorkerDisconnected((worker, pending) => {
+  console.log("Worker disconnected with pending:", pending.size);
+});
 ```
 
-#### HTTP Handlers
+## Advanced Features
+
+### HTTP Endpoints
+
+Custom HTTP handlers can be added:
 
 ```typescript
 server.addHttpHandler(async (req, res) => {
@@ -219,192 +233,171 @@ server.addHttpHandler(async (req, res) => {
     res.end(JSON.stringify({ status: "ok" }));
     return true;
   }
-  return false; // continue to next handler or 404
+  return false; // continue to next handler
 });
-
-// Custom HTTP responses take precedence over 404
 ```
 
-## Public API
+### Custom WebSocket Endpoints
 
-### `WorkerServer`
+Additional WebSocket paths can be handled:
 
-Main server class for managing worker connections.
-
-| Method | Description |
-|--------|-------------|
-| `onWorkerConnected(handler)` | Register handler for worker registration events |
-| `onWorkerDisconnected(handler)` | Register handler for worker disconnection events |
-| `onWorkerMessage(type, handler)` | Register handler for a specific message type |
-| `send(workerId, message)` | Send a JSON message to a specific worker |
-| `broadcast(message)` | Broadcast a JSON message to all workers |
-| `getAvailableWorker(model, category?)` | Get least-loaded worker supporting model |
-| `getAnyAvailableWorker()` | Get any available/Busy worker |
-| `getWorkerCount()` | Total connected worker count |
-| `getAvailableWorkerCount()` | Available worker count |
-| `getWorkerInfo()` | Get public info about all workers |
-| `trackRequest(workerId, requestId, category?)` | Track request as in-progress |
-| `releaseRequest(requestId, options?)` | Release tracked request |
-| `addHttpHandler(handler)` | Add HTTP request handler |
-| `addWebSocketEndpoint(path, handler)` | Add custom WebSocket endpoint |
-| `start()` | Start HTTP + WebSocket server |
-| `stop()` | Stop server and close all connections |
-
-### `WorkerPool`
-
-Internal pool manager with public helpers.
-
-| Method | Description |
-|--------|-------------|
-| `add(worker)` | Add a connected worker to the pool |
-| `remove(id)` | Remove worker by ID |
-| `get(id)` | Get worker by ID |
-| `has(id)` | Check if worker is in pool |
-| `getAvailableWorker(model, category?)` | Get available worker by model |
-| `getAnyAvailableWorker()` | Get any available/Busy worker |
-| `getCount()` | Total worker count |
-| `getAvailableCount()` | Available worker count |
-| `getWorkerInfoList()` | Get public info for all workers |
-| `checkHealth(timeoutMs)` | Check worker health and return dead IDs |
-| `send(workerId, message)` | Send message to worker |
-| `broadcast(message)` | Broadcast to all workers |
-| `closeAll()` | Close all worker connections |
+```typescript
+server.addWebSocketEndpoint("/ws/admin", (ws) => {
+  ws.on("message", (data) => {
+    // Handle admin WebSocket messages
+  });
+});
+```
 
-### `toWorkerInfo(worker)`
+### Authentication
 
-Converts internal `ConnectedWorker` to public `WorkerInfo`.
+Optionally require authentication tokens from workers:
 
 ```typescript
-import { toWorkerInfo, type ConnectedWorker } from "@hardlydifficult/worker-server";
+const server = new WorkerServer({
+  port: 8080,
+  authToken: "your-secret-token"
+});
 
-const internal: ConnectedWorker = /* ... */;
-const publicInfo = toWorkerInfo(internal);
-// No websocket reference in publicInfo
+// Workers must send registration with matching authToken
 ```
 
-### Types
+### Load Balancing with Category Limits
 
-| Type | Description |
-|------|-------------|
-| `WorkerStatus` | `available`, `busy`, `draining`, `unhealthy` |
-| `ModelInfo` | Model capabilities and metadata |
-| `WorkerCapabilities` | Worker capacity, models, and concurrency limits |
-| `WorkerInfo` | Public worker state |
-| `ConnectedWorker` | Internal state (includes WebSocket) |
-| `WorkerServerOptions` | Configuration for `WorkerServer` |
-| `WorkerServerLogger` | Logger interface |
-| `HttpRequestHandler` | HTTP request handler type |
-| `WorkerMessageHandler<T>` | Typed message handler |
-| `WorkerConnectedHandler` | Worker connected event handler |
-| `WorkerDisconnectedHandler` | Worker disconnected event handler |
-| `WebSocketConnectionHandler` | Custom WebSocket endpoint handler |
+Workers can declare per-category concurrency limits:
 
-### Constants and Defaults
+```typescript
+const capabilities = {
+  models: [{ modelId: "sonnet", ... }],
+  maxConcurrentRequests: 10,
+  concurrencyLimits: {
+    inference: 5, // max 5 concurrent inference requests
+    embeddings: 2 // max 2 concurrent embedding requests
+  }
+};
+```
 
-Default timeouts (milliseconds):
+Requests are then tracked by category:
 
 ```typescript
-{
-  heartbeatTimeoutMs: 60_000,
-  healthCheckIntervalMs: 10_000,
-  heartbeatIntervalMs: 15_000,
-}
+server.trackRequest("worker-1", "req-1", "inference");
+server.releaseRequest("req-1"); // category looked up automatically
 ```
 
-### Utility Functions
+## Types and Interfaces
+
+### WorkerInfo
+
+| Field | Type | Description |
+|--|------|---|
+| `id` | `string` | Unique worker identifier |
+| `name` | `string` | Worker-assigned name |
+| `status` | `WorkerStatus` | Current status (`available`, `busy`, `draining`, `unhealthy`) |
+| `capabilities` | `WorkerCapabilities` | Supported models and limits |
+| `sessionId` | `string` | Unique session identifier |
+| `connectedAt` | `Date` | Connection timestamp |
+| `lastHeartbeat` | `Date` | Last heartbeat timestamp |
+| `activeRequests` | `number` | Currently active requests |
+| `completedRequests` | `number` | Completed request count |
+| `pendingRequestIds` | `ReadonlySet<string>` | Pending request IDs |
+| `categoryActiveRequests` | `ReadonlyMap<string, number>` | Active requests per category |
+
+### WorkerCapabilities
+
+| Field | Type | Description |
+|--|------|---|
+| `models` | `ModelInfo[]` | Supported models |
+| `maxConcurrentRequests` | `number` | Overall concurrency limit |
+| `metadata?` | `Record<string, unknown>` | Optional metadata |
+| `concurrencyLimits?` | `Record<string, number>` | Per-category concurrency limits |
+
+### ModelInfo
+
+| Field | Type | Description |
+|--|------|---|
+| `modelId` | `string` | Model identifier |
+| `displayName` | `string` | Human-readable name |
+| `maxContextTokens` | `number` | Maximum context window |
+| `maxOutputTokens` | `number` | Maximum output length |
+| `supportsStreaming` | `boolean` | Streaming support |
+| `supportsVision?` | `boolean` | Vision support (optional) |
+| `supportsTools?` | `boolean` | Tool use support (optional) |
+
+### WorkerStatus
+
+- `"available"` — Worker can accept new requests
+- `"busy"` — Worker at max concurrency
+- `"draining"` — Worker shutting down, no new requests
+- `"unhealthy"` — Missed heartbeats
+
+### Configuration Options
 
-#### `safeCompare(a, b)`
+```typescript
+interface WorkerServerOptions {
+  port: number;
+  authToken?: string;
+  heartbeatTimeoutMs?: number; // default: 60000
+  healthCheckIntervalMs?: number; // default: 10000
+  heartbeatIntervalMs?: number; // default: 15000
+  logger?: WorkerServerLogger;
+}
+```
 
-Timing-safe string comparison.
+### Logger Interface
 
 ```typescript
-import { safeCompare } from "@hardlydifficult/worker-server";
-
-const isValid = safeCompare(inputToken, secretToken);
+interface WorkerServerLogger {
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
 ```
 
 ## Appendix
 
-### Worker Registration Protocol
+### Protocol Messages
 
-Workers send:
+**Worker Registration (worker → server)**
 
-```json
+```typescript
 {
-  "type": "worker_registration",
-  "workerId": "worker-1",
-  "workerName": "My Worker",
-  "capabilities": {
-    "models": [{
-      "modelId": "gpt-4",
-      "displayName": "GPT-4",
-      "maxContextTokens": 8192,
-      "maxOutputTokens": 4096,
-      "supportsStreaming": true
-    }],
-    "maxConcurrentRequests": 5,
-    "concurrencyLimits": {
-      "inference": 2,
-      "embedding": 4
-    }
-  },
-  "authToken": "optional"
+  type: "worker_registration",
+  workerId: string,
+  workerName: string,
+  capabilities: WorkerCapabilities,
+  authToken?: string
 }
 ```
 
-Server responds:
+**Registration Acknowledgment (server → worker)**
 
-```json
+```typescript
 {
-  "type": "worker_registration_ack",
-  "success": true,
-  "sessionId": "uuid",
-  "heartbeatIntervalMs": 15000
+  type: "worker_registration_ack",
+  success: boolean,
+  error?: string,
+  sessionId?: string,
+  heartbeatIntervalMs?: number
 }
 ```
 
-### Worker Heartbeat Protocol
+**Heartbeat (worker → server)**
 
-Workers send:
-
-```json
+```typescript
 {
-  "type": "heartbeat",
-  "workerId": "worker-1",
-  "timestamp": "2024-01-01T00:00:00.000Z"
+  type: "heartbeat",
+  workerId: string,
+  timestamp: string
 }
 ```
 
-Server responds:
+**Heartbeat Acknowledgment (server → worker)**
 
-```json
+```typescript
 {
-  "type": "heartbeat_ack",
-  "timestamp": "2024-01-01T00:00:00.000Z",
-  "nextHeartbeatDeadline": "2024-01-01T00:01:00.000Z"
+  type: "heartbeat_ack",
+  timestamp: string,
+  nextHeartbeatDeadline: string
 }
-```
-
-### Status Transitions
-
-- `Available` → `Busy` when `activeRequests >= maxConcurrentRequests`
-- `Busy` → `Available` when `activeRequests < maxConcurrentRequests`
-- Any → `Unhealthy` on heartbeat timeout
-- `Unhealthy` → `Available/Busy` on heartbeat recovery
-
-### Concurrent Request Tracking
-
-The pool tracks requests per-worker and per-category (if provided). It automatically decrements the category count when releasing a tracked request.
-
-### Worker Protocol Summary
-
-Workers communicate using JSON messages with a `type` field:
-
-| Message | Direction | Description |
-|---------|-----------|-------------|
-| `worker_registration` | Worker → Server | Register with capabilities |
-| `worker_registration_ack` | Server → Worker | Acknowledgment with session ID |
-| `heartbeat` | Worker → Server | Periodic health check |
-| `heartbeat_ack` | Server → Worker | Acknowledgment with next deadline |
-
-All other message types are routed to registered handlers via `onWorkerMessage()`.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/worker-server",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [