@hardlydifficult/worker-server 1.0.9 → 1.0.11

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/worker-server
 
-A WebSocket-based worker server for managing remote worker connections with health monitoring, request routing, and load balancing.
+WebSocket-based remote worker server with health monitoring, message routing, and load balancing.
 
 ## Installation
 
@@ -11,393 +11,267 @@ npm install @hardlydifficult/worker-server
 ## Quick Start
 
 ```typescript
-import { WorkerServer } from "@hardlydifficult/worker-server";
+import { WorkerServer, WorkerStatus } from "@hardlydifficult/worker-server";
 
-const server = new WorkerServer({ port: 3000 });
+const server = new WorkerServer({
+  port: 19100,
+  authToken: "secret-token", // optional
+});
 
 server.onWorkerConnected((worker) => {
-  console.log("Worker connected:", worker.id);
+  console.log(`Worker ${worker.name} connected with status ${worker.status}`);
 });
 
-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 });
+server.onWorkerMessage("work_result", (worker, message) => {
+  console.log(`Worker ${worker.id} completed request:`, message);
 });
 
 await server.start();
-console.log("Worker server running on port 3000");
+console.log("Worker server listening on port", server.port);
 ```
 
 ## Core Concepts
 
-### Worker Registration
+### WorkerServer
 
-Workers connect via WebSocket and register with identity and capabilities. The server supports optional authentication and tracks worker health via heartbeat protocol.
+Main entry point for managing worker connections via WebSocket.
 
 ```typescript
-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(", ")}`
-  );
-});
-```
-
-### Message Routing
-
-Messages are dispatched by `type` field to registered handlers.
+import { WorkerServer } from "@hardlydifficult/worker-server";
 
-```typescript
-server.onWorkerMessage("work_complete", (worker, message) => {
-  console.log("Work completed for", message.requestId);
+const server = new WorkerServer({
+  port: 19100,
+  authToken: "secret", // optional
+  heartbeatTimeoutMs: 60_000,
+  healthCheckIntervalMs: 10_000,
+  heartbeatIntervalMs: 15_000,
+  logger: myLogger,
 });
 
-server.send(workerId, { type: "work_request", requestId: "req-1" });
-server.broadcast({ type: "shutdown" });
-```
-
-### Request Tracking & Load Balancing
-
-Track active requests and select the least-loaded available worker.
-
-```typescript
-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 });
-```
-
-## Core Components
-
-### WorkerServer
-
-Main server class managing WebSocket connections, HTTP endpoints, and worker pool.
-
-#### Constructor
-
-| 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
-const server = new WorkerServer({ port: 8080, authToken: "secret" });
-
-// Start the server
 await server.start();
-
-// Stop the server gracefully
+// Handle connections, messages, and shutdown
 await server.stop();
 ```
 
-#### Registration Handlers
-
-```typescript
-// Called when a worker successfully registers
-const unsubscribeConnected = server.onWorkerConnected((worker) => {
-  console.log(`Worker connected: ${worker.name}`);
-});
+#### Lifecycle Events
 
-// Called when a worker disconnects
-const unsubscribeDisconnected = server.onWorkerDisconnected((worker, pending) => {
-  console.log(`Worker disconnected with ${pending.size} pending requests`);
-});
-```
-
-#### Message Handling
+| Method | Description |
+|--------|-------------|
+| `onWorkerConnected(handler)` | Called when a worker registers successfully |
+| `onWorkerDisconnected(handler)` | Called when a worker disconnects; includes pending request IDs |
 
 ```typescript
-// Register handlers for domain-specific messages by type
-server.onWorkerMessage("work_request", (worker, message) => {
-  // Process work request from worker
+server.onWorkerConnected((worker) => {
+  console.log(`Connected: ${worker.id} (${worker.name})`);
 });
 
-server.onWorkerMessage("status_update", (worker, message) => {
-  // Handle status updates from worker
+server.onWorkerDisconnected((worker, pendingRequestIds) => {
+  console.log(`Disconnected: ${worker.id} with ${pendingRequestIds.size} pending requests`);
 });
 ```
 
-#### Sending Messages
+#### Message Routing
+
+Register handlers for message types sent by workers:
 
 ```typescript
-// Send to a specific worker
-const success = server.send("worker-1", { type: "stop", reason: "shutdown" });
+server.onWorkerMessage("work_complete", (worker, message) => {
+  const { requestId, result } = message;
+  console.log(`Worker ${worker.id} completed ${requestId}`);
+});
 
-// Broadcast to all connected workers
-server.broadcast({ type: "maintenance_start" });
+// Send messages to workers
+const success = server.send(workerId, { type: "work_request", requestId: "req-1" });
+server.broadcast({ type: "shutdown" });
 ```
 
