@mark1russell7/netdiag 0.0.0-stage → 0.1.1

package/src/target.ts

@@ -0,0 +1,116 @@
+import { isIP } from "node:net";
+import { err, ok, type Result } from "@mark1russell7/optional";
+
+/** The kind of the host of a target: a DNS name, an IPv4 address or an IPv6 address. */
+export type HostKind = "name" | "ipv4" | "ipv6";
+
+/**
+ * A host that a probe examines, and an optional port.
+ *
+ * The host is in its canonical form: lower case, with no final dot and no brackets around an IPv6 address.
+ */
+export interface Target {
+  readonly host: string;
+  readonly kind: HostKind;
+  readonly port?: number | undefined;
+}
+
+/** The ports of the URL schemes that a target can have. */
+const SCHEME_PORTS: ReadonlyMap<string, number> = new Map([
+  ["http:", 80],
+  ["https:", 443],
+  ["ws:", 80],
+  ["wss:", 443],
+  ["dns:", 53],
+  ["tls:", 443],
+]);
+
+/** This function gives the kind of a host in its canonical form. */
+export function hostKind(host: string): HostKind {
+  const family = isIP(host);
+  if (family === 4) return "ipv4";
+  if (family === 6) return "ipv6";
+  return "name";
+}
+
+/** This function gives the canonical form of a host: lower case, with no final dot and no brackets. */
+export function canonicalHost(host: string): string {
+  let text = host.trim().toLowerCase();
+  if (text.startsWith("[") && text.endsWith("]")) text = text.slice(1, -1);
+  if (text.endsWith(".")) text = text.slice(0, -1);
+  return text;
+}
+
+/** This function makes a target from a host and an optional port. */
+export function target(host: string, port?: number): Target {
+  const canonical = canonicalHost(host);
+  return port === undefined ? { host: canonical, kind: hostKind(canonical) } : { host: canonical, kind: hostKind(canonical), port };
+}
+
+/** This function gives the text of a target: `host`, `host:port`, or `[address]:port` for an IPv6 address. */
+export function formatTarget(t: Target): string {
+  const host = t.kind === "ipv6" && t.port !== undefined ? `[${t.host}]` : t.host;
+  return t.port === undefined ? host : `${host}:${t.port}`;
+}
+
+/** This function tells if two targets have the same host and the same port. */
+export function sameTarget(a: Target, b: Target): boolean {
+  return a.host === b.host && a.port === b.port;
+}
+
+const LABEL = /^(?!-)[a-z0-9-]{1,63}(?<!-)$/;
+
+function validName(host: string): boolean {
+  if (host.length === 0 || host.length > 253) return false;
+  return host.split(".").every((label) => LABEL.test(label) || label === "_" || /^_[a-z0-9-]{1,62}$/.test(label));
+}
+
+function portOf(text: string): number | undefined {
+  if (!/^\d{1,5}$/.test(text)) return undefined;
+  const port = Number(text);
+  return port >= 1 && port <= 65535 ? port : undefined;
+}
+
+/**
+ * This function reads a target from the text that a user gives.
+ *
+ * It accepts a URL (`https://example.com/a`), a host (`example.com`) and a host with a port (`example.com:8443`).
+ * It also accepts an IPv4 address, and an IPv6 address in brackets with a port (`[2001:db8::1]:443`).
+ * A URL with a known scheme and no port gets the port of its scheme.
+ */
+export function parseTarget(text: string): Result<Target, string> {
+  const input = text.trim();
+  if (input.length === 0) return err("The target is empty.");
+  if (input.includes("://")) {
+    let url: URL;
+    try {
+      url = new URL(input);
+    } catch {
+      return err(`"${input}" is not a valid URL.`);
+    }
+    const host = canonicalHost(url.hostname);
+    if (host.length === 0) return err(`The URL "${input}" has no host.`);
+    const port = url.port === "" ? SCHEME_PORTS.get(url.protocol) : Number(url.port);
+    return checked(host, port, input);
+  }
+  if (isIP(input) === 6) return checked(canonicalHost(input), undefined, input);
+  const bracket = /^\[([^\]]+)\](?::(.*))?$/.exec(input);
+  if (bracket !== null) {
+    const host = bracket[1] ?? "";
+    if (isIP(host) !== 6) return err(`"${host}" is not an IPv6 address.`);
+    if (bracket[2] === undefined) return checked(canonicalHost(host), undefined, input);
+    const port = portOf(bracket[2]);
+    return port === undefined ? err(`"${bracket[2]}" is not a port from 1 to 65535.`) : checked(canonicalHost(host), port, input);
+  }
+  const colon = input.lastIndexOf(":");
+  if (colon === -1) return checked(canonicalHost(input), undefined, input);
+  const port = portOf(input.slice(colon + 1));
+  if (port === undefined) return err(`"${input.slice(colon + 1)}" is not a port from 1 to 65535.`);
+  return checked(canonicalHost(input.slice(0, colon)), port, input);
+}
+
+function checked(host: string, port: number | undefined, input: string): Result<Target, string> {
+  const kind = hostKind(host);
+  if (kind === "name" && !validName(host)) return err(`"${input}" has no valid host name.`);
+  return ok(port === undefined ? { host, kind } : { host, kind, port });
+}

