smartnetwork/readme.hints.md

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.

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)

Key Components

SmartNetwork Class

• Central orchestrator for all network operations
• Supports caching via cacheTtl option for gateway and public IP lookups
• Plugin architecture for extensibility

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)

Error Handling

• Custom NetworkError and TimeoutError classes for better error context
• Error codes follow Node.js conventions (ENOTSUP, EINVAL, ETIMEOUT)

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

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

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

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

Design Patterns

• 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