-#### Pool Queries
+#### Worker Selection & Pool Queries
 
 ```typescript
-// Get least-loaded worker supporting a specific model
-const worker = server.getAvailableWorker("sonnet-3.5");
+// Get least-loaded worker supporting a model
+const worker = server.getAvailableWorker("sonnet");
 
 // Get any available worker (model-agnostic)
-const anyWorker = server.getAnyAvailableWorker();
+const any = server.getAnyAvailableWorker();
+
+// Slot counts
+console.log("Available slots:", server.getAvailableSlotCount("sonnet", "local"));
 
-// Get all worker info
-const workers = server.getWorkerInfo(); // Returns WorkerInfo[]
+// Worker info
+for (const info of server.getWorkerInfo()) {
+  console.log(`${info.name}: ${info.status} (${info.activeRequests}/${info.capabilities.maxConcurrentRequests})`);
+}
 ```
 
 #### Request Tracking
 
+Track and release requests for accurate availability:
+
 ```typescript
-// Track a request assigned to a worker
-server.trackRequest("worker-1", "req-123", "inference");
+// When assigning a request to a worker
+server.trackRequest(workerId, requestId, "local");
 
-// Release a completed request
-server.releaseRequest("req-123", { incrementCompleted: true });
+// When the request completes
+server.releaseRequest(requestId, { incrementCompleted: true });
 ```
 
 #### 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 |
-
-#### Event Handlers
-
-| 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 |
-
-### WorkerPool
-
-Internal class managing worker state and selection. Exposed via `WorkerServer`.
-
-| 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 |
-
-### ConnectionHandler
-
-Handles WebSocket connection lifecycle and protocol message routing.
-
-#### Message Routing
+Add HTTP endpoints and custom WebSocket paths:
 
 ```typescript
-import { ConnectionHandler } from "@hardlydifficult/worker-server";
-
-const handler = new ConnectionHandler(pool, config, logger);
+// HTTP handler
+server.addHttpHandler(async (req, res) => {
+  if (req.url === "/health") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ ok: true }));
+    return true;
+  }
+  return false;
+});
 
-// Register handlers for custom message types
-const unregister = handler.onMessage("custom_type", (worker, message) => {
-  console.log(`Received from ${worker.id}:`, message);
+// Custom WebSocket endpoint
+server.addWebSocketEndpoint("/ws/dashboard", (ws) => {
+  ws.send(JSON.stringify({ type: "hello" }));
 });
 ```
 
-#### Event Handlers
+### WorkerPool
+
+Low-level pool manager for worker state and selection.
 
 ```typescript
-handler.onWorkerConnected((worker) => {
-  console.log("Worker connected:", worker.id);
-});
+import { WorkerPool, WorkerStatus } from "@hardlydifficult/worker-server";
 
-handler.onWorkerDisconnected((worker, pending) => {
-  console.log("Worker disconnected with pending:", pending.size);
-});
+const pool = new WorkerPool(logger);
+
+pool.add(worker);
+pool.remove(workerId);
+const worker = pool.get(workerId);
 ```
 
-## Advanced Features
+#### Selection Logic
 
-### HTTP Endpoints
+- `getAvailableWorker(model, category?)`: Returns least-loaded worker supporting the model, respecting per-category concurrency limits
+- `getAnyAvailableWorker()`: Returns any worker regardless of model (both Available and Busy)
+- `getAvailableSlotCount(model, category?)`: Total free slots across all available workers for the model
 
-Custom HTTP handlers can be added:
+#### Request Management
 
-```typescript
-server.addHttpHandler(async (req, res) => {
-  if (req.url === "/health") {
-    res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ status: "ok" }));
-    return true;
-  }
-  return false; // continue to next handler
-});
-```
+| Method | Description |
+|--------|-------------|
+| `trackRequest(workerId, requestId, category?)` | Marks request as in-flight and updates status |
+| `releaseRequest(requestId, options?)` | Decrements active count, optionally increments completed count |
 
-### Custom WebSocket Endpoints
+#### Health Monitoring
 
-Additional WebSocket paths can be handled:
+| Method | Description |
+|--------|-------------|
+| `checkHealth(timeoutMs)` | Returns IDs of workers exceeding `3x` timeout; marks unhealthy ones |
 
-```typescript
-server.addWebSocketEndpoint("/ws/admin", (ws) => {
-  ws.on("message", (data) => {
-    // Handle admin WebSocket messages
-  });
-});
-```
+### ConnectionHandler
 