package/src/tools/common.ts

@@ -0,0 +1,47 @@
+import { addressFamily, canonicalAddress, type AddressFamily } from "../address/index.ts";
+
+// The parts that the adapters share. The entry `@mark1russell7/netdiag/tools` does not export this module.
+
+/** The environment that makes the output of a tool English on Linux and macOS. */
+export const ENGLISH: Readonly<Record<string, string>> = { LC_ALL: "C" };
+
+/** The end of a line of output, on each operating system. */
+export const LINES: RegExp = /\r?\n/;
+
+/** The messages of a local send that tell that the address is unreachable, on Linux and macOS. */
+export const LOCAL_UNREACHABLE: RegExp = /\b(Network is unreachable|No route to host|Host is down|Network is down)\b/i;
+
+/** The IP address of a probe of an outside tool: its canonical form and its family. */
+export interface ToolAddress {
+  readonly address: string;
+  readonly family: AddressFamily;
+}
+
+/**
+ * This function gives the canonical form and the family of an IP address. It throws a `TypeError` for a name, because
+ * an adapter sends probes only to an address.
+ */
+export function toolAddress(address: string): ToolAddress {
+  const family = addressFamily(address);
+  if (family === undefined) throw new TypeError(`"${address}" is not an IP address. Get the addresses of a name with the DNS probe first.`);
+  return { address: canonicalAddress(address), family };
+}
+
+/** This function throws a `RangeError` when a value is not an integer from `min` to `max`. It gives the value. */
+export function integerIn(value: number, min: number, max: number, what: string): number {
+  if (!Number.isInteger(value) || value < min || value > max) throw new RangeError(`${value} is not ${what} from ${min} to ${max}.`);
+  return value;
+}
+
+/** This function tells if two IP addresses are the same address. */
+export function sameAddress(a: string, b: string): boolean {
+  return canonicalAddress(a) === canonicalAddress(b);
+}
+
+/** This function gives the first line of a text that is not empty, with no spaces at its ends. */
+export function firstLine(text: string): string | undefined {
+  return text
+    .split(LINES)
+    .find((line) => line.trim().length > 0)
+    ?.trim();
+}

package/src/tools/host.ts

@@ -0,0 +1,91 @@
+import type { Availability, ProbeContext } from "../probe.ts";
+
+/**
+ * The output of one command of an outside tool.
+ *
+ * The function `runCommand` of `@procedures/shell` gives this shape, so it is a host with no change (refer to the README).
+ */
+export interface ToolOutput {
+  /** The exit code of the program. */
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  /** This field is true when the time limit stopped the program. */
+  readonly timedOut?: boolean | undefined;
+  /** The error that kept the program from its start, for example `spawn ping ENOENT`. */
+  readonly error?: string | undefined;
+}
+
+/** The options of one command. */
+export interface ToolRunOptions {
+  /** The time limit of the command, in milliseconds. After the limit, the host stops the program. */
+  readonly timeoutMs: number;
+  readonly signal: AbortSignal;
+  /** The environment variables to add to the environment of the program, for example `LC_ALL=C` for English output. */
+  readonly env?: Readonly<Record<string, string>> | undefined;
+}
+
+/**
+ * The host of the outside tools: the operating system, and the function that starts a program.
+ *
+ * - `platform` has the values of `process.platform`, for example `linux`, `darwin` or `win32`.
+ * - `run` starts a program with a list of arguments and no shell. It does not throw. A failure is in the output.
+ */
+export interface ToolHost {
+  readonly platform: string;
+  run(command: string, args: readonly string[], options: ToolRunOptions): Promise<ToolOutput>;
+}
+
+/** The raw output of a probe of an outside tool: the command, its output, and the times on the clock of the runner. */
+export interface ToolRaw extends ToolOutput {
+  readonly platform: string;
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly start: number;
+  readonly end: number;
+}
+
+/** The time limit of the command that examines if a tool is available, in milliseconds. */
+export const AVAILABILITY_TIMEOUT_MS = 5000;
+
+/** The time that an adapter adds to the time limit of a command, in milliseconds. In this time, a tool writes its last lines. */
+export const TOOL_MARGIN_MS = 3000;
+
+/**
+ * This function gives the availability of a tool from the output of a harmless command. A tool is available when its
+ * program starts. The first group of `version` gives the version of the tool.
+ */
+export function availabilityOf(tool: string, output: ToolOutput, version?: RegExp): Availability {
+  if (output.error !== undefined) return { available: false, reason: `The tool ${tool} does not start: ${output.error}` };
+  const found = version?.exec(`${output.stdout}\n${output.stderr}`)?.[1];
+  return found === undefined ? { available: true } : { available: true, version: found };
+}
+
+/** A command of an outside tool: the program, its arguments, its time limit and the environment variables to add. */
+export interface ToolCommand {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly timeoutMs: number;
+  readonly env?: Readonly<Record<string, string>> | undefined;
+}
+
+/** This function starts a command on the host, and gives its raw output with the times of the clock of the runner. */
+export async function runTool(host: ToolHost, tool: ToolCommand, context: ProbeContext): Promise<ToolRaw> {
+  const { command, args, timeoutMs, env } = tool;
+  const start = context.clock.now();
+  const output = await host.run(command, args, env === undefined ? { timeoutMs, signal: context.signal } : { timeoutMs, signal: context.signal, env });
+  const end = context.clock.now();
+  context.signal.throwIfAborted();
+  return {
+    platform: host.platform,
+    command,
+    args: [...args],
+    start,
+    end,
+    exitCode: output.exitCode,
+    stdout: output.stdout,
+    stderr: output.stderr,
+    ...(output.timedOut === true ? { timedOut: true } : {}),
+    ...(output.error === undefined ? {} : { error: output.error }),
+  };
+}

