smartnetwork/readme.hints.md

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 --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
• 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