@hardlydifficult/worker-server 1.0.5 → 1.0.7

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/worker-server
 
-A WebSocket-based worker server that manages remote worker connections, health monitoring, request routing, and load balancing through a clean TypeScript interface.
+WebSocket-based worker server with health monitoring, request routing, and load balancing.
 
 ## Installation
 
@@ -13,197 +13,209 @@ npm install @hardlydifficult/worker-server
 ```typescript
 import { WorkerServer } from "@hardlydifficult/worker-server";
 
-const server = new WorkerServer({
-  port: 8080,
-  heartbeatTimeoutMs: 60000,  // 60 seconds
-  healthCheckIntervalMs: 10000,  // 10 seconds
-});
+const server = new WorkerServer({ port: 8080 });
 
 server.onWorkerConnected((worker) => {
-  console.log(`Worker connected: ${worker.name} (${worker.id})`);
+  console.log(`Worker ${worker.name} connected (${worker.id})`);
 });
 
-server.onWorkerDisconnected((worker, pendingRequests) => {
-  console.log(`Worker disconnected: ${worker.name} (${worker.id})`);
-  if (pendingRequests.size > 0) {
-    console.log(`Rescheduling ${pendingRequests.size} pending requests`);
-  }
+server.onWorkerDisconnected((worker, pending) => {
+  console.log(`Worker ${worker.name} disconnected with ${pending.size} pending requests`);
 });
 
 server.onWorkerMessage("work_complete", (worker, message) => {
-  console.log(`Work complete: ${message.requestId}`);
-});
-
-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;
+  console.log(`Worker ${worker.id} completed request ${message.requestId}`);
 });
 
 await server.start();
-console.log("Worker server running on port 8080");
+console.log("Server listening on port 8080");
 ```
 
-## Core Concepts
+## Core Components
 
-### Worker Management
-
-Workers connect via WebSocket, register with capabilities (supported models, concurrency limits), and send periodic heartbeats. The server tracks their status (available, busy, draining, unhealthy) and makes routing decisions based on load and model compatibility.
-
-### Request Tracking
-
-Requests are tracked per-worker and can be released when complete. Optional categories enable per-category concurrency limits when workers declare `concurrencyLimits` in their capabilities.
+### WorkerServer
 
-### Load Balancing
+WebSocket server managing remote worker connections with health checks, message routing, and pool management.
 
-Workers are selected based on:
-- Model support (exact or substring match)
-- Current load (least-loaded algorithm)
-- Category-specific limits (when `category` is provided)
+#### Lifecycle Management
 
-## API Reference
+```typescript
+const server = new WorkerServer({ port: 8080, authToken: "secret" });
 
-### WorkerServer
+// Start the server
+await server.start();
 
-Main entry point for managing worker connections.
+// Stop the server gracefully
+await server.stop();
+```
 
-#### Constructor
+#### Registration Handlers
 
 ```typescript
-constructor(options: WorkerServerOptions)
-```
+// Called when a worker successfully registers
+const unsubscribeConnected = server.onWorkerConnected((worker) => {
+  console.log(`Worker connected: ${worker.name}`);
+});
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `port` | `number` | — | HTTP + WebSocket server port |
-| `authToken` | `string` | `undefined` | Optional token required for worker registration |
-| `heartbeatTimeoutMs` | `number` | `60000` | Milliseconds before a missed heartbeat marks a worker unhealthy |
-| `healthCheckIntervalMs` | `number` | `10000` | Interval (ms) for health checks |
-| `heartbeatIntervalMs` | `number` | `15000` | Heartbeat interval communicated to workers |
-| `logger` | `WorkerServerLogger` | `undefined` | Logger instance (defaults to no-op) |
+// Called when a worker disconnects
+const unsubscribeDisconnected = server.onWorkerDisconnected((worker, pending) => {
+  console.log(`Worker disconnected with ${pending.size} pending requests`);
+});
+```
 
-#### Lifecycle Events
+#### Message Handling
 
 ```typescript
-// Called when a worker successfully registers
-onWorkerConnected(handler: WorkerConnectedHandler): () => void;
-
-// Called when a worker disconnects with pending request IDs
-onWorkerDisconnected(handler: WorkerDisconnectedHandler): () => void;
+// Register handlers for domain-specific messages by type
+server.onWorkerMessage("work_request", (worker, message) => {
+  // Process work request from worker
+});
 
-// Register a handler for a specific message type (dispatched by 'type' field)
-onWorkerMessage<T = Record<string, unknown>>(
-  type: string,
-  handler: WorkerMessageHandler<T>
-): () => void;
+server.onWorkerMessage("status_update", (worker, message) => {
+  // Handle status updates from worker
+});
 ```
 
-#### Message Operations
+#### Sending Messages
 
 ```typescript
-// Send a JSON message to a specific worker (false if failed)
-send(workerId: string, message: Record<string, unknown>): boolean;
+// Send to a specific worker
+const success = server.send("worker-1", { type: "stop", reason: "shutdown" });
 
 // Broadcast to all connected workers
-broadcast(message: Record<string, unknown>): void;
+server.broadcast({ type: "maintenance_start" });
 ```
 
 #### Pool Queries
 
 ```typescript
-// Get least-loaded worker supporting the given model
-getAvailableWorker(model: string, category?: string): WorkerInfo | null;
+// Get least-loaded worker supporting a specific model
+const worker = server.getAvailableWorker("sonnet-3.5");
 
 // Get any available worker (model-agnostic)
