@push.rocks/smartrust 1.2.1 → 1.3.1

package/readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartrust
 
-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.
+A type-safe, production-ready bridge between TypeScript and Rust binaries — with support for **stdio** (child process) and **socket** (Unix socket / Windows named pipe) transports, request/response, streaming, and event patterns.
 
 ## Issue Reporting and Security
 
@@ -16,25 +16,34 @@ pnpm install @push.rocks/smartrust
 
 ## Overview 🔭
 
-`@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.
+`@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 **or socket connection**, request/response correlation, **streaming responses**, event pub/sub, and graceful shutdown — so you can focus on your command definitions instead of IPC plumbing.
+
+### Two Transport Modes 🔌
+
+| Mode | Method | Use Case |
+|------|--------|----------|
+| **Stdio** | `bridge.spawn()` | Spawn the Rust binary as a child process. Communicate via stdin/stdout. |
+| **Socket** | `bridge.connect(path)` | Connect to an **already-running** Rust daemon via Unix socket or Windows named pipe. |
+
+The JSON protocol is identical in both modes — only the transport layer changes. Socket mode enables use cases where the Rust binary runs as a **privileged system service** (e.g., a VPN daemon needing root for TUN devices, a network proxy binding to privileged ports) while the TypeScript app connects to it unprivileged.
 
 ### 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
+- A way to **spawn it** or **connect to 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)
+- **Graceful lifecycle management** (ready detection, clean shutdown, auto-reconnection)
 
-`smartrust` wraps all of this into three classes: `RustBridge`, `RustBinaryLocator`, and `StreamingResponse`.
+`smartrust` wraps all of this into a clean API: `RustBridge`, `RustBinaryLocator`, `StreamingResponse`, and pluggable transports.
 
 ## Usage 🚀
 
 ### The IPC Protocol
 
-`smartrust` uses a simple, newline-delimited JSON protocol over stdin/stdout:
+`smartrust` uses a simple, newline-delimited JSON protocol:
 
 | Direction | Format | Description |
 |-----------|--------|-------------|
@@ -44,7 +53,7 @@ If you're integrating Rust into a Node.js project, you'll inevitably need:
 | **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.
+This protocol works identically over stdio and socket transports. Your Rust binary reads JSON lines from one end and writes JSON lines to the other. That's it.
 
 ### Defining Your Commands
 
