@push.rocks/smartnetwork 4.3.0 → 4.5.0

package/readme.hints.md

@@ -1,73 +1,99 @@
 # Project Analysis
 
 ## Architecture Overview
-This is a comprehensive network diagnostics toolkit that provides various network-related utilities. The main entry point is the `SmartNetwork` class which orchestrates all functionality.
+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)
-- Ping operations with statistics
-- Port availability checks (local and remote)
-- Network gateway discovery
-- Public IP retrieval
-- DNS resolution
-- HTTP endpoint health checks
-- Traceroute functionality (with fallback stub)
+- 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 --allowimplicitany && 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
-- Measures both download and upload speeds using progressive chunk sizes
-- Includes latency measurements (jitter, median, average)
+- 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)
-- Used primarily for error reporting in speed tests
 
 ### Statistics Helpers
 - Utility functions for statistical calculations (average, median, quartile, jitter)
-- Used extensively by speed testing and ping operations
+- Used by speed testing; ping statistics now computed server-side in Rust
 
-## Recent Changes (v4.0.0 - v4.0.1)
-- Added configurable speed test options (parallelStreams, duration)
-- Introduced plugin architecture for runtime extensibility
-- Enhanced error handling with custom error classes
-- Added global logging interface
-- Improved connection management by disabling HTTP connection pooling
-- Fixed memory leaks from listener accumulation
-- Minor formatting fixes for consistency
+## 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
-- Comprehensive test suite covering all major features
-- Tests run on both browser and node environments
-- Uses @push.rocks/tapbundle for testing with expectAsync
-- Performance tests for speed testing functionality
-- Edge case handling for network errors and timeouts
+- `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
-- Depends on external modules for specific functionality:
-  - @push.rocks/smartping for ICMP operations
-  - public-ip for external IP discovery
-  - systeminformation for network interface details
-  - isopen for remote port checking
-- Uses native Node.js modules for DNS, HTTP/HTTPS, and network operations
+- 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
-- Deferred promises for complex async coordination
-- Error propagation with custom error types
+- Error propagation with custom error types
+- Graceful degradation when ICMP permissions unavailable

package/readme.md

@@ -37,6 +37,14 @@ import { SmartNetwork } from '@push.rocks/smartnetwork';
 // Basic instance
 const network = new SmartNetwork();
 
+// Start the Rust bridge (auto-started on first use, but explicit start is recommended)
+await network.start();
+
+// ... use the network instance ...
+
+// Clean up when done (stops the Rust bridge process)
+await network.stop();
+
 // With caching enabled (60 seconds TTL)
 const cachedNetwork = new SmartNetwork({ cacheTtl: 60000 });
 ```
