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