# @push.rocks/smartnetwork Comprehensive network diagnostics and utilities for Node.js applications ## Install To install `@push.rocks/smartnetwork`, run the following command in your terminal: ```bash npm install @push.rocks/smartnetwork --save ``` ## Usage The `@push.rocks/smartnetwork` package provides a comprehensive suite of network diagnostic tools including speed tests, port availability checks, ping operations, DNS resolution, HTTP endpoint health checks, and more. ### Basic Setup First, import the package into your project: ```typescript import { SmartNetwork } from '@push.rocks/smartnetwork'; ``` Then, create an instance of `SmartNetwork`: ```typescript const myNetwork = new SmartNetwork(); // Or with caching enabled (60 seconds TTL) const myNetworkCached = new SmartNetwork({ cacheTtl: 60000 }); ``` ### Network Speed Testing Measure network download and upload speeds using Cloudflare's speed test infrastructure: ```typescript const speedTest = async () => { // Basic speed test const result = await myNetwork.getSpeed(); console.log(`Download: ${result.downloadSpeed} Mbps`); console.log(`Upload: ${result.uploadSpeed} Mbps`); // Advanced speed test with options const advancedResult = await myNetwork.getSpeed({ parallelStreams: 3, // Number of concurrent connections duration: 5 // Test duration in seconds }); console.log(`Download: ${advancedResult.downloadSpeed} Mbps`); console.log(`Upload: ${advancedResult.uploadSpeed} Mbps`); }; ``` ### Port Management #### Check Local Port Availability Verify if a specific port is available on your local machine (checks both IPv4 and IPv6): ```typescript const checkLocalPort = async (port: number) => { const isUnused = await myNetwork.isLocalPortUnused(port); if (isUnused) { console.log(`Port ${port} is available`); } else { console.log(`Port ${port} is in use`); } }; await checkLocalPort(8080); ``` #### Find Free Port in Range Automatically find the first available port within a specified range: ```typescript const findFreePort = async () => { // Find a free port between 3000 and 3100 const freePort = await myNetwork.findFreePort(3000, 3100); if (freePort) { console.log(`Found free port: ${freePort}`); } else { console.log('No free ports available in the specified range'); } }; ``` #### Check Remote Port Availability Verify if a port is open on a remote server: ```typescript // Method 1: Using "host:port" syntax const isOpen1 = await myNetwork.isRemotePortAvailable('example.com:443'); // Method 2: Using separate host and port const isOpen2 = await myNetwork.isRemotePortAvailable('example.com', 443); // Method 3: With options (retries, timeout) const isOpen3 = await myNetwork.isRemotePortAvailable('example.com', { port: 443, protocol: 'tcp', // Only TCP is supported retries: 3, // Number of connection attempts timeout: 5000 // Timeout per attempt in ms }); // Note: UDP is not supported and will throw an error try { await myNetwork.isRemotePortAvailable('example.com', { port: 53, protocol: 'udp' }); } catch (e) { console.error(e.code); // ENOTSUP } ``` ### Network Connectivity #### Ping Operations Send ICMP echo requests to test connectivity and measure latency: ```typescript // Simple ping const pingResult = await myNetwork.ping('google.com'); console.log(`Host alive: ${pingResult.alive}`); console.log(`RTT: ${pingResult.time} ms`); // Ping with statistics (multiple pings) const pingStats = await myNetwork.ping('google.com', { count: 5, // Number of pings timeout: 1000 // Timeout per ping in ms }); console.log(`Packet loss: ${pingStats.packetLoss}%`); console.log(`Min: ${pingStats.min} ms`); console.log(`Max: ${pingStats.max} ms`); console.log(`Avg: ${pingStats.avg.toFixed(2)} ms`); console.log(`Stddev: ${pingStats.stddev.toFixed(2)} ms`); ``` #### Traceroute Perform hop-by-hop network path analysis: ```typescript const hops = await myNetwork.traceroute('google.com', { maxHops: 10, // Maximum number of hops timeout: 5000 // Timeout in ms }); hops.forEach(hop => { const rtt = hop.rtt === null ? '*' : `${hop.rtt} ms`; console.log(`${hop.ttl}\t${hop.ip}\t${rtt}`); }); ``` Note: Falls back to a single-hop stub if the `traceroute` binary is unavailable on the system. ### DNS Operations Resolve DNS records for a hostname: ```typescript const dnsRecords = await myNetwork.resolveDns('example.com'); console.log('A records:', dnsRecords.A); // IPv4 addresses console.log('AAAA records:', dnsRecords.AAAA); // IPv6 addresses console.log('MX records:', dnsRecords.MX); // Mail servers // MX records include priority dnsRecords.MX.forEach(mx => { console.log(`Mail server: ${mx.exchange} (priority: ${mx.priority})`); }); ``` ### HTTP/HTTPS Endpoint Health Checks Check the health and response time of HTTP/HTTPS endpoints: ```typescript const health = await myNetwork.checkEndpoint('https://example.com', { timeout: 5000 // Request timeout in ms }); console.log(`Status: ${health.status}`); console.log(`RTT: ${health.rtt} ms`); console.log('Headers:', health.headers); ``` ### Network Interface Information #### Get Network Gateways List all network interfaces on the system: ```typescript const gateways = await myNetwork.getGateways(); Object.entries(gateways).forEach(([name, interfaces]) => { console.log(`Interface: ${name}`); interfaces.forEach(iface => { console.log(` ${iface.family}: ${iface.address}`); console.log(` Netmask: ${iface.netmask}`); console.log(` MAC: ${iface.mac}`); }); }); ``` #### Get Default Gateway Retrieve the system's default network gateway: ```typescript const defaultGateway = await myNetwork.getDefaultGateway(); if (defaultGateway) { console.log('IPv4 Gateway:', defaultGateway.ipv4.address); console.log('IPv6 Gateway:', defaultGateway.ipv6.address); } ``` ### Public IP Discovery Discover your public IPv4 and IPv6 addresses: ```typescript const publicIps = await myNetwork.getPublicIps(); console.log(`Public IPv4: ${publicIps.v4 || 'Not available'}`); console.log(`Public IPv6: ${publicIps.v6 || 'Not available'}`); ``` ### Caching SmartNetwork supports caching for gateway and public IP lookups to reduce repeated network calls: ```typescript // Create instance with 60-second cache TTL const cachedNetwork = new SmartNetwork({ cacheTtl: 60000 }); // These calls will use cached results if called within 60 seconds const gateways1 = await cachedNetwork.getGateways(); const publicIps1 = await cachedNetwork.getPublicIps(); // Subsequent calls within TTL return cached results const gateways2 = await cachedNetwork.getGateways(); // From cache const publicIps2 = await cachedNetwork.getPublicIps(); // From cache ``` ### Plugin Architecture Extend SmartNetwork's functionality with custom plugins: ```typescript // Define your plugin class CustomNetworkPlugin { constructor(private smartNetwork: SmartNetwork) {} async customMethod() { // Your custom network functionality } } // Register the plugin SmartNetwork.registerPlugin('customPlugin', CustomNetworkPlugin); // Use the plugin const network = new SmartNetwork(); const plugin = new (SmartNetwork.pluginsRegistry.get('customPlugin'))(network); await plugin.customMethod(); // Unregister when no longer needed SmartNetwork.unregisterPlugin('customPlugin'); ``` ### Error Handling The package uses custom `NetworkError` class for network-related errors: ```typescript import { NetworkError } from '@push.rocks/smartnetwork'; try { await myNetwork.isRemotePortAvailable('example.com', { protocol: 'udp' }); } catch (error) { if (error instanceof NetworkError) { console.error(`Network error: ${error.message}`); console.error(`Error code: ${error.code}`); } } ``` ### TypeScript Support This package is written in TypeScript and provides full type definitions. Key interfaces include: ```typescript interface SmartNetworkOptions { cacheTtl?: number; // Cache TTL in milliseconds } interface Hop { ttl: number; // Time to live ip: string; // IP address of the hop rtt: number | null; // Round trip time in ms } ``` ## License and Legal Information This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. ### Trademarks This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH. ### Company Information Task Venture Capital GmbH Registered at District court Bremen HRB 35230 HB, Germany For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.