@push.rocks/smartrust 1.1.1 → 1.2.0

package/dist_ts/plugins.js

@@ -2,10 +2,10 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import * as childProcess from 'child_process';
-import * as readline from 'readline';
 import * as events from 'events';
-export { path, fs, childProcess, readline, events };
+import * as url from 'url';
+export { path, fs, childProcess, events, url };
 // @push.rocks scope
 import * as smartpath from '@push.rocks/smartpath';
 export { smartpath };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsZUFBZTtBQUNmLE9BQU8sS0FBSyxJQUFJLE1BQU0sTUFBTSxDQUFDO0FBQzdCLE9BQU8sS0FBSyxFQUFFLE1BQU0sSUFBSSxDQUFDO0FBQ3pCLE9BQU8sS0FBSyxZQUFZLE1BQU0sZUFBZSxDQUFDO0FBQzlDLE9BQU8sS0FBSyxRQUFRLE1BQU0sVUFBVSxDQUFDO0FBQ3JDLE9BQU8sS0FBSyxNQUFNLE1BQU0sUUFBUSxDQUFDO0FBRWpDLE9BQU8sRUFBRSxJQUFJLEVBQUUsRUFBRSxFQUFFLFlBQVksRUFBRSxRQUFRLEVBQUUsTUFBTSxFQUFFLENBQUM7QUFFcEQsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxTQUFTLE1BQU0sdUJBQXVCLENBQUM7QUFFbkQsT0FBTyxFQUFFLFNBQVMsRUFBRSxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsZUFBZTtBQUNmLE9BQU8sS0FBSyxJQUFJLE1BQU0sTUFBTSxDQUFDO0FBQzdCLE9BQU8sS0FBSyxFQUFFLE1BQU0sSUFBSSxDQUFDO0FBQ3pCLE9BQU8sS0FBSyxZQUFZLE1BQU0sZUFBZSxDQUFDO0FBQzlDLE9BQU8sS0FBSyxNQUFNLE1BQU0sUUFBUSxDQUFDO0FBQ2pDLE9BQU8sS0FBSyxHQUFHLE1BQU0sS0FBSyxDQUFDO0FBRTNCLE9BQU8sRUFBRSxJQUFJLEVBQUUsRUFBRSxFQUFFLFlBQVksRUFBRSxNQUFNLEVBQUUsR0FBRyxFQUFFLENBQUM7QUFFL0Msb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxTQUFTLE1BQU0sdUJBQXVCLENBQUM7QUFFbkQsT0FBTyxFQUFFLFNBQVMsRUFBRSxDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartrust",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "private": false,
   "description": "a bridge between JS engines and rust",
   "main": "dist_ts/index.js",

package/readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartrust
 
-A type-safe, standardized bridge between TypeScript and Rust binaries via JSON-over-stdin/stdout IPC.
+A type-safe, production-ready bridge between TypeScript and Rust binaries via JSON-over-stdin/stdout IPC — with support for request/response, streaming, and event patterns.
 
 ## Issue Reporting and Security
 
@@ -16,18 +16,19 @@ pnpm install @push.rocks/smartrust
 
 ## Overview 🔭
 
-`@push.rocks/smartrust` provides a production-ready bridge for TypeScript applications that need to communicate with Rust binaries. It handles the entire lifecycle — binary discovery, process spawning, request/response correlation with timeouts, event streaming, and graceful shutdown — so you can focus on your command definitions instead of IPC plumbing.
+`@push.rocks/smartrust` provides a complete bridge for TypeScript applications that need to communicate with Rust binaries. It handles the entire lifecycle — binary discovery, process spawning, request/response correlation, **streaming responses**, event pub/sub, and graceful shutdown — so you can focus on your command definitions instead of IPC plumbing.
 
-### Why?
+### Why? 🤔
 
 If you're integrating Rust into a Node.js project, you'll inevitably need:
 - A way to **find** the compiled Rust binary across different environments (dev, CI, production, platform packages)
 - A way to **spawn** it and establish reliable two-way communication
 - **Type-safe** request/response patterns with proper error handling
+- **Streaming responses** for progressive data processing, log tailing, or chunked transfers
 - **Event streaming** from Rust to TypeScript
 - **Graceful lifecycle management** (ready detection, clean shutdown, force kill)
 