package/src/tools/index.ts

@@ -0,0 +1,38 @@
+// The entry `@mark1russell7/netdiag/tools`: the adapters of outside tools. netdiag bundles no tool. The host starts each
+// tool with a list of arguments and no shell.
+export {
+  AVAILABILITY_TIMEOUT_MS,
+  availabilityOf,
+  runTool,
+  TOOL_MARGIN_MS,
+  type ToolCommand,
+  type ToolHost,
+  type ToolOutput,
+  type ToolRaw,
+  type ToolRunOptions,
+} from "./host.ts";
+export { TOOL_LICENSES, toolLicense, type ToolLicense, type ToolUse } from "./licenses.ts";
+export {
+  DEFAULT_PING_COUNT,
+  DEFAULT_PING_WAIT_MS,
+  MAX_PING_COUNT,
+  PING6_LAST_WAIT_MS,
+  PING_INTERVAL_MS,
+  pingAvailability,
+  pingCommand,
+  pingProbe,
+  readPing,
+  type PingInput,
+} from "./ping.ts";
+export {
+  DEFAULT_TRACE_HOPS,
+  DEFAULT_TRACE_WAIT_MS,
+  MAX_TRACE_HOPS,
+  TRACE_QUERIES,
+  readTraceroute,
+  tracerouteAvailability,
+  tracerouteCommand,
+  tracerouteProbe,
+  type TraceInput,
+} from "./traceroute.ts";
+export { DEFAULT_MTR_CYCLES, MAX_MTR_CYCLES, MTR_GRACE_MS, mtrAvailability, mtrCommand, mtrProbe, readMtr, type MtrInput } from "./mtr.ts";

package/src/tools/licenses.ts

@@ -0,0 +1,37 @@
+/**
+ * The use of an outside tool in netdiag.
+ *
+ * - `adapter`: netdiag has an optional adapter. The user installs the tool, and netdiag starts it when it is available.
+ * - `not-bundled`: netdiag does not start the tool, because its license is restrictive.
+ */
+export type ToolUse = "adapter" | "not-bundled";
+
+/** A row of the table of the licenses of the outside tools. */
+export interface ToolLicense {
+  /** The name of the program, for example `ping`. */
+  readonly tool: string;
+  readonly license: string;
+  readonly use: ToolUse;
+  /** The id of the probe of the adapter. A planned adapter has no probe yet. */
+  readonly probe?: string | undefined;
+}
+
+/**
+ * The licenses of the outside tools, as data. netdiag bundles no tool. A test makes sure that the probe of each adapter
+ * has a row with the use `adapter`.
+ */
+export const TOOL_LICENSES: readonly ToolLicense[] = [
+  { tool: "ping", license: "The license of the operating system", use: "adapter", probe: "icmp.ping" },
+  { tool: "traceroute", license: "GPL on Linux", use: "adapter", probe: "path.traceroute" },
+  { tool: "mtr", license: "GPL", use: "adapter", probe: "path.mtr" },
+  { tool: "tshark", license: "GPL", use: "adapter" },
+  { tool: "iperf3", license: "BSD", use: "adapter" },
+  { tool: "nmap", license: "NPSL", use: "not-bundled" },
+  { tool: "masscan", license: "AGPL", use: "not-bundled" },
+  { tool: "speedtest", license: "Ookla EULA", use: "not-bundled" },
+];
+
+/** This function gives the row of a tool, or `undefined` for a tool that is not in the table. */
+export function toolLicense(tool: string): ToolLicense | undefined {
+  return TOOL_LICENSES.find((row) => row.tool === tool);
+}

