feat(smartnetwork): add Rust-powered network diagnostics bridge and IP intelligence lookups
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user