-`smartrust` wraps all of this into two classes: `RustBridge` and `RustBinaryLocator`.
+`smartrust` wraps all of this into three classes: `RustBridge`, `RustBinaryLocator`, and `StreamingResponse`.
 
 ## Usage 🚀
 
@@ -38,8 +39,9 @@ If you're integrating Rust into a Node.js project, you'll inevitably need:
 | Direction | Format | Description |
 |-----------|--------|-------------|
 | **TS → Rust** (Request) | `{"id": "req_1", "method": "start", "params": {...}}` | Command with unique ID |
-| **Rust → TS** (Response) | `{"id": "req_1", "success": true, "result": {...}}` | Response correlated by ID |
+| **Rust → TS** (Response) | `{"id": "req_1", "success": true, "result": {...}}` | Final response correlated by ID |
 | **Rust → TS** (Error) | `{"id": "req_1", "success": false, "error": "msg"}` | Error correlated by ID |
+| **Rust → TS** (Stream Chunk) | `{"id": "req_1", "stream": true, "data": {...}}` | Intermediate chunk (zero or more) |
 | **Rust → TS** (Event) | `{"event": "ready", "data": {...}}` | Unsolicited event (no ID) |
 
 Your Rust binary reads JSON lines from stdin and writes JSON lines to stdout. That's it. Stderr is free for logging.
@@ -49,7 +51,7 @@ Your Rust binary reads JSON lines from stdin and writes JSON lines to stdout. Th
 Start by defining a type map of commands your Rust binary supports:
 
 ```typescript
-import { RustBridge, type ICommandDefinition } from '@push.rocks/smartrust';
+import { RustBridge } from '@push.rocks/smartrust';
 
 // Define your command types
 type TMyCommands = {
@@ -92,7 +94,91 @@ bridge.on('management:configChanged', (data) => {
 bridge.kill();
 ```
 
-### Binary Locator
+### Streaming Commands 🌊
+
+For commands where the Rust binary sends a series of chunks before a final result, use `sendCommandStreaming`. This is perfect for progressive data processing, log tailing, search results, or any scenario where you want incremental output.
+
+#### Defining Streaming Commands
+
+Add a `chunk` field to your command type definition to mark it as streamable:
+
+```typescript
+type TMyCommands = {
+  // Regular command (request → response)
+  ping:        { params: {}; result: { pong: boolean } };
+
+  // Streaming command (request → chunks... → final result)
+  processData: { params: { count: number }; chunk: { index: number; progress: number }; result: { totalProcessed: number } };
+  tailLogs:    { params: { lines: number }; chunk: string; result: { linesRead: number } };
+};
+```
+
+#### Consuming Streams
+
+```typescript
+// Returns a StreamingResponse immediately (does NOT block)
+const stream = bridge.sendCommandStreaming('processData', { count: 1000 });
+
+// Consume chunks with for-await-of
+for await (const chunk of stream) {
+  console.log(`Processing item ${chunk.index}, progress: ${chunk.progress}%`);
+}
+
+// Get the final result after all chunks are consumed
+const result = await stream.result;
+console.log(`Done! Processed ${result.totalProcessed} items`);
+```
+
+#### Error Handling in Streams
+
+Errors propagate to both the iterator and the `.result` promise:
+
+```typescript
+const stream = bridge.sendCommandStreaming('processData', { count: 100 });
+
+try {
+  for await (const chunk of stream) {
+    console.log(chunk);
+  }
+} catch (err) {
+  console.error('Stream failed:', err.message);
+}
+
+// .result also rejects on error
+try {
+  await stream.result;
+} catch (err) {
+  console.error('Same error here:', err.message);
+}
+```
+
+#### Stream Timeout
+
+By default, streaming commands use the same timeout as regular commands (`requestTimeoutMs`). The timeout **resets on each chunk received**, so it acts as an inactivity timeout rather than an absolute timeout. You can configure it separately:
+
+```typescript
+const bridge = new RustBridge<TMyCommands>({
+  binaryName: 'my-server',
+  requestTimeoutMs: 30000,   // regular command timeout: 30s
+  streamTimeoutMs: 60000,    // streaming inactivity timeout: 60s
+});
+```
+
+#### Implementing Streaming on the Rust Side
+
+Your Rust binary sends stream chunks by writing lines with `"stream": true` before the final response:
+
+```rust
+// For each chunk:
+println!(r#"{{"id":"{}","stream":true,"data":{{"index":{},"progress":{}}}}}"#, req.id, i, pct);
+io::stdout().flush().unwrap();
+
+// When done, send the final response (same as non-streaming):
+println!(r#"{{"id":"{}","success":true,"result":{{"totalProcessed":{}}}}}"#, req.id, total);
+io::stdout().flush().unwrap();
+```
+
+### Binary Locator 🔍
 
 The `RustBinaryLocator` searches for your binary using a priority-ordered strategy:
 
