@push.rocks/smartnetwork 4.10.0 → 5.0.0

package/ts/smartnetwork.classes.smartnetwork.ts

@@ -5,7 +5,10 @@ import { IpIntelligence, type IIpIntelligenceResult } from './smartnetwork.class
 import { DomainIntelligence, type IDomainIntelligenceResult } from './smartnetwork.classes.domainintelligence.js';
 import { getLogger } from './logging.js';
 import { NetworkError } from './errors.js';
-import { RustNetworkBridge } from './smartnetwork.classes.rustbridge.js';
+import {
+  RustNetworkBridge,
+  RustNetworkBridgeActivationCleanupError,
+} from './smartnetwork.classes.rustbridge.js';
 
 /** Type alias for the shared Smartdns client instance */
 type TSmartdnsClient = InstanceType<typeof plugins.smartdns.dnsClientMod.Smartdns>;
@@ -29,6 +32,37 @@ export interface Hop {
   rtt: number | null;
 }
 
+/**
+ * Options for the ping method
+ */
+export interface IPingOptions {
+  /** Time to wait for each echo reply in milliseconds. Default: 5000 */
+  timeout?: number;
+  /** Number of echo requests to send. Default: 1 */
+  count?: number;
+}
+
+/**
+ * Result of the ping method. Round-trip times are in milliseconds and `null`
+ * where no reply arrived.
+ */
+export interface IPingResult {
+  host: string;
+  count: number;
+  /** True when at least one echo reply arrived */
+  alive: boolean;
+  /** Round-trip time of the first reply */
+  time: number | null;
+  /** Round-trip time per echo request */
+  times: (number | null)[];
+  min: number | null;
+  max: number | null;
+  avg: number | null;
+  stddev: number | null;
+  /** Lost echo requests in percent */
+  packetLoss: number;
+}
+
 /**
  * Options for the findFreePort method
  */
@@ -39,6 +73,8 @@ export interface IFindFreePortOptions {
   exclude?: number[];
 }
 
+type TBridgeLifecycleState = 'idle' | 'active' | 'release-failed';
+
 /**
  * SmartNetwork simplifies actions within the network.
  * Uses a Rust binary for system-dependent operations (ping, traceroute, port scanning, gateway detection).
@@ -58,7 +94,11 @@ export class SmartNetwork {
   private options: SmartNetworkOptions;
   private cache: Map<string, { value: any; expiry: number }>;
   private rustBridge: RustNetworkBridge;
-  private bridgeStarted = false;
+  private bridgeLifecycleState: TBridgeLifecycleState = 'idle';
+  private bridgeLifecycleQueue: Promise<void> = Promise.resolve();
+  private activeDnsOperations = 0;
+  private dnsDrainPromise: Promise<void> | null = null;
+  private resolveDnsDrain: (() => void) | null = null;
   private ipIntelligence: IpIntelligence | null = null;
   private domainIntelligence: DomainIntelligence | null = null;
   private dnsClient: TSmartdnsClient | null = null;
@@ -73,11 +113,21 @@ export class SmartNetwork {
    * Start the Rust binary bridge. Must be called before using ping, traceroute,
    * port scanning, or gateway operations. Safe to call multiple times.
    */
