@push.rocks/smartrust 2.5.0 → 2.6.0

package/ts/classes.linescanner.ts

@@ -4,9 +4,16 @@ import type { IRustBridgeLogger } from './interfaces/index.js';
  * Buffer-based newline scanner for streaming binary data.
  * Accumulates chunks and emits complete lines via callback.
  * Used by both StdioTransport and SocketTransport.
+ *
+ * Each byte is scanned once and copied at most once into its line, so a line that arrives in many
+ * chunks costs time linear in its length.
  */
 export class LineScanner {
-  private buffer: Buffer = Buffer.alloc(0);
+  /** Chunks of the line being received; none of them contains a newline. */
+  private pending: Buffer[] = [];
+  private pendingLength = 0;
+  /** Bytes after a line whose callback threw; they may contain newlines and are scanned first. */
+  private unscanned: Buffer = Buffer.alloc(0);
   private maxPayloadSize: number;
   private logger: IRustBridgeLogger;
 
@@ -19,44 +26,74 @@ export class LineScanner {
    * Feed a chunk of data. Calls onLine for each complete newline-terminated line found.
    */
   public push(chunk: Buffer, onLine: (line: string) => void): void {
-    this.buffer = Buffer.concat([this.buffer, chunk]);
+    const input = this.unscanned.length > 0 ? Buffer.concat([this.unscanned, chunk]) : chunk;
+    this.unscanned = Buffer.alloc(0);
+    let start = 0;
 
     try {
       let newlineIndex: number;
-      while ((newlineIndex = this.buffer.indexOf(0x0A)) !== -1) {
-        const lineBuffer = this.buffer.subarray(0, newlineIndex);
-        this.buffer = this.buffer.subarray(newlineIndex + 1);
-
-        if (lineBuffer.length > this.maxPayloadSize) {
-          this.logger.log('error', `Inbound message exceeds maxPayloadSize (${lineBuffer.length} bytes), dropping`);
+      while ((newlineIndex = input.indexOf(0x0A, start)) !== -1) {
+        const lineBuffer = this.takeLine(input.subarray(start, newlineIndex));
+        start = newlineIndex + 1;
+        if (!lineBuffer) {
           continue;
         }
-
         const line = lineBuffer.toString('utf8').trim();
         if (line) {
           onLine(line);
         }
       }
-
-      // Prevent OOM if sender never sends newline
-      if (this.buffer.length > this.maxPayloadSize) {
-        this.logger.log('error', `Buffer exceeded maxPayloadSize (${this.buffer.length} bytes) without newline, clearing`);
-        this.buffer = Buffer.alloc(0);
-      }
-    } finally {
-      // A subarray retains its entire backing allocation, even when empty.
-      // Compact once per chunk, including when a callback throws, without
-      // repeatedly copying the unread suffix for each parsed line.
-      if (this.buffer.length === 0) {
-        this.buffer = Buffer.alloc(0);
-      } else if (this.buffer.buffer.byteLength > Math.max(Buffer.poolSize, this.buffer.length * 2)) {
-        this.buffer = Buffer.from(this.buffer);
-      }
+      this.appendPartial(input.subarray(start));
+    } catch (error) {
+      // Keep what follows the failed line for the next push, without retaining what was consumed.
+      this.unscanned = LineScanner.compact(input.subarray(start));
+      throw error;
     }
   }
 
   /** Reset the internal buffer. */
   public clear(): void {
-    this.buffer = Buffer.alloc(0);
+    this.pending = [];
+    this.pendingLength = 0;
+    this.unscanned = Buffer.alloc(0);
+  }
+
+  /** Joins the pending chunks with the line's last piece; null when the line is too large. */
+  private takeLine(tail: Buffer): Buffer | null {
+    const length = this.pendingLength + tail.length;
+    const pending = this.pending;
+    this.pending = [];
+    this.pendingLength = 0;
+    if (length > this.maxPayloadSize) {
+      this.logger.log('error', `Inbound message exceeds maxPayloadSize (${length} bytes), dropping`);
+      return null;
+    }
+    return pending.length === 0 ? tail : Buffer.concat([...pending, tail], length);
+  }
+
+  private appendPartial(partial: Buffer): void {
+    if (partial.length === 0) {
+      return;
+    }
+    // Prevent OOM if sender never sends newline
+    if (this.pendingLength + partial.length > this.maxPayloadSize) {
+      this.logger.log(
+        'error',
+        `Buffer exceeded maxPayloadSize (${this.pendingLength + partial.length} bytes) without newline, clearing`,
+      );
+      this.pending = [];
+      this.pendingLength = 0;
+      return;
+    }
+    this.pending.push(LineScanner.compact(partial));
+    this.pendingLength += partial.length;
+  }
+
+  /** A subarray retains its entire backing allocation; copy a small piece of a large one. */
+  private static compact(piece: Buffer): Buffer {
+    if (piece.length === 0) {
+      return Buffer.alloc(0);
+    }
+    return piece.buffer.byteLength > Math.max(Buffer.poolSize, piece.length * 2) ? Buffer.from(piece) : piece;
   }
 }

package/ts/classes.rustbinarylocator.ts

@@ -10,9 +10,11 @@ const defaultLogger: IRustBridgeLogger = {
  * Locates a Rust binary using a priority-ordered search strategy:
  * 1. Explicit binaryPath override
  * 2. Environment variable
- * 3. Platform-specific npm package
- * 4. Local development build paths
- * 5. System PATH
+ * 3. Inside a Node.js single executable application: the sidecar embedded under `binaryName`,
+ *    and nothing else
+ * 4. Platform-specific npm package
+ * 5. Local development build paths
+ * 6. System PATH
  */
 export class RustBinaryLocator {
   private options: IBinaryLocatorOptions;
@@ -37,11 +39,18 @@ export class RustBinaryLocator {
    * Find the binary path.
    * Returns null if discovery finds no binary. An unusable explicit path
    * rejects with RustBinaryLocatorError without trying discovery or chmod.
+   * Inside a single executable application, a sidecar it cannot provide rejects
+   * with RustBinaryLocatorError (`ERR_RUST_BINARY_SEA_SIDECAR_UNAVAILABLE`).
    */
   public async findBinary(): Promise<string | null> {
     if (this.options.binaryPath !== undefined) {
       return this.validateExplicitPath();
     }
+    // Inside a SEA every lookup resolves again: smartsea refreshes the extracted
+    // generation's lease and re-extracts a pruned tree, which a cached path would skip.
+    if (plugins.smartsea.isSea()) {
+      return this.findSeaBinary();
+    }
     if (this.cachedPath !== null) {
       if (await this.isExecutable(this.cachedPath)) return this.cachedPath;
       this.cachedPath = null;
@@ -62,18 +71,12 @@ export class RustBinaryLocator {
     const { binaryName } = this.options;
 
     // 2. Environment variable override
-    if (this.options.envVarName) {
-      const envPath = process.env[this.options.envVarName];
-      if (envPath) {
-        if (await this.isExecutable(envPath)) {
-          this.logger.log('info', `Binary found via ${this.options.envVarName}: ${envPath}`);
-          return envPath;
-        }
-        this.logger.log('warn', `${this.options.envVarName} set but not executable: ${envPath}`);
-      }
+    const envPath = await this.findEnvOverride();
+    if (envPath) {
+      return envPath;
     }
 
-    // 3. Platform-specific npm package
+    // 4. Platform-specific npm package
     if (this.options.platformPackagePrefix) {
       const platformBinary = await this.findPlatformPackageBinary();
       if (platformBinary) {
@@ -82,7 +85,7 @@ export class RustBinaryLocator {
       }
     }
 
-    // 4. Local development build paths
+    // 5. Local development build paths
     const localPaths = this.options.localPaths || [
       plugins.path.resolve(process.cwd(), `rust/target/release/${binaryName}`),
       plugins.path.resolve(process.cwd(), `rust/target/debug/${binaryName}`),
@@ -101,7 +104,7 @@ export class RustBinaryLocator {
       }
     }
 
-    // 5. System PATH
+    // 6. System PATH
     if (this.options.searchSystemPath !== false) {
       const systemPath = await this.findInPath(binaryName);
       if (systemPath) {
@@ -114,6 +117,49 @@ export class RustBinaryLocator {
     return null;
   }
 
+  private async findEnvOverride(): Promise<string | null> {
+    if (!this.options.envVarName) {
+      return null;
+    }
+    const envPath = process.env[this.options.envVarName];
+    if (!envPath) {
+      return null;
+    }
+    if (await this.isExecutable(envPath)) {
+      this.logger.log('info', `Binary found via ${this.options.envVarName}: ${envPath}`);
+      return envPath;
+    }
+    this.logger.log('warn', `${this.options.envVarName} set but not executable: ${envPath}`);
+    return null;
+  }
+
+  /**
+   * Inside a single executable application: the environment override, else the sidecar the
+   * executable embeds under `binaryName`. Packages, local paths and PATH belong to the machine,
+   * not to the application, and are never searched.
+   */
+  private async findSeaBinary(): Promise<string> {
+    const envPath = await this.findEnvOverride();
+    if (envPath) {
+      return envPath;
+    }
+    const { binaryName } = this.options;
+    let sidecarPath: string;
+    try {
+      sidecarPath = await plugins.smartsea.getSidecarPath(binaryName);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new RustBinaryLocatorError(
+        `This single executable application cannot provide its embedded sidecar '${binaryName}': ${reason}`,
+        undefined,
+        error,
+        'ERR_RUST_BINARY_SEA_SIDECAR_UNAVAILABLE',
+      );
+    }
+    this.logger.log('info', `Binary found as embedded sidecar: ${sidecarPath}`);
+    return sidecarPath;
+  }
+
   private async findPlatformPackageBinary(): Promise<string | null> {
     const { binaryName, platformPackagePrefix } = this.options;
     const platform = process.platform;

package/ts/classes.rustbinarylocatorerror.ts

@@ -1,13 +1,30 @@
-/** Failure to use the caller's explicit executable selection. */
+/**
+ * Why a binary lookup failed:
+ * - `ERR_RUST_BINARY_EXPLICIT_PATH_INVALID`: the caller's explicit `binaryPath` is unusable.
+ * - `ERR_RUST_BINARY_SEA_SIDECAR_UNAVAILABLE`: inside a Node.js single executable application,
+ *   the sidecar embedded under the binary's name could not be provided (not embedded, no usable
+ *   cache directory, extraction failed, …); `cause` carries the `SmartSeaError`.
+ */
+export type TRustBinaryLocatorErrorCode =
+  | 'ERR_RUST_BINARY_EXPLICIT_PATH_INVALID'
+  | 'ERR_RUST_BINARY_SEA_SIDECAR_UNAVAILABLE';
+
+/**
+ * A binary lookup that must not continue with other candidates: an unusable explicit
+ * `binaryPath`, or an embedded sidecar a single executable application cannot provide.
+ * `RustBridge.spawn()` rejects with it instead of resolving `false`.
+ */
 export class RustBinaryLocatorError extends Error {
-  public readonly code = 'ERR_RUST_BINARY_EXPLICIT_PATH_INVALID' as const;
+  public readonly code: TRustBinaryLocatorErrorCode;
 
   constructor(
     message: string,
     public readonly binaryPath: string | undefined,
     cause?: unknown,
+    code: TRustBinaryLocatorErrorCode = 'ERR_RUST_BINARY_EXPLICIT_PATH_INVALID',
   ) {
     super(message, cause === undefined ? undefined : { cause });
     this.name = 'RustBinaryLocatorError';
+    this.code = code;
   }
 }

package/ts/classes.rustbridge.ts

@@ -155,7 +155,8 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   /**
    * Spawn the Rust binary and wait for it to signal readiness.
    * Returns true if the binary was found and spawned successfully.
-   * Rejects with RustBinaryLocatorError for an invalid explicit binaryPath.
+   * Rejects with RustBinaryLocatorError for an invalid explicit binaryPath and,
+   * inside a single executable application, for an embedded sidecar it cannot provide.
    */
   public spawn(): Promise<boolean> {
     return this.activate(async (generationArg) => {

package/ts/index.ts

@@ -7,7 +7,7 @@ export {
   type TRustBridgeRequestErrorCode,
 } from './classes.rustbridgerequesterror.js';
 export { RustBinaryLocator } from './classes.rustbinarylocator.js';
-export { RustBinaryLocatorError } from './classes.rustbinarylocatorerror.js';
+export { RustBinaryLocatorError, type TRustBinaryLocatorErrorCode } from './classes.rustbinarylocatorerror.js';
 export { StreamingResponse } from './classes.streamingresponse.js';
 export { StdioTransport } from './classes.stdiotransport.js';
 export { SocketTransport } from './classes.sockettransport.js';

package/ts/plugins.ts

@@ -11,5 +11,6 @@ export { path, fs, childProcess, events, url, net, stream };
 
 // @push.rocks scope
 import * as smartpath from '@push.rocks/smartpath';
+import * as smartsea from '@push.rocks/smartsea';
 
-export { smartpath };
+export { smartpath, smartsea };