@@ -119,7 +205,7 @@ const binaryPath = await locator.findBinary();
 // Result is cached — call clearCache() to force re-search
 ```
 
-### Configuration Reference
+### Configuration Reference ⚙️
 
 The `RustBridge` constructor accepts an `IRustBridgeOptions` object:
 
@@ -136,14 +222,16 @@ const bridge = new RustBridge<TMyCommands>({
   // --- Bridge Options ---
   cliArgs: ['--management'],                  // optional: args passed to binary (default: ['--management'])
   requestTimeoutMs: 30000,                    // optional: per-request timeout (default: 30000)
+  streamTimeoutMs: 30000,                     // optional: streaming inactivity timeout (default: requestTimeoutMs)
   readyTimeoutMs: 10000,                      // optional: ready event timeout (default: 10000)
+  maxPayloadSize: 50 * 1024 * 1024,           // optional: max message size in bytes (default: 50MB)
   env: { RUST_LOG: 'debug' },                 // optional: extra env vars for the child process
   readyEventName: 'ready',                    // optional: name of the ready event (default: 'ready')
   logger: myLogger,                           // optional: logger implementing IRustBridgeLogger
 });
 ```
 
-### Events
+### Events 📡
 
 `RustBridge` extends `EventEmitter` and emits the following events:
 
