@push.rocks/smartnetwork 4.10.1 → 5.0.1

package/ts/smartnetwork.classes.smartnetwork.ts

@@ -32,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
  */
@@ -220,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;
@@ -230,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,
     };
   }
 

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 — TypeScript orchestration with a Rust UDP/DoH fallback
-- 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 serializes shared Rust ownership and drains DNS operations before confirmed `stop()` cleanup
-- `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
-- Rust-backed tests require `start()`/`stop()`; failed Rust or DNS cleanup retains ownership until `stop()` succeeds on retry
-
-## 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
-  }
-}