package/src/tools/mtr.ts

@@ -0,0 +1,156 @@
+import { observe, type Observation } from "../fact.ts";
+import { PATH_REPORT, type PathReport, type ReportHop } from "../kinds.ts";
+import { defineProbe, type Availability, type Probe, type ProbeContext } from "../probe.ts";
+import { target, type Target } from "../target.ts";
+import { ENGLISH, firstLine, integerIn, sameAddress, toolAddress, type ToolAddress } from "./common.ts";
+import { AVAILABILITY_TIMEOUT_MS, availabilityOf, runTool, TOOL_MARGIN_MS, type ToolCommand, type ToolHost, type ToolRaw } from "./host.ts";
+import { DEFAULT_TRACE_HOPS, MAX_TRACE_HOPS } from "./traceroute.ts";
+
+// The adapter of the tool mtr. It reads the JSON report of `mtr --json` (mtr 0.92 or later) on Linux and macOS. mtr
+// sends one cycle of probes each second. A user without privileges cannot set a shorter interval.
+
+/** The input of the mtr probe: many cycles of probes on the path to one IP address. */
+export interface MtrInput {
+  readonly address: string;
+  /** The number of cycles. The default is `DEFAULT_MTR_CYCLES`. */
+  readonly cycles?: number | undefined;
+  /** The largest TTL. The default is `DEFAULT_TRACE_HOPS`. */
+  readonly maxHops?: number | undefined;
+}
+
+/** The default number of cycles. It is `LOSS_MIN_SENT` of the readers, so a report gives the feature `path.loss`. */
+export const DEFAULT_MTR_CYCLES = 20;
+
+/** The largest number of cycles of one input. */
+export const MAX_MTR_CYCLES = 100;
+
+/** The time that mtr waits for the last answers after the last cycle, in milliseconds (its option `--gracetime`). */
+export const MTR_GRACE_MS = 5000;
+
+interface CheckedInput extends ToolAddress {
+  readonly cycles: number;
+  readonly maxHops: number;
+}
+
+function checked(input: MtrInput): CheckedInput {
+  return {
+    ...toolAddress(input.address),
+    cycles: integerIn(input.cycles ?? DEFAULT_MTR_CYCLES, 1, MAX_MTR_CYCLES, "a number of cycles"),
+    maxHops: integerIn(input.maxHops ?? DEFAULT_TRACE_HOPS, 1, MAX_TRACE_HOPS, "a number of hops"),
+  };
+}
+
+/**
+ * This function gives the command of mtr for an operating system and an input. On Windows and on an operating system
+ * that the adapter does not know, it gives `undefined`. It throws for an input that is not valid.
+ */
+export function mtrCommand(platform: string, input: MtrInput): ToolCommand | undefined {
+  const { address, family, cycles, maxHops } = checked(input);
+  if (platform !== "linux" && platform !== "darwin") return undefined;
+  return {
+    command: "mtr",
+    args: ["--json", "--no-dns", family === "ipv6" ? "-6" : "-4", "-c", String(cycles), "-m", String(maxHops), address],
+    timeoutMs: cycles * 1000 + MTR_GRACE_MS + TOOL_MARGIN_MS,
+    env: ENGLISH,
+  };
+}
+
+/** This function tells if mtr is available on the host. The adapter knows Linux and macOS. */
+export async function mtrAvailability(host: ToolHost, context: ProbeContext): Promise<Availability> {
+  if (host.platform !== "linux" && host.platform !== "darwin") return { available: false, reason: `netdiag starts mtr only on Linux and macOS, not on ${host.platform}.` };
+  const output = await host.run("mtr", ["--version"], { timeoutMs: AVAILABILITY_TIMEOUT_MS, signal: context.signal, env: ENGLISH });
+  return availabilityOf("mtr", output, /mtr (\d[\d.]*)/);
+}
+
+function finite(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+/** This function reads one hub of the JSON report, or gives `undefined` when netdiag cannot read it. */
+function readHub(hub: unknown): ReportHop | undefined {
+  if (typeof hub !== "object" || hub === null) return undefined;
+  const record = hub as Readonly<Record<string, unknown>>;
+  // mtr 0.92 writes the count as a text, and mtr 0.93 and later as a number.
+  const ttl = Number(record["count"]);
+  const sent = record["Snt"];
+  const loss = finite(record["Loss%"]);
+  const host = record["host"];
+  if (!Number.isInteger(ttl) || ttl < 1 || typeof sent !== "number" || !Number.isInteger(sent) || sent < 0 || loss === undefined || loss > 100) return undefined;
+  if (typeof host !== "string") return undefined;
+  const received = sent - Math.round((sent * loss) / 100);
+  // mtr writes "???" for a hop with no answer.
+  if (host === "???") return received === 0 ? { ttl, sent, received } : undefined;
+  if (received === 0) return { ttl, address: host, sent, received };
+  const times = { bestMs: finite(record["Best"]), meanMs: finite(record["Avg"]), worstMs: finite(record["Wrst"]) };
+  return {
+    ttl,
+    address: host,
+    sent,
+    received,
+    ...(times.bestMs === undefined ? {} : { bestMs: times.bestMs }),
+    ...(times.meanMs === undefined ? {} : { meanMs: times.meanMs }),
+    ...(times.worstMs === undefined ? {} : { worstMs: times.worstMs }),
+  };
+}
+
+/** This function gives the hubs of the JSON report of mtr, or `undefined` when the text is not such a report. */
+function hubsOf(text: string): readonly unknown[] | undefined {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (typeof parsed !== "object" || parsed === null) return undefined;
+    const report = (parsed as { readonly report?: unknown }).report;
+    if (typeof report !== "object" || report === null) return undefined;
+    const hubs = (report as { readonly hubs?: unknown }).hubs;
+    return Array.isArray(hubs) ? hubs : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * This function reads the raw output of the mtr probe into the value of a fact `path.report`.
+ *
+ * - The number of answers of a hop comes from its loss and its number of probes.
+ * - Output that netdiag cannot read gives the outcome `error`.
+ */
+export function readMtr(raw: ToolRaw, input: { readonly address: string; readonly cycles?: number | undefined }): PathReport {
+  const { address } = input;
+  const cycles = input.cycles ?? DEFAULT_MTR_CYCLES;
+  const error = (detail: string): PathReport => ({ address, outcome: "error", cycles, hops: [], detail });
+  if (raw.error !== undefined) return error(raw.error);
+  if (raw.timedOut === true) return error("The time limit stopped mtr before its report.");
+  const hubs = hubsOf(raw.stdout);
+  if (hubs === undefined) return error(firstLine(raw.stderr) ?? "netdiag cannot read the JSON report of mtr.");
+  const hops: ReportHop[] = [];
+  for (const hub of hubs) {
+    const hop = readHub(hub);
+    if (hop === undefined) return error(`netdiag cannot read the hub ${hops.length + 1} of the report of mtr.`);
+    if (hop.ttl <= (hops.at(-1)?.ttl ?? 0)) return error(`The hubs of the report of mtr are not in the order of their TTL.`);
+    hops.push(hop);
+  }
+  const last = hops.at(-1);
+  if (last === undefined) return error(firstLine(raw.stderr) ?? "The report of mtr has no hub.");
+  const reached = last.address !== undefined && last.received > 0 && sameAddress(last.address, address);
+  return { address, outcome: reached ? "reached" : "stopped", cycles, hops };
+}
+
+/** This function makes the probe `path.mtr`: many cycles of probes on the path to one IP address with the tool mtr. */
+export function mtrProbe(host: ToolHost): Probe<MtrInput, ToolRaw> {
+  return defineProbe<MtrInput, ToolRaw>({
+    id: "path.mtr",
+    version: "1",
+    summary: "The loss and the round-trip times of each hop of the path to one IP address, from the tool mtr.",
+    layer: "path",
+    mode: "active",
+    kinds: [PATH_REPORT],
+    tool: "mtr",
+    peers: (input): readonly Target[] => [target(checked(input).address)],
+    available: (context) => mtrAvailability(host, context),
+    async run(input, context) {
+      const command = mtrCommand(host.platform, input);
+      if (command === undefined) throw new Error(`netdiag has no command of mtr for ${host.platform}.`);
+      return runTool(host, command, context);
+    },
+    parse: (raw, input): readonly Observation[] => [observe(PATH_REPORT, target(input.address), readMtr(raw, input), { start: raw.start, end: raw.end })],
+  });
+}