comfyui-node 1.6.3 → 1.6.5

package/README.md

@@ -136,12 +136,64 @@ Hash-based routing intelligently handles failures at the workflow level (not cli
 
 See [Hash-Based Routing Guide](./docs/hash-routing-guide.md) for details and demos.
 
-## What's New in v1.5.0
+### Advanced: `MultiWorkflowPool` for Heterogeneous Clusters
 
-- **WorkflowPool Profiling** – Enable automatic per-node performance tracking with `enableProfiling: true`.
-- **Timeout Protection** – Prevent jobs from hanging with `executionStartTimeoutMs` and `nodeExecutionTimeoutMs`.
-- **Idle connection stability** – Automatic health checks keep WebSocket connections alive.
-- **Better DX** – Comprehensive JSDoc comments and exported types for all pool options.
+For complex use cases involving a heterogeneous cluster of workers (e.g., some with SDXL models, others for video generation), `MultiWorkflowPool` provides fine-grained control over job routing based on workflow requirements.
+
+It uses an event-driven architecture to manage clients with specific **workflow affinities**, ensuring that jobs are only sent to nodes capable of processing them.
+
+- **Workflow Affinity:** Assign clients to specific workflows. Jobs are automatically routed to the correct client.
+- **Dynamic Job Queues:** A separate job queue is created for each workflow type, preventing head-of-line blocking.
+- **Event-Driven Architecture:** Zero polling for maximum efficiency and responsiveness.
+- **Built-in Monitoring:** Optional real-time monitoring of client and queue states.
+
+**Example:**
+```ts
+import { MultiWorkflowPool, Workflow } from "comfyui-node";
+import SdxlWorkflow from './sdxl-workflow.json';
+import VideoWorkflow from './video-workflow.json';
+
+// 1. Define workflows and generate their hash for affinity mapping
+const sdxlWF = Workflow.from(SdxlWorkflow).updateHash();
+const videoWF = Workflow.from(VideoWorkflow).updateHash();
+
+// 2. Create a new pool
+const pool = new MultiWorkflowPool({
+  logLevel: "info",
+  enableMonitoring: true,
+});
+
+// 3. Add clients with workflow affinity
+// This client is specialized for SDXL workflows
+pool.addClient("http://localhost:8188", { workflowAffinity: [sdxlWF] });
+
+// This client is specialized for Video workflows
+pool.addClient("http://localhost:8189", { workflowAffinity: [videoWF] });
+
+// This client is a general-purpose worker
+pool.addClient("http://localhost:8190");
+
+// 4. Initialize the pool (connects to all clients)
+await pool.init();
+
+// 5. Submit jobs
+// The pool automatically routes them to the correct client
+const sdxlJobId = await pool.submitJob(sdxlWF);
+const videoJobId = await pool.submitJob(videoWF);
+
+// 6. Wait for a job to complete
+const results = await pool.waitForJobCompletion(sdxlJobId);
+console.log("SDXL Job completed!", results.images);
+```
+
+## What's New in v1.6.5
+
+- **Integration Test Infrastructure** – Comprehensive reconnection testing with real mock server processes
+  - Mock servers spawn in separate OS processes that can be killed/restarted
+  - 13 integration tests covering manual/auto-reconnection, state transitions, and multiple restart cycles
+  - Test helpers and utilities for easy test development
+  - 900+ lines of documentation with quick-start guide and examples
+  - Run with: `bun test test/integration/` or `bun run test:integration`
 
 See [CHANGELOG.md](./CHANGELOG.md) for complete release notes.
 
@@ -200,11 +252,71 @@ job.on('failed', err => console.error(err));
 
 ## Testing
 
+### Unit and Integration Tests
+
 ```bash
-bun test                 # Unit + integration tests
-bun run test:real        # Real server tests (COMFY_REAL=1)
-bun run test:full        # Comprehensive tests (COMFY_FULL=1)
-bun run coverage         # Coverage report
+bun test                        # Unit + integration tests
+bun run test:integration        # Run all integration tests
+bun run test:integration:simple # Run simple reconnection examples
+bun run test:real               # Real server tests (COMFY_REAL=1)
+bun run test:full               # Comprehensive tests (COMFY_FULL=1)
+bun run coverage                # Coverage report
+```
+
+### Integration Tests (v1.6.5+)
+
+The library includes a comprehensive integration test infrastructure that spawns real mock server processes to test reconnection behavior:
+
+```bash
+# Run all integration tests
+bun test test/integration/
+
+# Run simple examples (recommended first)
+bun run test:integration:simple
+
+# Validate the mock server infrastructure
+bun test/integration/validate-mock-server.ts
+
+# Debug: Run mock server standalone
+bun test/integration/mock-server.ts 8191
+```
+
+**What's Tested:**
+- Manual and automatic reconnection after server crashes
+- Connection state transitions (connecting → connected → disconnected → reconnecting)
+- Event emission (`reconnected`, `reconnection_failed`)
+- Multiple server restart cycles
+- WebSocket message handling across reconnections
+
+**Documentation:**
+- `test/integration/README.md` – Comprehensive guide
+- `test/integration/QUICKSTART.md` – Developer quick-start with patterns
+- `test/integration/SUMMARY.md` – Architecture overview
+
+**Example:**
+```ts
+// Integration test pattern
+const manager = new ServerManager({ port: 8191 });
+await manager.startServer(8191);
+
+const api = new ComfyApi("http://localhost:8191");
+await initializeClient(api);
+
+// Kill server to simulate crash
+await manager.killServer(8191);
+await sleep(500);
+
+// Restart server
+await manager.startServer(8191);
+
+// Verify reconnection
+await api.reconnectWs(true);
+await waitForConnection(api);
+expect(api.isConnected()).toBe(true);
+
+// Cleanup
+api.destroy();
+await manager.killAll();
 ```
 
 See [Troubleshooting docs](./docs/troubleshooting.md#testing--coverage) for details.