@@ -154,7 +242,7 @@ const bridge = new RustBridge<TMyCommands>({
 | `stderr` | `string` | A line from the binary's stderr |
 | `management:<name>` | `any` | Custom event from Rust (e.g. `management:configChanged`) |
 
-### Custom Logger
+### Custom Logger 📝
 
 Plug in your own logger by implementing the `IRustBridgeLogger` interface:
 
@@ -173,7 +261,7 @@ const bridge = new RustBridge<TMyCommands>({
 });
 ```
 
-### Writing the Rust Side
+### Writing the Rust Side 🦀
 
 Your Rust binary needs to implement a simple protocol:
 
@@ -186,9 +274,11 @@ Your Rust binary needs to implement a simple protocol:
 
 3. **Write JSON responses to stdout**, each as `{"id": "...", "success": true, "result": {...}}\n`
 
-4. **Emit events** anytime by writing `{"event": "name", "data": {...}}\n` to stdout
+4. **For streaming commands**, write zero or more `{"id": "...", "stream": true, "data": {...}}\n` chunks before the final response
 
-5. **Use stderr** for logging — it won't interfere with the IPC protocol
+5. **Emit events** anytime by writing `{"event": "name", "data": {...}}\n` to stdout
+
+6. **Use stderr** for logging — it won't interfere with the IPC protocol
 
 Here's a minimal Rust skeleton:
 
@@ -213,6 +303,13 @@ struct Response {
     error: Option<String>,
 }
 
+#[derive(Serialize)]
+struct StreamChunk {
+    id: String,
+    stream: bool,
+    data: serde_json::Value,
+}
+
 fn main() {
     // Signal ready
     println!(r#"{{"event":"ready","data":{{"version":"1.0.0"}}}}"#);
@@ -223,24 +320,50 @@ fn main() {
         let line = line.unwrap();
         let req: Request = serde_json::from_str(&line).unwrap();
 
-        let response = match req.method.as_str() {
-            "ping" => Response {
-                id: req.id,
-                success: true,
-                result: Some(serde_json::json!({"pong": true})),
-                error: None,
-            },
-            _ => Response {
-                id: req.id,
-                success: false,
-                result: None,
-                error: Some(format!("Unknown method: {}", req.method)),
-            },
-        };
-
-        let json = serde_json::to_string(&response).unwrap();
-        println!("{json}");
-        io::stdout().flush().unwrap();
+        match req.method.as_str() {
+            "ping" => {
+                let resp = Response {
+                    id: req.id,
+                    success: true,
+                    result: Some(serde_json::json!({"pong": true})),
+                    error: None,
+                };
+                println!("{}", serde_json::to_string(&resp).unwrap());
+                io::stdout().flush().unwrap();
+            }
+            "processData" => {
+                let count = req.params["count"].as_u64().unwrap_or(0);
+                // Send stream chunks
+                for i in 0..count {
+                    let chunk = StreamChunk {
+                        id: req.id.clone(),
+                        stream: true,
+                        data: serde_json::json!({"index": i, "progress": ((i+1) * 100 / count)}),
+                    };
+                    println!("{}", serde_json::to_string(&chunk).unwrap());
+                    io::stdout().flush().unwrap();
+                }
+                // Send final response
+                let resp = Response {
+                    id: req.id,
+                    success: true,
+                    result: Some(serde_json::json!({"totalProcessed": count})),
+                    error: None,
+                };
+                println!("{}", serde_json::to_string(&resp).unwrap());
+                io::stdout().flush().unwrap();
+            }
+            _ => {
+                let resp = Response {
+                    id: req.id,
+                    success: false,
+                    result: None,
+                    error: Some(format!("Unknown method: {}", req.method)),
+                };
+                println!("{}", serde_json::to_string(&resp).unwrap());
+                io::stdout().flush().unwrap();
+            }
+        }
     }
 }
 ```
@@ -254,9 +377,17 @@ fn main() {
 | `constructor` | `new RustBridge<T>(options: IRustBridgeOptions)` | Create a new bridge instance |
 | `spawn()` | `Promise<boolean>` | Spawn the binary and wait for ready; returns `false` on failure |
 | `sendCommand(method, params)` | `Promise<TCommands[K]['result']>` | Send a typed command and await the response |
+| `sendCommandStreaming(method, params)` | `StreamingResponse<TChunk, TResult>` | Send a streaming command; returns immediately |
 | `kill()` | `void` | SIGTERM the process, reject pending requests, force SIGKILL after 5s |
 | `running` | `boolean` | Whether the bridge is currently connected |
 
+### `StreamingResponse<TChunk, TResult>`
+
+| Method / Property | Type | Description |
+|---|---|---|
+| `[Symbol.asyncIterator]()` | `AsyncIterator<TChunk>` | Enables `for await...of` consumption of chunks |
+| `result` | `Promise<TResult>` | Resolves with the final result after stream ends |
+
 ### `RustBinaryLocator`
 
 | Method / Property | Signature | Description |
@@ -265,9 +396,9 @@ fn main() {
 | `findBinary()` | `Promise<string \| null>` | Find the binary using the priority search; result is cached |
 | `clearCache()` | `void` | Clear the cached path to force a fresh search |
 
-### Exported Interfaces
+### Exported Interfaces & Types
 
-| Interface | Description |
+| Interface / Type | Description |
 |---|---|
 | `IRustBridgeOptions` | Full configuration for `RustBridge` |
 | `IBinaryLocatorOptions` | Configuration for `RustBinaryLocator` |
@@ -275,8 +406,11 @@ fn main() {
 | `IManagementRequest` | IPC request shape: `{ id, method, params }` |
 | `IManagementResponse` | IPC response shape: `{ id, success, result?, error? }` |
 | `IManagementEvent` | IPC event shape: `{ event, data }` |
+| `IManagementStreamChunk` | IPC stream chunk shape: `{ id, stream: true, data }` |
 | `ICommandDefinition` | Single command definition: `{ params, result }` |
 | `TCommandMap` | `Record<string, ICommandDefinition>` |
+| `TStreamingCommandKeys<T>` | Extracts keys from a command map that have a `chunk` field |
+| `TExtractChunk<T>` | Extracts the chunk type from a streaming command definition |
 
 ## License and Legal Information
 

package/test/helpers/mock-rust-binary.mjs

@@ -2,22 +2,46 @@
 
 /**
  * Mock "Rust binary" for testing the RustBridge IPC protocol.
- * Reads JSON lines from stdin, writes JSON lines to stdout.
+ * Reads JSON lines from stdin via Buffer-based scanner, writes JSON lines to stdout.
  * Emits a ready event on startup.
  */
 
-import { createInterface } from 'readline';
-
 // Emit ready event
 const readyEvent = JSON.stringify({ event: 'ready', data: { version: '1.0.0' } });
 process.stdout.write(readyEvent + '\n');
 
-const rl = createInterface({ input: process.stdin });
+// Buffer-based newline scanner for stdin (mirrors the RustBridge approach)
+let stdinBuffer = Buffer.alloc(0);
+
+process.stdin.on('data', (chunk) => {
+  stdinBuffer = Buffer.concat([stdinBuffer, chunk]);
+
+  let newlineIndex;
+  while ((newlineIndex = stdinBuffer.indexOf(0x0A)) !== -1) {
+    const lineBuffer = stdinBuffer.subarray(0, newlineIndex);
+    stdinBuffer = stdinBuffer.subarray(newlineIndex + 1);
+    const line = lineBuffer.toString('utf8').trim();
+    if (line) {
+      handleLine(line);
+    }
+  }
+});
 
-rl.on('line', (line) => {
+/**
+ * Backpressure-aware write to stdout.
+ */
+function writeResponse(data) {
+  const json = JSON.stringify(data) + '\n';
+  if (!process.stdout.write(json)) {
+    // Wait for drain before continuing
+    process.stdout.once('drain', () => {});
+  }
+}
+
+function handleLine(line) {
   let request;
   try {
-    request = JSON.parse(line.trim());
+    request = JSON.parse(line);
   } catch {
     return;
   }
@@ -26,35 +50,53 @@ rl.on('line', (line) => {
 
   if (method === 'echo') {
     // Echo back the params as result
-    const response = JSON.stringify({ id, success: true, result: params });
-    process.stdout.write(response + '\n');
+    writeResponse({ id, success: true, result: params });
+  } else if (method === 'largeEcho') {
+    // Echo back params (same as echo, named distinctly for large payload tests)
+    writeResponse({ id, success: true, result: params });
   } else if (method === 'error') {
     // Return an error
-    const response = JSON.stringify({ id, success: false, error: 'Test error message' });
-    process.stdout.write(response + '\n');
+    writeResponse({ id, success: false, error: 'Test error message' });
   } else if (method === 'emitEvent') {
     // Emit a custom event, then respond with success
-    const event = JSON.stringify({ event: params.eventName, data: params.eventData });
-    process.stdout.write(event + '\n');
-    const response = JSON.stringify({ id, success: true, result: null });
-    process.stdout.write(response + '\n');
+    writeResponse({ event: params.eventName, data: params.eventData });
+    writeResponse({ id, success: true, result: null });
   } else if (method === 'slow') {
     // Respond after a delay
     setTimeout(() => {
-      const response = JSON.stringify({ id, success: true, result: { delayed: true } });
-      process.stdout.write(response + '\n');
+      writeResponse({ id, success: true, result: { delayed: true } });
     }, 100);
+  } else if (method === 'streamEcho') {
+    // Send params.count stream chunks, then final response
+    const count = params.count || 0;
+    let sent = 0;
+    const interval = setInterval(() => {
+      if (sent < count) {
+        writeResponse({ id, stream: true, data: { index: sent, value: `chunk_${sent}` } });
+        sent++;
+      } else {
+        clearInterval(interval);
+        writeResponse({ id, success: true, result: { totalChunks: count } });
+      }
+    }, 10);
+  } else if (method === 'streamError') {
+    // Send 1 chunk, then error
+    writeResponse({ id, stream: true, data: { index: 0, value: 'before_error' } });
+    setTimeout(() => {
+      writeResponse({ id, success: false, error: 'Stream error after chunk' });
+    }, 20);
+  } else if (method === 'streamEmpty') {
+    // Zero chunks, immediate final response
+    writeResponse({ id, success: true, result: { totalChunks: 0 } });
   } else if (method === 'exit') {
     // Graceful exit
-    const response = JSON.stringify({ id, success: true, result: null });
-    process.stdout.write(response + '\n');
+    writeResponse({ id, success: true, result: null });
     process.exit(0);
   } else {
     // Unknown command
-    const response = JSON.stringify({ id, success: false, error: `Unknown method: ${method}` });
-    process.stdout.write(response + '\n');
+    writeResponse({ id, success: false, error: `Unknown method: ${method}` });
   }
-});
+}
 
 // Handle SIGTERM gracefully
 process.on('SIGTERM', () => {