@@ -99,6 +107,19 @@ const findFreePort = async () => {
   // Find a random free port in range (useful to avoid port conflicts)
   const randomPort = await network.findFreePort(3000, 3100, { randomize: true });
   console.log(`🎲 Random free port: ${randomPort}`);
+  
+  // Exclude specific ports from the search
+  const portWithExclusions = await network.findFreePort(3000, 3100, {
+    exclude: [3000, 3001, 3005]  // Skip these ports even if they're free
+  });
+  console.log(`🚫 Free port (excluding specific ports): ${portWithExclusions}`);
+  
+  // Combine randomize with exclude options
+  const randomWithExclusions = await network.findFreePort(3000, 3100, {
+    randomize: true,
+    exclude: [3000, 3001, 3005]
+  });
+  console.log(`🎲🚫 Random free port (with exclusions): ${randomWithExclusions}`);
 };
 ```
 
@@ -333,6 +354,7 @@ interface SmartNetworkOptions {
 
 interface IFindFreePortOptions {
   randomize?: boolean;  // If true, returns a random free port instead of the first one
+  exclude?: number[];   // Array of port numbers to exclude from the search
 }
 
 interface Hop {

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartnetwork',
-  version: '4.3.0',
+  version: '4.5.0',
   description: 'A toolkit for network diagnostics including speed tests, port availability checks, and more.'
 }

package/ts/helpers/stats.ts

@@ -33,7 +33,7 @@ export function quartile(values: number[], percentile: number) {
 
 export function jitter(values: number[]) {
   // Average distance between consecutive latency measurements...
-  let jitters = [];
+  let jitters: number[] = [];
 
   for (let i = 0; i < values.length - 1; i += 1) {
     jitters.push(Math.abs(values[i] - values[i + 1]));

package/ts/index.ts

@@ -1,5 +1,8 @@
 export * from './smartnetwork.classes.smartnetwork.js';
 export type { SmartNetworkOptions, Hop } from './smartnetwork.classes.smartnetwork.js';
+export { RustNetworkBridge } from './smartnetwork.classes.rustbridge.js';
 export { PublicIp } from './smartnetwork.classes.publicip.js';
+export { IpIntelligence } from './smartnetwork.classes.ipintelligence.js';
+export type { IIpIntelligenceResult, IIpIntelligenceOptions } from './smartnetwork.classes.ipintelligence.js';
 export { setLogger, getLogger } from './logging.js';
 export { NetworkError, TimeoutError } from './errors.js';

package/ts/smartnetwork.classes.cloudflarespeed.ts

@@ -53,7 +53,7 @@ export class CloudflareSpeed {
       const t5 = await measureDownloadParallel(100001000, 1);
       downloadTests = [...t1, ...t2, ...t3, ...t4, ...t5];
     }
-    const speedDownload = stats.quartile(downloadTests, 0.9).toFixed(2);
+    const speedDownload = downloadTests.length > 0 ? stats.quartile(downloadTests, 0.9).toFixed(2) : '0.00';
 
     // lets test the upload speed with configurable parallel streams
     const measureUploadParallel = (bytes: number, iterations: number) => {
@@ -84,7 +84,7 @@ export class CloudflareSpeed {
       const u3 = await measureUploadParallel(1001000, 8);
       uploadTests = [...u1, ...u2, ...u3];
     }
-    const speedUpload = stats.quartile(uploadTests, 0.9).toFixed(2);
+    const speedUpload = uploadTests.length > 0 ? stats.quartile(uploadTests, 0.9).toFixed(2) : '0.00';
 
     return {
       ...latency,
@@ -147,8 +147,14 @@ export class CloudflareSpeed {
     for (let i = 0; i < iterations; i += 1) {
       await this.upload(bytes).then(
         async (response) => {
-          const transferTime = response[6];
-          measurements.push(await this.measureSpeed(bytes, transferTime));
+          // Prefer server-timing duration; fall back to client-side transfer time
+          let transferTime = response[6];
+          if (!transferTime || !isFinite(transferTime)) {
+            transferTime = response[5] - response[4]; // ended - ttfb
+          }
+          if (transferTime > 0) {
+            measurements.push(await this.measureSpeed(bytes, transferTime));
+          }
         },
         (error) => {
           getLogger().error('Error measuring upload chunk:', error);
@@ -164,17 +170,22 @@ export class CloudflareSpeed {
   }
 
   public async fetchServerLocations(): Promise<{ [key: string]: string }> {
-    const res = JSON.parse(await this.get('speed.cloudflare.com', '/locations')) as Array<{
-      iata: string;
-      city: string;
-    }>;
-    return res.reduce(
-      (data: Record<string, string>, optionsArg) => {
-        data[optionsArg.iata] = optionsArg.city;
-        return data;
-      },
-      {} as Record<string, string>,
-    );
+    try {
+      const raw = await this.get('speed.cloudflare.com', '/locations');
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed)) {
+        return {};
+      }
+      return (parsed as Array<{ iata: string; city: string }>).reduce(
+        (data: Record<string, string>, entry) => {
+          data[entry.iata] = entry.city;
+          return data;
+        },
+        {} as Record<string, string>,
+      );
+    } catch {
+      return {};
+    }
   }
 
   public async get(hostname: string, path: string): Promise<string> {
@@ -259,7 +270,12 @@ export class CloudflareSpeed {
             sslHandshake,
             ttfb,
             ended,
-            parseFloat((res.headers['server-timing'] as string).slice(22)),
+            (() => {
+              const serverTiming = res.headers['server-timing'] as string | undefined;
+              if (!serverTiming) return 0;
+              const match = serverTiming.match(/dur=([\d.]+)/);
+              return match ? parseFloat(match[1]) : parseFloat(serverTiming.slice(22)) || 0;
+            })(),
           ]);
         });
       });