-### Authentication
+Handles WebSocket lifecycle, registration, heartbeats, and message routing. Most consumers use `WorkerServer`, which encapsulates this.
 
-Optionally require authentication tokens from workers:
+### Types & Interfaces
 
-```typescript
-const server = new WorkerServer({
-  port: 8080,
-  authToken: "your-secret-token"
-});
+#### `WorkerStatus`
 
-// Workers must send registration with matching authToken
-```
+| Value | Description |
+|-------|-------------|
+| `available` | Worker can accept new requests |
+| `busy` | Worker at capacity, but can accept model-agnostic tasks |
+| `draining` | Worker finishing current work before shutdown |
+| `unhealthy` | Worker failed heartbeat checks |
 
-### Load Balancing with Category Limits
+#### `WorkerInfo`
 
-Workers can declare per-category concurrency limits:
+Public worker metadata (excludes raw WebSocket):
 
 ```typescript
-const capabilities = {
-  models: [{ modelId: "sonnet", ... }],
-  maxConcurrentRequests: 10,
-  concurrencyLimits: {
-    inference: 5, // max 5 concurrent inference requests
-    embeddings: 2 // max 2 concurrent embedding requests
-  }
-};
-```
-
-Requests are then tracked by category:
-
-```typescript
-server.trackRequest("worker-1", "req-1", "inference");
-server.releaseRequest("req-1"); // category looked up automatically
+interface WorkerInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly status: WorkerStatus;
+  readonly capabilities: WorkerCapabilities;
+  readonly sessionId: string;
+  readonly connectedAt: Date;
+  readonly lastHeartbeat: Date;
+  readonly activeRequests: number;
+  readonly completedRequests: number;
+  readonly pendingRequestIds: ReadonlySet<string>;
+  readonly categoryActiveRequests: ReadonlyMap<string, number>;
+}
 ```
 
-## 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
+#### `WorkerCapabilities`
 
 ```typescript
-interface WorkerServerOptions {
-  port: number;
-  authToken?: string;
-  heartbeatTimeoutMs?: number; // default: 60000
-  healthCheckIntervalMs?: number; // default: 10000
-  heartbeatIntervalMs?: number; // default: 15000
-  logger?: WorkerServerLogger;
+interface WorkerCapabilities {
+  models: ModelInfo[];
+  maxConcurrentRequests: number;
+  metadata?: Record<string, unknown>;
+  concurrencyLimits?: Record<string, number>;
 }
 ```
 
-### Logger Interface
+#### `ModelInfo`
 
 ```typescript
-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;
+interface ModelInfo {
+  modelId: string;
+  displayName: string;
+  maxContextTokens: number;
+  maxOutputTokens: number;
+  supportsStreaming: boolean;
+  supportsVision?: boolean;
+  supportsTools?: boolean;
 }
 ```
 
-## Appendix
+### Secure Authentication
 
-### Protocol Messages
-
-**Worker Registration (worker → server)**
+Authentication tokens are compared using timing-safe comparison to prevent brute-force attacks:
 
 ```typescript
-{
-  type: "worker_registration",
-  workerId: string,
-  workerName: string,
-  capabilities: WorkerCapabilities,
-  authToken?: string
-}
+const server = new WorkerServer({
+  port: 19100,
+  authToken: "secret-token",
+});
 ```
 
-**Registration Acknowledgment (server → worker)**
+Workers must send:
 
-```typescript
+```json
 {
-  type: "worker_registration_ack",
-  success: boolean,
-  error?: string,
-  sessionId?: string,
-  heartbeatIntervalMs?: number
+  "type": "worker_registration",
+  "workerId": "worker-1",
+  "workerName": "My Worker",
+  "capabilities": { ... },
+  "authToken": "secret-token"
 }
 ```
 
-**Heartbeat (worker → server)**
+### Heartbeat Protocol
 
-```typescript
+Workers must send periodic heartbeat messages:
+
+```json
 {
-  type: "heartbeat",
-  workerId: string,
-  timestamp: string
+  "type": "heartbeat",
+  "workerId": "worker-1",
+  "timestamp": "2024-01-01T00:00:00.000Z"
 }
 ```
 
-**Heartbeat Acknowledgment (server → worker)**
+The server responds with:
 
-```typescript
+```json
 {
-  type: "heartbeat_ack",
-  timestamp: string,
-  nextHeartbeatDeadline: string
+  "type": "heartbeat_ack",
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "nextHeartbeatDeadline": "2024-01-01T00:01:15.000Z"
 }
-```
+```
+
+A worker is considered unhealthy if its heartbeat exceeds `heartbeatTimeoutMs`. It is marked dead and disconnected after `3x` the timeout.

package/package.json

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