@hardlydifficult/worker-server 1.0.7 → 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,29 +13,80 @@ npm install @hardlydifficult/worker-server
 ```typescript
 import { WorkerServer } from "@hardlydifficult/worker-server";
 
-const server = new WorkerServer({ port: 8080 });
+const server = new WorkerServer({ port: 3000 });
 
 server.onWorkerConnected((worker) => {
-  console.log(`Worker ${worker.name} connected (${worker.id})`);
+  console.log("Worker connected:", worker.id);
+});
+
+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.onWorkerDisconnected((worker, pending) => {
-  console.log(`Worker ${worker.name} disconnected with ${pending.size} pending requests`);
+await server.start();
+console.log("Worker server running on port 3000");
+```
+
+## Core Concepts
+
+### Worker Registration
+
+Workers connect via WebSocket and register with identity and capabilities. The server supports optional authentication and tracks worker health via heartbeat protocol.
+
+```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.
 
+```typescript
 server.onWorkerMessage("work_complete", (worker, message) => {
-  console.log(`Worker ${worker.id} completed request ${message.requestId}`);
+  console.log("Work completed for", message.requestId);
 });
 
-await server.start();
-console.log("Server listening on port 8080");
+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
 
-WebSocket server managing remote worker connections with health checks, message routing, and pool management.
+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
 
@@ -109,49 +160,36 @@ server.trackRequest("worker-1", "req-123", "inference");
 server.releaseRequest("req-123", { incrementCompleted: true });
 ```
 
-### WorkerPool
-
-Manages worker lifecycle, request tracking, health checks, and message routing.
+#### Extensibility
 
-#### Worker Status
+| 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 |
 
-Workers transition automatically between states:
-- `available`: Ready to accept new requests
-- `busy`: At maximum concurrent request capacity
-- `draining`: In the process of shutting down
-- `unhealthy`: Heartbeat missed beyond timeout threshold
-
-#### Pool Operations
-
-```typescript
-import { WorkerPool, WorkerStatus, type ConnectedWorker } from "@hardlydifficult/worker-server";
-
-const pool = new WorkerPool();
-
-// Get the least-loaded available worker supporting a model
-const worker = pool.getAvailableWorker("sonnet-3.5", "inference");
-
-// Get any available or busy worker
-const anyWorker = pool.getAnyAvailableWorker();
-
-// Get count statistics
-const total = pool.getCount();
-const available = pool.getAvailableCount();
+#### Event Handlers
 
-// Get worker info (without WebSocket reference)
-const workers = pool.getWorkerInfoList();
+| 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 |
 
-// Track and release requests
-pool.trackRequest("worker-1", "req-123");
-pool.releaseRequest("req-123");
+### WorkerPool
 
-// Check for unhealthy workers
-const deadWorkerIds = pool.checkHealth(60_000); // 60-second timeout
+Internal class managing worker state and selection. Exposed via `WorkerServer`.
 
-// Send and broadcast messages
-pool.send("worker-1", { type: "ping" });
-pool.broadcast({ type: "shutdown" });
-```
+| 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
 
@@ -182,75 +220,6 @@ handler.onWorkerDisconnected((worker, pending) => {
 });
 ```
 
-## Types and Interfaces
-
-### WorkerInfo
-
-Public worker metadata exposed to consumers:
-
-```typescript
-interface WorkerInfo {
-  id: string;
-  name: string;
-  status: WorkerStatus;
-  capabilities: WorkerCapabilities;
-  sessionId: string;
-  connectedAt: Date;
-  lastHeartbeat: Date;
-  activeRequests: number;
-  completedRequests: number;
-  pendingRequestIds: ReadonlySet<string>;
-  categoryActiveRequests: ReadonlyMap<string, number>;
-}
-```
-
-### WorkerCapabilities
-
-Describes what a worker can do:
-
-```typescript
-interface WorkerCapabilities {
-  models: ModelInfo[];
-  maxConcurrentRequests: number;
-  metadata?: Record<string, unknown>;
-  concurrencyLimits?: Record<string, number>; // per-category limits
-}
-
-interface ModelInfo {
-  modelId: string;
-  displayName: string;
-  maxContextTokens: number;
-  maxOutputTokens: number;
-  supportsStreaming: boolean;
-  supportsVision?: boolean;
-  supportsTools?: boolean;
-}
-```
-
-### Configuration Options
-
-```typescript
-interface WorkerServerOptions {
-  port: number;
-  authToken?: string;
-  heartbeatTimeoutMs?: number; // default: 60000
-  healthCheckIntervalMs?: number; // default: 10000
-  heartbeatIntervalMs?: number; // default: 15000
-  logger?: WorkerServerLogger;
-}
-```
-
-### Logger Interface
-
-```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;
-}
-```
-
 ## Advanced Features
 
 ### HTTP Endpoints
@@ -313,4 +282,122 @@ Requests are then tracked by category:
 ```typescript
 server.trackRequest("worker-1", "req-1", "inference");
 server.releaseRequest("req-1"); // category looked up automatically
+```
+
+## 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
+
+```typescript
+interface WorkerServerOptions {
+  port: number;
+  authToken?: string;
+  heartbeatTimeoutMs?: number; // default: 60000
+  healthCheckIntervalMs?: number; // default: 10000
+  heartbeatIntervalMs?: number; // default: 15000
+  logger?: WorkerServerLogger;
+}
+```
+
+### Logger Interface
+
+```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;
+}
+```
+
+## Appendix
+
+### Protocol Messages
+
+**Worker Registration (worker → server)**
+
+```typescript
+{
+  type: "worker_registration",
+  workerId: string,
+  workerName: string,
+  capabilities: WorkerCapabilities,
+  authToken?: string
+}
+```
+
+**Registration Acknowledgment (server → worker)**
+
+```typescript
+{
+  type: "worker_registration_ack",
+  success: boolean,
+  error?: string,
+  sessionId?: string,
+  heartbeatIntervalMs?: number
+}
+```
+
+**Heartbeat (worker → server)**
+
+```typescript
+{
+  type: "heartbeat",
+  workerId: string,
+  timestamp: string
+}
+```
+
+**Heartbeat Acknowledgment (server → worker)**
+
+```typescript
+{
+  type: "heartbeat_ack",
+  timestamp: string,
+  nextHeartbeatDeadline: string
+}
 ```

package/package.json

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