-  public async start(): Promise<void> {
-    if (!this.bridgeStarted) {
-      await this.rustBridge.start();
-      this.bridgeStarted = true;
-    }
+  public start(): Promise<void> {
+    return this.enqueueBridgeLifecycle(async () => {
+      if (this.bridgeLifecycleState === 'release-failed') {
+        throw new Error('SmartNetwork cleanup must succeed before it can start again');
+      }
+      try {
+        await this.rustBridge.start(this);
+        this.bridgeLifecycleState = 'active';
+      } catch (error) {
+        if (error instanceof RustNetworkBridgeActivationCleanupError) {
+          this.bridgeLifecycleState = 'release-failed';
+        }
+        throw error;
+      }
+    });
   }
 
   /**
@@ -86,35 +136,100 @@ export class SmartNetwork {
    * Rust-backed features, otherwise the smartdns Rust backend may keep
    * the event loop alive.
    */
-  public async stop(): Promise<void> {
-    if (this.bridgeStarted) {
-      await this.rustBridge.stop();
-      this.bridgeStarted = false;
+  public stop(): Promise<void> {
+    return this.enqueueBridgeLifecycle(async () => {
+      await this.waitForDnsOperations();
+
+      let bridgeError: unknown;
+      if (this.bridgeLifecycleState !== 'idle') {
+        try {
+          await this.rustBridge.stop(this);
+        } catch (error) {
+          bridgeError = error;
+        }
+      }
+
+      let dnsError: unknown;
+      if (this.dnsClient) {
+        try {
+          await this.dnsClient.terminate();
+          this.dnsClient = null;
+          // Intelligence instances hold a stale reference to the terminated
+          // client; drop them so the next call rebuilds with a fresh one.
+          this.ipIntelligence = null;
+          this.domainIntelligence = null;
+        } catch (error) {
+          dnsError = error;
+        }
+      }
+
+      if (bridgeError || dnsError) {
+        this.bridgeLifecycleState = 'release-failed';
+      } else {
+        this.bridgeLifecycleState = 'idle';
+      }
+
+      if (bridgeError && dnsError) {
+        throw new AggregateError([bridgeError, dnsError], 'SmartNetwork cleanup failed');
+      }
+      if (bridgeError) throw bridgeError;
+      if (dnsError) throw dnsError;
+    });
+  }
+
+  private enqueueBridgeLifecycle(operationArg: () => Promise<void>): Promise<void> {
+    const result = this.bridgeLifecycleQueue.then(operationArg);
+    this.bridgeLifecycleQueue = result.catch(() => {});
+    return result;
+  }
+
+  private async withDnsClient<T>(
+    operationArg: (dnsClientArg: TSmartdnsClient) => Promise<T>,
+  ): Promise<T> {
+    let dnsClient: TSmartdnsClient;
+    await this.enqueueBridgeLifecycle(async () => {
+      if (this.bridgeLifecycleState === 'release-failed') {
+        throw new Error('SmartNetwork cleanup must succeed before DNS can be used again');
+      }
+      dnsClient = this.ensureDnsClient();
+      this.activeDnsOperations++;
+    });
+
+    try {
+      return await operationArg(dnsClient!);
+    } finally {
+      this.activeDnsOperations--;
+      if (this.activeDnsOperations === 0 && this.resolveDnsDrain) {
+        const resolve = this.resolveDnsDrain;
+        this.resolveDnsDrain = null;
+        this.dnsDrainPromise = null;
+        resolve();
+      }
     }
-    if (this.dnsClient) {
-      this.dnsClient.destroy();
-      this.dnsClient = null;
-      // Intelligence instances hold a stale reference to the destroyed
-      // client; drop them so the next call rebuilds with a fresh one.
-      this.ipIntelligence = null;
-      this.domainIntelligence = null;
+  }
+
+  private waitForDnsOperations(): Promise<void> {
+    if (this.activeDnsOperations === 0) return Promise.resolve();
+    if (!this.dnsDrainPromise) {
+      this.dnsDrainPromise = new Promise<void>((resolve) => {
+        this.resolveDnsDrain = resolve;
+      });
     }
+    return this.dnsDrainPromise;
   }
 
   /**
    * Ensure the Rust bridge is running before sending commands.
    */
   private async ensureBridge(): Promise<void> {
-    if (!this.bridgeStarted) {
-      await this.start();
-    }
+    await this.start();
   }
 
   /**
    * Lazily create the shared Smartdns client. The Rust backend inside
    * Smartdns is only spawned on first query that requires it (NS/MX/SOA
    * with prefer-system strategy, or any query with doh/udp strategy).
-   * The client is destroyed by stop().
+   * The client is terminated by stop().
    */
   private ensureDnsClient(): TSmartdnsClient {
     if (!this.dnsClient) {
@@ -136,9 +251,14 @@ export class SmartNetwork {
   }
 
   /**
-   * Send ICMP pings to a host. Optionally specify count for multiple pings.
+   * Send ICMP echo requests to a host.
+   *
+   * A host that does not answer or cannot be resolved yields `alive: false`.
+   * Rejects with a `NetworkError` with code `EPERM` when the process may not
+   * open an ICMP socket (Linux needs `CAP_NET_RAW` or a `net.ipv4.ping_group_range`
+   * that includes the process group), because no probe was sent at all.
    */
-  public async ping(host: string, opts?: { timeout?: number; count?: number }): Promise<any> {
+  public async ping(host: string, opts?: IPingOptions): Promise<IPingResult> {
     await this.ensureBridge();
     const timeoutMs = opts?.timeout ?? 5000;
     const count = opts?.count && opts.count > 1 ? opts.count : 1;
@@ -146,48 +266,43 @@ export class SmartNetwork {
     let result: Awaited<ReturnType<typeof this.rustBridge.ping>>;
     try {
       result = await this.rustBridge.ping(host, count, timeoutMs);
-    } catch {
-      // DNS resolution failure or other error — return dead ping
-      if (count === 1) {
-        return { alive: false, time: NaN };
+    } catch (error) {
+      if (error instanceof plugins.smartrust.RustBridgeRequestError) {
+        if (error.responseErrorCode === 'ERESOLVE') {
+          return {
+            host,
+            count,
+            alive: false,
+            time: null,
+            times: Array<number | null>(count).fill(null),
+            min: null,
+            max: null,
+            avg: null,
+            stddev: null,
+            packetLoss: 100,
+          };
+        }
+        if (error.responseErrorCode === 'EPERM') {
+          throw new NetworkError(
+            `ICMP ping is not permitted for this process (needs CAP_NET_RAW or a net.ipv4.ping_group_range that includes its group): ${error.message}`,
+            'EPERM',
+          );
+        }
       }
-      return {
-        host,
-        count,
-        times: Array(count).fill(NaN),
-        min: NaN,
-        max: NaN,
-        avg: NaN,
-        stddev: NaN,
-        packetLoss: 100,
-        alive: false,
-      };
-    }
-
-    // Map times: replace null with NaN for backward compatibility
-    const times = result.times.map((t) => (t === null ? NaN : t));
-    const min = result.min === null ? NaN : result.min;
-    const max = result.max === null ? NaN : result.max;
-    const avg = result.avg === null ? NaN : result.avg;
-    const stddev = result.stddev === null ? NaN : result.stddev;
-
-    if (count === 1) {
-      return {
-        alive: result.alive,
-        time: times[0] ?? NaN,
-      };
+      throw error;
     }
 
     return {
       host,
       count,
-      times,
-      min,
-      max,
-      avg,
-      stddev,
-      packetLoss: result.packetLoss,
       alive: result.alive,
+      time: result.times.find((time) => time !== null) ?? null,
+      times: result.times,
+      min: result.min,
+      max: result.max,
+      avg: result.avg,
+      stddev: result.stddev,
+      packetLoss: result.packetLoss,
     };
   }
 
@@ -348,31 +463,31 @@ export class SmartNetwork {
   /**
    * Resolve DNS records (A, AAAA, MX) via the shared smartdns client.
    * The client is lifecycle-managed by start()/stop() — MX queries spawn
-   * the smartdns Rust bridge, which is torn down by stop().
+   * the smartdns Rust bridge, whose termination is confirmed by stop().
    */
   public async resolveDns(
     host: string,
   ): Promise<{ A: string[]; AAAA: string[]; MX: { exchange: string; priority: number }[] }> {
     try {
-      const dnsClient = this.ensureDnsClient();
-
-      const [aRecords, aaaaRecords, mxRecords] = await Promise.all([
-        dnsClient.getRecordsA(host).catch((): any[] => []),
-        dnsClient.getRecordsAAAA(host).catch((): any[] => []),
-        dnsClient.getRecords(host, 'MX').catch((): any[] => []),
-      ]);
-
-      const A = aRecords.map((record: any) => record.value);
-      const AAAA = aaaaRecords.map((record: any) => record.value);
-      const MX = mxRecords.map((record: any) => {
-        const parts = record.value.split(' ');
-        return {
-          priority: parseInt(parts[0], 10),
-          exchange: parts[1] || '',
-        };
+      return await this.withDnsClient(async (dnsClient) => {
+        const [aRecords, aaaaRecords, mxRecords] = await Promise.all([
+          dnsClient.getRecordsA(host).catch((): any[] => []),
+          dnsClient.getRecordsAAAA(host).catch((): any[] => []),
+          dnsClient.getRecords(host, 'MX').catch((): any[] => []),
+        ]);
+
+        const A = aRecords.map((record: any) => record.value);
+        const AAAA = aaaaRecords.map((record: any) => record.value);
+        const MX = mxRecords.map((record: any) => {
+          const parts = record.value.split(' ');
+          return {
+            priority: parseInt(parts[0], 10),
+            exchange: parts[1] || '',
+          };
+        });
+
+        return { A, AAAA, MX };
       });
-
-      return { A, AAAA, MX };
     } catch (err: any) {
       throw new NetworkError(err.message, err.code);
     }
@@ -438,13 +553,15 @@ export class SmartNetwork {
    * Pure TS, no Rust needed.
    */
   public async getIpIntelligence(ip: string): Promise<IIpIntelligenceResult> {
-    if (!this.ipIntelligence) {
-      this.ipIntelligence = new IpIntelligence({
-        dnsClient: this.ensureDnsClient(),
-        timeout: this.options.ipIntelligenceTimeout,
-      });
-    }
-    const fetcher = () => this.ipIntelligence!.getIntelligence(ip);
+    const fetcher = () => this.withDnsClient(async (dnsClient) => {
+      if (!this.ipIntelligence) {
+        this.ipIntelligence = new IpIntelligence({
+          dnsClient,
+          timeout: this.options.ipIntelligenceTimeout,
+        });
+      }
+      return this.ipIntelligence.getIntelligence(ip);
+    });
     if (this.options.cacheTtl && this.options.cacheTtl > 0) {
       return this.getCached(`ipIntelligence:${ip}`, fetcher);
     }
@@ -457,10 +574,12 @@ export class SmartNetwork {
    * Rust needed.
    */
   public async getDomainIntelligence(domain: string): Promise<IDomainIntelligenceResult> {
-    if (!this.domainIntelligence) {
-      this.domainIntelligence = new DomainIntelligence({ dnsClient: this.ensureDnsClient() });
-    }
-    const fetcher = () => this.domainIntelligence!.getIntelligence(domain);
+    const fetcher = () => this.withDnsClient(async (dnsClient) => {
+      if (!this.domainIntelligence) {
+        this.domainIntelligence = new DomainIntelligence({ dnsClient });
+      }
+      return this.domainIntelligence.getIntelligence(domain);
+    });
     if (this.options.cacheTtl && this.options.cacheTtl > 0) {
       return this.getCached(`domainIntelligence:${domain}`, fetcher);
     }

package/readme.hints.md

@@ -1,106 +0,0 @@
-# Project Analysis
-
-## Architecture Overview
-This is a comprehensive network diagnostics toolkit. The main entry point is the `SmartNetwork` class which orchestrates all functionality. System-dependent operations are delegated to a Rust binary via JSON-over-stdin/stdout IPC using `@push.rocks/smartrust`.
-
-Key features:
-- Speed testing via Cloudflare (parallelizable with duration support) — pure TS
-- ICMP ping with statistics — Rust binary (surge-ping)
-- Port availability checks (local and remote) — Rust binary (tokio TCP / socket2)
-- Network gateway discovery — Rust binary (parses /proc/net/route on Linux)
-- Public IP retrieval — pure TS
-- DNS resolution via smartdns — pure TS
-- HTTP endpoint health checks — pure TS
-- Traceroute — Rust binary (raw ICMP sockets via socket2)
-
-## Rust Binary Architecture (v4.5.0+)
-
-### Binary: `rustnetwork`
-- Located in `rust/crates/rustnetwork/`
-- Cross-compiled for linux_amd64 and linux_arm64 via `@git.zone/tsrust`
-- Output: `dist_rust/rustnetwork_linux_amd64`, `dist_rust/rustnetwork_linux_arm64`
-- IPC mode: `--management` flag for JSON-over-stdin/stdout
-
-### IPC Commands
-| Method | Description |
-|--------|-------------|
-| `healthPing` | Liveness check (returns `{ pong: true }`) |
-| `ping` | ICMP ping with count/timeout, returns stats |
-| `traceroute` | Hop-by-hop latency via raw ICMP sockets |
-| `tcpPortCheck` | TCP connect probe to remote host:port |
-| `isLocalPortFree` | Bind test on IPv4 + IPv6 |
-| `defaultGateway` | Parse /proc/net/route for default interface |
-
-### TypeScript Bridge
-- `ts/smartnetwork.classes.rustbridge.ts` — Singleton `RustNetworkBridge` wrapping `smartrust.RustBridge`
-- `SmartNetwork` class has `start()`/`stop()` lifecycle for the bridge
-- `ensureBridge()` auto-starts on first use
-
-### Build Pipeline
-- `pnpm build` = `tsbuild tsfolders && tsrust`
-- Targets configured in `.smartconfig.json` under `@git.zone/tsrust`
-
-## Key Components
-
-### SmartNetwork Class
-- Central orchestrator for all network operations
-- Requires `start()` before using ping/traceroute/port/gateway operations
-- Supports caching via `cacheTtl` option for gateway and public IP lookups
-- Plugin architecture for extensibility
-
-### RustNetworkBridge Class
-- Singleton pattern via `getInstance()`
-- Binary search: dist_rust/ (platform-suffixed) > rust/target/release/ > rust/target/debug/
-- `searchSystemPath: false` — only looks in local paths
-
-### CloudflareSpeed Class
-- Handles internet speed testing using Cloudflare's infrastructure
-- Supports parallel streams and customizable test duration
-- Upload speed measurement uses server-timing header with client-side timing fallback
-
-### Error Handling
-- Custom `NetworkError` and `TimeoutError` classes for better error context
-- Error codes follow Node.js conventions (ENOTSUP, EINVAL, ETIMEOUT)
-- Ping/port methods gracefully degrade on errors (return alive=false / false)
-
-### Logging
-- Global logger interface for consistent logging across the codebase
-- Replaceable logger implementation (defaults to console)
-
-### Statistics Helpers
-- Utility functions for statistical calculations (average, median, quartile, jitter)
-- Used by speed testing; ping statistics now computed server-side in Rust
-
-## Dependencies
-- **Runtime**: `@push.rocks/smartrust` (IPC bridge), `@push.rocks/smartdns` (DNS resolution)
-- **Removed in v4.5.0**: `@push.rocks/smartping`, `@push.rocks/smartstring`, `isopen`, `systeminformation`
-- **Dev**: `@git.zone/tsrust` (Rust cross-compilation)
-
-## Testing
-- `test/test.ts` — Core smoke tests (speed, ports, gateways, public IPs)
-- `test/test.ping.ts` — ICMP ping tests (requires CAP_NET_RAW for alive=true)
-- `test/test.ports.ts` — Comprehensive port testing (27 tests)
-- `test/test.features.ts` — DNS, HTTP health check, traceroute, multi-ping, plugins, caching
-- All tests require `start()`/`stop()` lifecycle for the Rust bridge
-
-## Technical Details
-- ESM-only package (module type)
-- TypeScript with strict typing
-- Node built-in imports use `node:` prefix throughout
-- Uses native Node.js modules for HTTP/HTTPS and os.networkInterfaces()
-- Rust binary requires no elevated privileges for port checks; ICMP ping needs CAP_NET_RAW or appropriate ping_group_range
-
-## Design Patterns
-- Singleton pattern for RustNetworkBridge
-- Factory pattern for plugin registration
-- Caching pattern with TTL for expensive operations
-- Promise-based async/await throughout
-- Error propagation with custom error types
-- Graceful degradation when ICMP permissions unavailable
-
-## Static Rust Binaries
-
-- The Rust binaries in `dist_rust/` are statically linked (static-pie) via `"static": true` in the `@git.zone/tsrust` block of `.smartconfig.json` (tsrust >= 1.4.1). They run on both glibc (Debian/Ubuntu) and musl (Alpine) systems.
-- tsrust injects `RUSTFLAGS="-C target-feature=+crt-static"` only into its own per-target cargo invocations and verifies the result (no `PT_INTERP` ELF header). Keep `rust/.cargo/config.toml` free of `rustflags` entries: the injected env variable would replace them, and a repo-wide `rustflags` would also break plain `cargo test`/`cargo check` (proc-macros cannot build with `+crt-static` on linux-gnu without an explicit `--target`).
-- `pnpm run test:rust` runs the Rust unit tests; plain `cargo test` in `rust/` works as well.
-- Verify linkage manually with `ldd dist_rust/<binary>_linux_amd64` → "statically linked".

package/ts/tsconfig.json

@@ -1,5 +0,0 @@
-{
-  "compilerOptions": {
-    "noImplicitAny": true
-  }
-}