@@ -62,7 +71,9 @@ type TMyCommands = {
 };
 ```
 
-### Creating and Using the Bridge
+### Stdio Mode — Spawn a Child Process
+
+This is the classic mode. The bridge spawns the Rust binary and communicates via stdin/stdout:
 
 ```typescript
 const bridge = new RustBridge<TMyCommands>({
@@ -90,10 +101,62 @@ bridge.on('management:configChanged', (data) => {
   console.log('Config was changed:', data);
 });
 
-// Clean shutdown
+// Clean shutdown (SIGTERM → SIGKILL after 5s)
+bridge.kill();
+```
+
+### Socket Mode — Connect to a Running Daemon 🔗
+
+When the Rust binary runs as a system service (e.g., via `systemd`, `launchd`, or a Windows Service), use `connect()` to talk to it over a Unix socket or named pipe:
+
+```typescript
+const bridge = new RustBridge<TMyCommands>({
+  binaryName: 'my-daemon',  // used for logging / error messages
+});
+
+// Connect to the daemon's management socket
+const ok = await bridge.connect('/var/run/my-daemon.sock');
+if (!ok) {
+  console.error('Failed to connect to daemon');
+  process.exit(1);
+}
+
+// Same API as stdio mode — completely transparent!
+const { pid } = await bridge.sendCommand('start', { port: 8080, host: '0.0.0.0' });
+const metrics = await bridge.sendCommand('getMetrics', {});
+
+// kill() closes the socket — it does NOT kill the daemon
 bridge.kill();
 ```
 
+#### Auto-Reconnect
+
+For long-running applications, enable automatic reconnection with exponential backoff:
+
+```typescript
+const ok = await bridge.connect('/var/run/my-daemon.sock', {
+  autoReconnect: true,          // reconnect on unexpected disconnect
+  reconnectBaseDelayMs: 100,    // initial retry delay (doubles each attempt)
+  reconnectMaxDelayMs: 30000,   // max retry delay cap
+  maxReconnectAttempts: 10,     // give up after 10 attempts
+});
+
+// Listen for reconnection events
+bridge.on('reconnected', () => {
+  console.log('Reconnected to daemon!');
+});
+```
+
+#### Platform Notes
+
+| Platform | Socket Path Format | Example |
+|----------|-------------------|---------|
+| **Linux** | `/var/run/<name>.sock` or `$XDG_RUNTIME_DIR/<name>.sock` | `/var/run/my-daemon.sock` |
+| **macOS** | `/var/run/<name>.sock` | `/var/run/my-daemon.sock` |
+| **Windows** | `\\.\pipe\<name>` | `\\.\pipe\my-daemon` |
+
+Node.js `net.connect()` handles all formats transparently — no platform-specific code needed.
+
 ### 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.
@@ -231,6 +294,17 @@ const bridge = new RustBridge<TMyCommands>({
 });
 ```
 
+Socket connection options (passed to `bridge.connect()`):
+
+```typescript
+interface ISocketConnectOptions {
+  autoReconnect?: boolean;         // default: false
+  reconnectBaseDelayMs?: number;   // default: 100
+  reconnectMaxDelayMs?: number;    // default: 30000
+  maxReconnectAttempts?: number;   // default: 10
+}
+```
+
 ### Events 📡
 
 `RustBridge` extends `EventEmitter` and emits the following events:
@@ -238,8 +312,9 @@ const bridge = new RustBridge<TMyCommands>({
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `ready` | — | Bridge connected and binary reported ready |
-| `exit` | `(code, signal)` | Rust process exited |
-| `stderr` | `string` | A line from the binary's stderr |
+| `exit` | `(code, signal)` | Transport closed (process exited or socket disconnected) |
+| `stderr` | `string` | A line from the binary's stderr (stdio mode only) |
+| `reconnected` | — | Socket transport reconnected after unexpected disconnect |
 | `management:<name>` | `any` | Custom event from Rust (e.g. `management:configChanged`) |
 
 ### Custom Logger 📝
@@ -263,7 +338,9 @@ const bridge = new RustBridge<TMyCommands>({
 
 ### Writing the Rust Side 🦀
 
-Your Rust binary needs to implement a simple protocol:
+Your Rust binary needs to implement a simple protocol. The transport (stdio or socket) doesn't change the message format — only how connections are established.
+
+#### Stdio Mode (Child Process)
 
 1. **On startup**, write a ready event to stdout:
    ```
@@ -280,7 +357,14 @@ Your Rust binary needs to implement a simple protocol:
 
 6. **Use stderr** for logging — it won't interfere with the IPC protocol
 
-Here's a minimal Rust skeleton:
+#### Socket Mode (Daemon)
+
+1. **Listen** on a Unix socket (e.g., `/var/run/my-daemon.sock`) or Windows named pipe
+2. **On each new client connection**, send the `{"event":"ready","data":{...}}\n` event
+3. Read/write JSON lines on the socket (same protocol as stdio)
+4. Support multiple concurrent clients — each connection is independent
+
+Here's a minimal Rust skeleton (stdio mode):
 
 ```rust
 use serde::{Deserialize, Serialize};
@@ -368,6 +452,33 @@ fn main() {
 }
 ```
 
+## Architecture 🏗️
+
+```
+┌──────────────────────────────────────────────────────┐
+│                    RustBridge<T>                      │
+│  (protocol layer: handleLine, sendCommand, events)   │
+├──────────────┬───────────────────────────────────────┤
+│ StdioTransport │         SocketTransport             │
+│  spawn() +     │   net.connect() + auto-reconnect    │
+│  stdin/stdout  │   Unix socket / named pipe          │
+├──────────────┴───────────────────────────────────────┤
+│               IRustTransport interface               │
+│         connect() / write() / disconnect()           │
+├──────────────────────────────────────────────────────┤
+│       LineScanner (shared newline scanner)            │
+├──────────────────────────────────────────────────────┤
+│              RustBinaryLocator                        │
+│  (binary search — stdio mode only)                   │
+└──────────────────────────────────────────────────────┘
+```
+
+- **`RustBridge`** — The main class. Protocol-level logic (JSON parsing, request correlation, streaming, events) is transport-agnostic.
+- **`StdioTransport`** — Spawns a child process, manages stdin/stdout/stderr, handles SIGTERM/SIGKILL.
+- **`SocketTransport`** — Connects to an existing Unix socket or named pipe, with optional auto-reconnect and exponential backoff.
+- **`LineScanner`** — Shared buffer-based newline scanner used by both transports for efficient message framing.
+- **`RustBinaryLocator`** — Priority-ordered binary search (used by stdio mode only).
+
 ## API Reference 📖
 
 ### `RustBridge<TCommands>`
@@ -375,11 +486,12 @@ fn main() {
 | Method / Property | Signature | Description |
 |---|---|---|
 | `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 |
+| `spawn()` | `Promise<boolean>` | **Stdio mode**: Spawn the binary and wait for ready; returns `false` on failure |
+| `connect(socketPath, options?)` | `Promise<boolean>` | **Socket mode**: Connect to a running daemon; 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 |
+| `kill()` | `void` | Stdio: SIGTERM the process, SIGKILL after 5s. Socket: close the connection (daemon stays alive) |
+| `running` | `boolean` | Whether the bridge is currently connected and ready |
 
 ### `StreamingResponse<TChunk, TResult>`
 
@@ -396,13 +508,43 @@ 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 |
 
+### `StdioTransport`
+
+| Method / Property | Signature | Description |
+|---|---|---|
+| `constructor` | `new StdioTransport(options: IStdioTransportOptions)` | Create a stdio transport |
+| `connect()` | `Promise<void>` | Spawn the child process |
+| `write(data)` | `Promise<void>` | Write to stdin with backpressure handling |
+| `disconnect()` | `void` | Kill the process (SIGTERM → SIGKILL after 5s) |
+| `connected` | `boolean` | Whether the process is running |
+
+### `SocketTransport`
+
+| Method / Property | Signature | Description |
+|---|---|---|
+| `constructor` | `new SocketTransport(options: ISocketTransportOptions)` | Create a socket transport |
+| `connect()` | `Promise<void>` | Connect to the Unix socket / named pipe |
+| `write(data)` | `Promise<void>` | Write to socket with backpressure handling |
+| `disconnect()` | `void` | Close the socket (does not kill the daemon) |
+| `connected` | `boolean` | Whether the socket is connected |
+
+### `LineScanner`
+
+| Method / Property | Signature | Description |
+|---|---|---|
+| `constructor` | `new LineScanner(maxPayloadSize, logger)` | Create a line scanner |
+| `push(chunk, onLine)` | `void` | Feed a `Buffer` chunk; calls `onLine` for each complete line |
+| `clear()` | `void` | Reset the internal buffer |
+
 ### Exported Interfaces & Types
 
 | Interface / Type | Description |
 |---|---|
 | `IRustBridgeOptions` | Full configuration for `RustBridge` |
 | `IBinaryLocatorOptions` | Configuration for `RustBinaryLocator` |
+| `ISocketConnectOptions` | Socket connection options (reconnect settings) |
 | `IRustBridgeLogger` | Logger interface: `{ log(level, message, data?) }` |
+| `IRustTransport` | Transport interface (extends `EventEmitter`) |
 | `IManagementRequest` | IPC request shape: `{ id, method, params }` |
 | `IManagementResponse` | IPC response shape: `{ id, success, result?, error? }` |
 | `IManagementEvent` | IPC event shape: `{ event, data }` |

package/test/helpers/mock-socket-server.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+/**
+ * Mock "Rust daemon" for testing the SocketTransport and RustBridge socket mode.
+ * Creates a Unix socket server, accepts connections, and speaks the same
+ * JSON-over-newline IPC protocol as mock-rust-binary.mjs.
+ *
+ * Usage: node mock-socket-server.mjs <socket-path>
+ * Signals readiness by writing a JSON line to stdout: {"socketPath":"...","ready":true}
+ */
+
+import * as net from 'net';
+import * as fs from 'fs';
+
+const socketPath = process.argv[2];
+if (!socketPath) {
+  process.stderr.write('Usage: mock-socket-server.mjs <socket-path>\n');
+  process.exit(1);
+}
+
+// Remove stale socket file
+try { fs.unlinkSync(socketPath); } catch { /* ignore */ }
+
+/**
+ * Backpressure-aware write to a socket.
+ */
+function writeResponse(conn, data) {
+  const json = JSON.stringify(data) + '\n';
+  if (!conn.write(json)) {
+    conn.once('drain', () => {});
+  }
+}
+
+function handleLine(line, conn) {
+  let request;
+  try {
+    request = JSON.parse(line);
+  } catch {
+    return;
+  }
+
+  const { id, method, params } = request;
+
+  if (method === 'echo') {
+    writeResponse(conn, { id, success: true, result: params });
+  } else if (method === 'largeEcho') {
+    writeResponse(conn, { id, success: true, result: params });
+  } else if (method === 'error') {
+    writeResponse(conn, { id, success: false, error: 'Test error message' });
+  } else if (method === 'emitEvent') {
+    writeResponse(conn, { event: params.eventName, data: params.eventData });
+    writeResponse(conn, { id, success: true, result: null });
+  } else if (method === 'slow') {
+    setTimeout(() => {
+      writeResponse(conn, { id, success: true, result: { delayed: true } });
+    }, 100);
+  } else if (method === 'streamEcho') {
+    const count = params.count || 0;
+    let sent = 0;
+    const interval = setInterval(() => {
+      if (sent < count) {
+        writeResponse(conn, { id, stream: true, data: { index: sent, value: `chunk_${sent}` } });
+        sent++;
+      } else {
+        clearInterval(interval);
+        writeResponse(conn, { id, success: true, result: { totalChunks: count } });
+      }
+    }, 10);
+  } else if (method === 'streamError') {
+    writeResponse(conn, { id, stream: true, data: { index: 0, value: 'before_error' } });
+    setTimeout(() => {
+      writeResponse(conn, { id, success: false, error: 'Stream error after chunk' });
+    }, 20);
+  } else if (method === 'streamEmpty') {
+    writeResponse(conn, { id, success: true, result: { totalChunks: 0 } });
+  } else if (method === 'exit') {
+    writeResponse(conn, { id, success: true, result: null });
+    // In socket mode, 'exit' just closes this connection, not the server
+    setTimeout(() => conn.end(), 50);
+  } else {
+    writeResponse(conn, { id, success: false, error: `Unknown method: ${method}` });
+  }
+}
+
+const server = net.createServer((conn) => {
+  // Send ready event on each new connection
+  writeResponse(conn, { event: 'ready', data: { version: '1.0.0' } });
+
+  // Buffer-based newline scanner for incoming data
+  let buffer = Buffer.alloc(0);
+  conn.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    let idx;
+    while ((idx = buffer.indexOf(0x0A)) !== -1) {
+      const lineBuffer = buffer.subarray(0, idx);
+      buffer = buffer.subarray(idx + 1);
+      const line = lineBuffer.toString('utf8').trim();
+      if (line) {
+        handleLine(line, conn);
+      }
+    }
+  });
+
+  conn.on('error', () => { /* ignore client errors */ });
+});
+
+server.listen(socketPath, () => {
+  // Signal to parent that the server is ready
+  process.stdout.write(JSON.stringify({ socketPath, ready: true }) + '\n');
+});
+
+// Handle SIGTERM gracefully
+process.on('SIGTERM', () => {
+  server.close();
+  try { fs.unlinkSync(socketPath); } catch { /* ignore */ }
+  process.exit(0);
+});
+
+// Handle SIGINT
+process.on('SIGINT', () => {
+  server.close();
+  try { fs.unlinkSync(socketPath); } catch { /* ignore */ }
+  process.exit(0);
+});

package/test/test.linescanner.node.ts

@@ -0,0 +1,89 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { LineScanner } from '../ts/classes.linescanner.js';
+
+const noopLogger = { log() {} };
+
+tap.test('should parse a single complete line', async () => {
+  const scanner = new LineScanner(1024 * 1024, noopLogger);
+  const lines: string[] = [];
+  scanner.push(Buffer.from('{"hello":"world"}\n'), (line) => lines.push(line));
+  expect(lines.length).toEqual(1);
+  expect(lines[0]).toEqual('{"hello":"world"}');
+});
+
+tap.test('should parse multiple lines in one chunk', async () => {
+  const scanner = new LineScanner(1024 * 1024, noopLogger);
+  const lines: string[] = [];
+  scanner.push(Buffer.from('{"a":1}\n{"b":2}\n{"c":3}\n'), (line) => lines.push(line));
+  expect(lines.length).toEqual(3);
+  expect(lines[0]).toEqual('{"a":1}');
+  expect(lines[1]).toEqual('{"b":2}');
+  expect(lines[2]).toEqual('{"c":3}');
+});
+
+tap.test('should handle a line split across chunks', async () => {
+  const scanner = new LineScanner(1024 * 1024, noopLogger);
+  const lines: string[] = [];
+  scanner.push(Buffer.from('{"hel'), (line) => lines.push(line));
+  expect(lines.length).toEqual(0);
+  scanner.push(Buffer.from('lo":"world"}\n'), (line) => lines.push(line));
+  expect(lines.length).toEqual(1);
+  expect(lines[0]).toEqual('{"hello":"world"}');
+});
+
+tap.test('should drop oversized lines', async () => {
+  const scanner = new LineScanner(100, noopLogger);
+  const lines: string[] = [];
+  // Line is 200 chars + newline, exceeds maxPayloadSize of 100
+  const oversized = 'x'.repeat(200) + '\n';
+  scanner.push(Buffer.from(oversized), (line) => lines.push(line));
+  expect(lines.length).toEqual(0);
+});
+
+tap.test('should clear buffer on OOM (no newline, exceeds max)', async () => {
+  const scanner = new LineScanner(100, noopLogger);
+  const lines: string[] = [];
+  // Push 200 bytes without any newline — exceeds maxPayloadSize
+  scanner.push(Buffer.from('x'.repeat(200)), (line) => lines.push(line));
+  expect(lines.length).toEqual(0);
+  // After clearing, should work normally again
+  scanner.push(Buffer.from('{"ok":true}\n'), (line) => lines.push(line));
+  expect(lines.length).toEqual(1);
+  expect(lines[0]).toEqual('{"ok":true}');
+});
+
+tap.test('should skip empty lines', async () => {
+  const scanner = new LineScanner(1024 * 1024, noopLogger);
+  const lines: string[] = [];
+  scanner.push(Buffer.from('\n\n{"a":1}\n\n'), (line) => lines.push(line));
+  expect(lines.length).toEqual(1);
+  expect(lines[0]).toEqual('{"a":1}');
+});
+
+tap.test('should handle mixed complete and partial lines', async () => {
+  const scanner = new LineScanner(1024 * 1024, noopLogger);
+  const lines: string[] = [];
+  // First chunk: one complete line + start of second line
+  scanner.push(Buffer.from('{"first":1}\n{"sec'), (line) => lines.push(line));
+  expect(lines.length).toEqual(1);
+  // Second chunk: end of second line + complete third line
+  scanner.push(Buffer.from('ond":2}\n{"third":3}\n'), (line) => lines.push(line));
+  expect(lines.length).toEqual(3);
+  expect(lines[1]).toEqual('{"second":2}');
+  expect(lines[2]).toEqual('{"third":3}');
+});
+
+tap.test('clear should reset the buffer', async () => {
+  const scanner = new LineScanner(1024 * 1024, noopLogger);
+  const lines: string[] = [];
+  // Push partial data
+  scanner.push(Buffer.from('{"partial":'), (line) => lines.push(line));
+  // Clear
+  scanner.clear();
+  // Now push a complete new line — old partial should not affect it
+  scanner.push(Buffer.from('{"fresh":true}\n'), (line) => lines.push(line));
+  expect(lines.length).toEqual(1);
+  expect(lines[0]).toEqual('{"fresh":true}');
+});
+
+export default tap.start();