@push.rocks/smartnetwork 3.0.2 → 4.0.1

package/readme.md

@@ -1,61 +1,183 @@
-# @pushrocks/smartnetwork
+# @push.rocks/smartnetwork
+
 network diagnostics
 
-## Availabililty and Links
-* [npmjs.org (npm package)](https://www.npmjs.com/package/@pushrocks/smartnetwork)
-* [gitlab.com (source)](https://gitlab.com/pushrocks/smartnetwork)
-* [github.com (source mirror)](https://github.com/pushrocks/smartnetwork)
-* [docs (typedoc)](https://pushrocks.gitlab.io/smartnetwork/)
-
-## Status for master
-
-Status Category | Status Badge
--- | --
-GitLab Pipelines | [![pipeline status](https://gitlab.com/pushrocks/smartnetwork/badges/master/pipeline.svg)](https://lossless.cloud)
-GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/pushrocks/smartnetwork/badges/master/coverage.svg)](https://lossless.cloud)
-npm | [![npm downloads per month](https://badgen.net/npm/dy/@pushrocks/smartnetwork)](https://lossless.cloud)
-Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/pushrocks/smartnetwork)](https://lossless.cloud)
-TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud)
-node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/)
-Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud)
-PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@pushrocks/smartnetwork)](https://lossless.cloud)
-PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@pushrocks/smartnetwork)](https://lossless.cloud)
-BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@pushrocks/smartnetwork)](https://lossless.cloud)
-Platform support | [![Supports Windows 10](https://badgen.net/badge/supports%20Windows%2010/yes/green?icon=windows)](https://lossless.cloud) [![Supports Mac OS X](https://badgen.net/badge/supports%20Mac%20OS%20X/yes/green?icon=apple)](https://lossless.cloud)
+## Install
+
+To install `@push.rocks/smartnetwork`, run the following command in your terminal:
+
+```bash
+npm install @push.rocks/smartnetwork --save
+```
+
+### Performing a Traceroute
+
+You can perform a hop-by-hop traceroute to measure latency per hop. Falls back to a single-hop stub if the `traceroute` binary is unavailable.
+
+```typescript
+const hops = await myNetwork.traceroute('google.com', { maxHops: 10, timeout: 5000 });
+hops.forEach((h) => console.log(`${h.ttl}\t${h.ip}\t${h.rtt === null ? '*' : h.rtt + ' ms'}`));
+```
+
+This command will download `@push.rocks/smartnetwork` and add it to your project's `package.json` file.
 
 ## Usage
 
+In this section, we will dive deep into the capabilities of the `@push.rocks/smartnetwork` package, exploring its various features through TypeScript examples. The package is designed to simplify network diagnostics tasks, including speed tests, port availability checks, ping operations, 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
-import * as smartnetwork from 'smartnetwork';
-const testSmartNetwork = new smartnetwork.SmartNetwork();
-const run = async () => {
-  // measure average speed over a period of 5 seconds
-  // the structure of speedResult is self explanatory using TypeScript (or the linked TypeDoc above)
-  const speedResult: smartnetwork.SpeedResult = testSmartNetwork.getSpeed(5000);
+const myNetwork = new SmartNetwork();
+```
+
+### Performing a Speed Test
 
-  // you can check for local ports before trying to bind to it from your nodejs program
-  const isLocalPortUnused: boolean = await testSmartNetwork.isLocalPortUnused(1234);
+You can measure the network speed using the `getSpeed` method. It supports optional parameters:
 
-  // you can run basic port checks on remote domains.
-  const isRemotePortAvailable: boolean = await testSmartNetwork.isRemotePortAvailable(
-    'google.com:80'
-  );
+- `parallelStreams`: number of concurrent streams (default: 1)
+- `duration`: test duration in seconds (default: fixed segments)
 
-  // just another way to call for the same thing as above
-  const isRemotePortAvailable: boolean = await testSmartNetwork.isRemotePortAvailable(
-    'google.com',
-    80
-  );
+```typescript
+const speedTest = async () => {
+  // Default fixed-segment test
+  let r = await myNetwork.getSpeed();
+  console.log(`Download: ${r.downloadSpeed} Mbps, Upload: ${r.uploadSpeed} Mbps`);
+
+  // Parallel + duration-based test
+  r = await myNetwork.getSpeed({ parallelStreams: 3, duration: 5 });
+  console.log(`Download: ${r.downloadSpeed} Mbps, Upload: ${r.uploadSpeed} Mbps`);
 };
+
+speedTest();
+```
+
+### Checking Port Availability Locally
+
+The `isLocalPortUnused` method allows you to check if a specific port on your local machine is available for use.
+
+```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.`);
+  }
+};
+
+checkLocalPort(8080); // Example port number
+```
+
+### Checking Remote Port Availability
+
+To verify if a port is available on a remote server, use `isRemotePortAvailable`. You can specify target as `"host:port"` or host plus a numeric port.
+
+```typescript
+// Using "host:port"
+await myNetwork.isRemotePortAvailable('example.com:443');
+
+// Using host + port
+await myNetwork.isRemotePortAvailable('example.com', 443);
+
+// UDP is not supported:
+try {
+  await myNetwork.isRemotePortAvailable('example.com', { port: 53, protocol: 'udp' });
+} catch (e) {
+  console.error((e as any).code); // ENOTSUP
+}
+```
+
+### Using Ping
+
+The `ping` method sends ICMP echo requests and optionally repeats them to collect statistics.
+
+```typescript
+// Single ping
+const p1 = await myNetwork.ping('google.com');
+console.log(`Alive: ${p1.alive}, RTT: ${p1.time} ms`);
+
+// Multiple pings with statistics
+const stats = await myNetwork.ping('google.com', { count: 5 });
+console.log(
+  `min=${stats.min} ms, max=${stats.max} ms, avg=${stats.avg.toFixed(2)} ms, loss=${stats.packetLoss}%`,
+);
+```
+
+### Getting Network Gateways
+
+You can also retrieve network interfaces (gateways) and determine the default gateway. Caching with TTL is supported via constructor options.
+
+```typescript
+// Create with cache TTL of 60 seconds
+const netCached = new SmartNetwork({ cacheTtl: 60000 });
+
+// List all interfaces
+const gateways = await netCached.getGateways();
+console.log(gateways);
+
+// Get default gateway
+const defaultGw = await netCached.getDefaultGateway();
+console.log(defaultGw);
+```
+
+### Discovering Public IP Addresses
+
+To find out your public IPv4 and IPv6 addresses (with caching):
+
+```typescript
+const publicIps = await netCached.getPublicIps();
+console.log(`Public IPv4: ${publicIps.v4}`);
+console.log(`Public IPv6: ${publicIps.v6}`);
 ```
 
-## Contribution
+The `@push.rocks/smartnetwork` package provides an easy-to-use, comprehensive suite of tools for network diagnostics and monitoring, encapsulating complex network operations into simple asynchronous methods. By leveraging TypeScript, developers can benefit from type checking, ensuring that they can work with clear structures and expectations.
+
+These examples offer a glimpse into the module's utility in real-world scenarios, demonstrating its versatility in handling common network tasks. Whether you're developing a network-sensitive application, diagnosing connectivity issues, or simply curious about your network performance, `@push.rocks/smartnetwork` equips you with the tools you need.
+
+### Plugin Architecture
+
+You can extend `SmartNetwork` with custom plugins by registering them at runtime:
+
+```typescript
+import { SmartNetwork } from '@push.rocks/smartnetwork';
+
+// Define your plugin class or constructor
+class MyCustomPlugin {
+  // plugin implementation goes here
+}
+
+// Register and unregister your plugin by name
+SmartNetwork.registerPlugin('myPlugin', MyCustomPlugin);
+// Later, remove it if no longer needed
+SmartNetwork.unregisterPlugin('myPlugin');
+```
+
+Plugins enable you to dynamically augment the core functionality without altering the library's source.
+
+## 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.
 
-We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
+### Company Information
 
-For further information read the linked docs at the top of this readme.
+Task Venture Capital GmbH  
+Registered at District court Bremen HRB 35230 HB, Germany
 
-> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh)
-| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
+For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
 
-[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com)
+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.

package/ts/00_commitinfo_data.ts

@@ -1,8 +1,8 @@
 /**
- * autocreated commitinfo by @pushrocks/commitinfo
+ * autocreated commitinfo by @push.rocks/commitinfo
  */
 export const commitinfo = {
-  name: '@pushrocks/smartnetwork',
-  version: '3.0.2',
-  description: 'network diagnostics'
+  name: '@push.rocks/smartnetwork',
+  version: '4.0.1',
+  description: 'A toolkit for network diagnostics including speed tests, port availability checks, and more.'
 }

package/ts/errors.ts

@@ -0,0 +1,20 @@
+/**
+ * Custom error classes for network operations
+ */
+export class NetworkError extends Error {
+  public code?: string;
+  constructor(message?: string, code?: string) {
+    super(message);
+    this.name = 'NetworkError';
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class TimeoutError extends NetworkError {
+  constructor(message?: string) {
+    super(message, 'ETIMEOUT');
+    this.name = 'TimeoutError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/ts/index.ts

@@ -1 +1,4 @@
 export * from './smartnetwork.classes.smartnetwork.js';
+export type { SmartNetworkOptions, Hop } from './smartnetwork.classes.smartnetwork.js';
+export { setLogger, getLogger } from './logging.js';
+export { NetworkError, TimeoutError } from './errors.js';

package/ts/logging.ts

@@ -0,0 +1,30 @@
+/**
+ * Injectable logging interface and global logger
+ */
+export interface Logger {
+  /** Debug-level messages */
+  debug?(...args: unknown[]): void;
+  /** Informational messages */
+  info(...args: unknown[]): void;
+  /** Warning messages */
+  warn?(...args: unknown[]): void;
+  /** Error messages */
+  error(...args: unknown[]): void;
+}
+
+let globalLogger: Logger = console;
+
+/**
+ * Replace the global logger implementation
+ * @param logger Custom logger adhering to Logger interface
+ */
+export function setLogger(logger: Logger): void {
+  globalLogger = logger;
+}
+
+/**
+ * Retrieve the current global logger
+ */
+export function getLogger(): Logger {
+  return globalLogger;
+}

package/ts/smartnetwork.classes.cloudflarespeed.ts

@@ -1,8 +1,17 @@
 import * as plugins from './smartnetwork.plugins.js';
+import { getLogger } from './logging.js';
+import { NetworkError, TimeoutError } from './errors.js';
 import * as stats from './helpers/stats.js';
 
+export interface SpeedOptions {
+  parallelStreams?: number;
+  duration?: number;
+}
 export class CloudflareSpeed {
-  constructor() {}
+  private opts: SpeedOptions;
+  constructor(opts?: SpeedOptions) {
+    this.opts = opts || {};
+  }
 
   public async speedTest() {
     const latency = await this.measureLatency();
@@ -10,20 +19,71 @@ export class CloudflareSpeed {
     const serverLocations = await this.fetchServerLocations();
     const cgiData = await this.fetchCfCdnCgiTrace();
 
-    // lets test the download speed
-    const testDown1 = await this.measureDownload(101000, 10);
-    const testDown2 = await this.measureDownload(1001000, 8);
-    const testDown3 = await this.measureDownload(10001000, 6);
-    const testDown4 = await this.measureDownload(25001000, 4);
-    const testDown5 = await this.measureDownload(100001000, 1);
-    const downloadTests = [...testDown1, ...testDown2, ...testDown3, ...testDown4, ...testDown5];
+    // speed tests: either fixed segments or duration-based mode
+    const parallel = this.opts.parallelStreams ?? 1;
+    const measureDownloadParallel = (bytes: number, iterations: number) => {
+      if (parallel <= 1) {
+        return this.measureDownload(bytes, iterations);
+      }
+      return Promise.all(
+        Array(parallel)
+          .fill(null)
+          .map(() => this.measureDownload(bytes, iterations)),
+      ).then((arrays) => arrays.flat());
+    };
+    let downloadTests: number[];
+    if (this.opts.duration && this.opts.duration > 0) {
+      // duration-based download: run for specified seconds
+      downloadTests = [];
+      const durMs = this.opts.duration * 1000;
+      const startMs = Date.now();
+      // use medium chunk size for download
+      const chunkBytes = 25001000;
+      while (Date.now() - startMs < durMs) {
+        const speeds = await measureDownloadParallel(chunkBytes, 1);
+        downloadTests.push(...speeds);
+      }
+      if (downloadTests.length === 0) downloadTests = [0];
+    } else {
+      // fixed download segments
+      const t1 = await measureDownloadParallel(101000, 10);
+      const t2 = await measureDownloadParallel(1001000, 8);
+      const t3 = await measureDownloadParallel(10001000, 6);
+      const t4 = await measureDownloadParallel(25001000, 4);
+      const t5 = await measureDownloadParallel(100001000, 1);
+      downloadTests = [...t1, ...t2, ...t3, ...t4, ...t5];
+    }
     const speedDownload = stats.quartile(downloadTests, 0.9).toFixed(2);
 
-    // lets test the upload speed
-    const testUp1 = await this.measureUpload(11000, 10);
-    const testUp2 = await this.measureUpload(101000, 10);
-    const testUp3 = await this.measureUpload(1001000, 8);
-    const uploadTests = [...testUp1, ...testUp2, ...testUp3];
+    // lets test the upload speed with configurable parallel streams
+    const measureUploadParallel = (bytes: number, iterations: number) => {
+      if (parallel <= 1) {
+        return this.measureUpload(bytes, iterations);
+      }
+      return Promise.all(
+        Array(parallel)
+          .fill(null)
+          .map(() => this.measureUpload(bytes, iterations)),
+      ).then((arrays) => arrays.flat());
+    };
+    let uploadTests: number[];
+    if (this.opts.duration && this.opts.duration > 0) {
+      // duration-based upload: run for specified seconds
+      uploadTests = [];
+      const durMsUp = this.opts.duration * 1000;
+      const startMsUp = Date.now();
+      const chunkBytesUp = 1001000;
+      while (Date.now() - startMsUp < durMsUp) {
+        const speeds = await measureUploadParallel(chunkBytesUp, 1);
+        uploadTests.push(...speeds);
+      }
+      if (uploadTests.length === 0) uploadTests = [0];
+    } else {
+      const u1 = await measureUploadParallel(11000, 10);
+      const u2 = await measureUploadParallel(101000, 10);
+      const u3 = await measureUploadParallel(1001000, 8);
+      uploadTests = [...u1, ...u2, ...u3];
+    }
     const speedUpload = stats.quartile(uploadTests, 0.9).toFixed(2);
 
     return {
@@ -49,8 +109,8 @@ export class CloudflareSpeed {
           measurements.push(response[4] - response[0] - response[6]);
         },
         (error) => {
-          console.log(`Error: ${error}`);
-        }
+          getLogger().error('Error measuring latency:', error);
+        },
       );
     }
 
@@ -73,8 +133,8 @@ export class CloudflareSpeed {
           measurements.push(await this.measureSpeed(bytes, transferTime));
         },
         (error) => {
-          console.log(`Error: ${error}`);
-        }
+          getLogger().error('Error measuring download chunk:', error);
+        },
       );
     }
 
@@ -91,8 +151,8 @@ export class CloudflareSpeed {
           measurements.push(await this.measureSpeed(bytes, transferTime));
         },
         (error) => {
-          console.log(`Error: ${error}`);
-        }
+          getLogger().error('Error measuring upload chunk:', error);
+        },
       );
     }
 
@@ -104,15 +164,17 @@ export class CloudflareSpeed {
   }
 
   public async fetchServerLocations(): Promise<{ [key: string]: string }> {
-    const res = JSON.parse(await this.get('speed.cloudflare.com', '/locations'));
-
-    return res.reduce((data: any, optionsArg: { iata: string; city: string }) => {
-      // Bypass prettier "no-assign-param" rules
-      const data1 = data;
-
-      data1[optionsArg.iata] = optionsArg.city;
-      return data1;
-    }, {});
+    const res = JSON.parse(await this.get('speed.cloudflare.com', '/locations')) as Array<{
+      iata: string;
+      city: string;
+    }>;
+    return res.reduce(
+      (data: Record<string, string>, optionsArg) => {
+        data[optionsArg.iata] = optionsArg.city;
+        return data;
+      },
+      {} as Record<string, string>,
+    );
   }
 
   public async get(hostname: string, path: string): Promise<string> {
@@ -122,6 +184,8 @@ export class CloudflareSpeed {
           hostname,
           path,
           method: 'GET',
+          // disable connection pooling to avoid listener accumulation
+          agent: false,
         },
         (res) => {
           const body: Array<Buffer> = [];
@@ -135,10 +199,10 @@ export class CloudflareSpeed {
               reject(e);
             }
           });
-          req.on('error', (err) => {
-            reject(err);
+          req.on('error', (err: Error & { code?: string }) => {
+            reject(new NetworkError(err.message, err.code));
           });
-        }
+        },
       );
 
       req.end();
@@ -179,7 +243,9 @@ export class CloudflareSpeed {
 
     return new Promise((resolve, reject) => {
       started = plugins.perfHooks.performance.now();
-      const req = plugins.https.request(options, (res) => {
+      // disable connection pooling to avoid listener accumulation across requests
+      const reqOptions = { ...options, agent: false };
+      const req = plugins.https.request(reqOptions, (res) => {
         res.once('readable', () => {
           ttfb = plugins.perfHooks.performance.now();
         });
@@ -193,25 +259,26 @@ export class CloudflareSpeed {
             sslHandshake,
             ttfb,
             ended,
-            parseFloat(res.headers['server-timing'].slice(22) as any),
+            parseFloat((res.headers['server-timing'] as string).slice(22)),
           ]);
         });
       });
 
-      req.on('socket', (socket) => {
-        socket.on('lookup', () => {
+      // Listen for timing events once per new socket
+      req.once('socket', (socket) => {
+        socket.once('lookup', () => {
           dnsLookup = plugins.perfHooks.performance.now();
         });
-        socket.on('connect', () => {
+        socket.once('connect', () => {
           tcpHandshake = plugins.perfHooks.performance.now();
         });
-        socket.on('secureConnect', () => {
+        socket.once('secureConnect', () => {
           sslHandshake = plugins.perfHooks.performance.now();
         });
       });
 
-      req.on('error', (error) => {
-        reject(error);
+      req.on('error', (error: Error & { code?: string }) => {
+        reject(new NetworkError(error.message, error.code));
       });
 
       req.write(data);
@@ -219,39 +286,25 @@ export class CloudflareSpeed {
     });
   }
 
-  public async fetchCfCdnCgiTrace(): Promise<{
-    fl: string;
-    h: string;
-    ip: string;
-    ts: string;
-    visit_scheme: string;
-    uag: string;
-    colo: string;
-    http: string;
-    loc: string;
-    tls: string;
-    sni: string;
-    warp: string;
-    gateway: string;
-  }> {
+  /**
+   * Fetch Cloudflare's trace endpoint and parse key=value lines to a record.
+   */
+  public async fetchCfCdnCgiTrace(): Promise<Record<string, string>> {
     const parseCfCdnCgiTrace = (text: string) =>
       text
         .split('\n')
         .map((i) => {
-          const j = i.split('=');
-
-          return [j[0], j[1]];
+          const parts = i.split('=');
+          return [parts[0], parts[1]];
         })
-        .reduce((data: any, [k, v]) => {
-          if (v === undefined) return data;
-
-          // Bypass prettier "no-assign-param" rules
-          const data1 = data;
-          // Object.fromEntries is only supported by Node.js 12 or newer
-          data1[k] = v;
-
-          return data1;
-        }, {});
+        .reduce(
+          (data: Record<string, string>, [k, v]) => {
+            if (v === undefined) return data;
+            data[k] = v;
+            return data;
+          },
+          {} as Record<string, string>,
+        );
 
     return this.get('speed.cloudflare.com', '/cdn-cgi/trace').then(parseCfCdnCgiTrace);
   }