100 lines
4.4 KiB
Markdown
100 lines
4.4 KiB
Markdown
# 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
|