-getAnyAvailableWorker(): WorkerInfo | null;
+const anyWorker = server.getAnyAvailableWorker();
+
+// Get all worker info
+const workers = server.getWorkerInfo(); // Returns WorkerInfo[]
+```
 
-// Total connected worker count
-getWorkerCount(): number;
+#### Request Tracking
 
-// Available worker count
-getAvailableWorkerCount(): number;
+```typescript
+// Track a request assigned to a worker
+server.trackRequest("worker-1", "req-123", "inference");
 
-// Get info about all connected workers
-getWorkerInfo(): WorkerInfo[];
+// Release a completed request
+server.releaseRequest("req-123", { incrementCompleted: true });
 ```
 
-#### Request Tracking
+### WorkerPool
+
+Manages worker lifecycle, request tracking, health checks, and message routing.
+
+#### Worker Status
+
+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
-// Track a request assigned to a worker (optional category)
-trackRequest(workerId: string, requestId: string, category?: string): void;
+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();
 
-// Release a tracked request (optionally increment completed count)
-releaseRequest(
-  requestId: string,
-  options?: { incrementCompleted?: boolean }
-): void;
+// Get worker info (without WebSocket reference)
+const workers = pool.getWorkerInfoList();
+
+// Track and release requests
+pool.trackRequest("worker-1", "req-123");
+pool.releaseRequest("req-123");
+
+// Check for unhealthy workers
+const deadWorkerIds = pool.checkHealth(60_000); // 60-second timeout
+
+// Send and broadcast messages
+pool.send("worker-1", { type: "ping" });
+pool.broadcast({ type: "shutdown" });
 ```
 
-#### HTTP & WebSocket Extensibility
+### ConnectionHandler
+
+Handles WebSocket connection lifecycle and protocol message routing.
+
+#### Message Routing
 
 ```typescript
-// Add an HTTP handler (called in order until one returns true)
-addHttpHandler(handler: HttpRequestHandler): void;
+import { ConnectionHandler } from "@hardlydifficult/worker-server";
 
-// Add an additional WebSocket endpoint at a path
-addWebSocketEndpoint(
-  path: string,
-  handler: WebSocketConnectionHandler
-): void;
+const handler = new ConnectionHandler(pool, config, logger);
+
+// Register handlers for custom message types
+const unregister = handler.onMessage("custom_type", (worker, message) => {
+  console.log(`Received from ${worker.id}:`, message);
+});
 ```
 
-#### Server Lifecycle
+#### Event Handlers
 
 ```typescript
-// Start the HTTP + WebSocket server
-start(): Promise<void>;
+handler.onWorkerConnected((worker) => {
+  console.log("Worker connected:", worker.id);
+});
 
-// Stop the server and close all connections
-stop(): Promise<void>;
+handler.onWorkerDisconnected((worker, pending) => {
+  console.log("Worker disconnected with pending:", pending.size);
+});
 ```
 
+## Types and Interfaces
+
 ### WorkerInfo
 
-Public interface representing a connected worker:
+Public worker metadata exposed to consumers:
 
 ```typescript
 interface WorkerInfo {
-  readonly id: string;
-  readonly name: string;
-  readonly status: WorkerStatus;  // "available" | "busy" | "draining" | "unhealthy"
-  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>;
+  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 a worker's capabilities:
+Describes what a worker can do:
 
 ```typescript
 interface WorkerCapabilities {
   models: ModelInfo[];
   maxConcurrentRequests: number;
   metadata?: Record<string, unknown>;
-  concurrencyLimits?: Record<string, number>;
+  concurrencyLimits?: Record<string, number>; // per-category limits
 }
-```
 
-### ModelInfo
-
-Describes a supported model:
-
-```typescript
 interface ModelInfo {
   modelId: string;
   displayName: string;
@@ -215,32 +227,90 @@ interface ModelInfo {
 }
 ```
 
-### WorkerStatus
+### Configuration Options
 
-Worker state enumeration:
+```typescript
+interface WorkerServerOptions {
+  port: number;
+  authToken?: string;
+  heartbeatTimeoutMs?: number; // default: 60000
+  healthCheckIntervalMs?: number; // default: 10000
+  heartbeatIntervalMs?: number; // default: 15000
+  logger?: WorkerServerLogger;
+}
+```
 
-| Status | Description |
-|--------|-------------|
-| `available` | Worker is idle and can accept new requests |
-| `busy` | Worker is at max concurrent requests but may accept model-agnostic tasks |
-| `draining` | Worker is being gracefully decommissioned |
-| `unhealthy` | Worker has missed heartbeats and is presumed degraded |
+### Logger Interface
 
-## Worker Protocol
+```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;
+}
+```
 
-Workers communicate using JSON messages with a `type` field:
+## Advanced Features
 
-| 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 |
+### HTTP Endpoints
 
-All other message types are routed to registered handlers via `onWorkerMessage()`.
+Custom HTTP handlers can be added:
 
-## Health Monitoring
+```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
+});
+```
 
-- Workers missing heartbeats for `heartbeatTimeoutMs` are marked `unhealthy`
-- Workers missing heartbeats for `3 × heartbeatTimeoutMs` are disconnected
-- Health checks run every `healthCheckIntervalMs`
+### Custom WebSocket Endpoints
+
+Additional WebSocket paths can be handled:
+
+```typescript
+server.addWebSocketEndpoint("/ws/admin", (ws) => {
+  ws.on("message", (data) => {
+    // Handle admin WebSocket messages
+  });
+});
+```
+
+### Authentication
+
+Optionally require authentication tokens from workers:
+
+```typescript
+const server = new WorkerServer({
+  port: 8080,
+  authToken: "your-secret-token"
+});
+
+// Workers must send registration with matching authToken
+```
+
+### Load Balancing with Category Limits
+
+Workers can declare per-category concurrency limits:
+
+```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
+```

package/package.json

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