@mark1russell7/netdiag 0.1.0 → 0.1.1

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 })],
+  });
+}

package/src/tools/ping.ts

@@ -0,0 +1,231 @@
+import { isIP } from "node:net";
+import { observe, type Observation } from "../fact.ts";
+import { ICMP_ECHO, type IcmpEcho } 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, LINES, LOCAL_UNREACHABLE, toolAddress, type ToolAddress } from "./common.ts";
+import { AVAILABILITY_TIMEOUT_MS, availabilityOf, runTool, TOOL_MARGIN_MS, type ToolCommand, type ToolHost, type ToolRaw } from "./host.ts";
+
+// The adapter of the tool `ping`. It reads the English output of iputils on Linux, of the BSD ping on macOS and of
+// ping.exe on Windows. On Linux and macOS, `LC_ALL=C` makes the output English. On Windows, the language of the
+// system sets the language of the output, so netdiag cannot read the output of a system in another language.
+
+/** The input of the ping probe: echo requests to one IP address. */
+export interface PingInput {
+  readonly address: string;
+  /** The number of echo requests. The default is `DEFAULT_PING_COUNT`. */
+  readonly count?: number | undefined;
+  /** The time to wait for each reply, in milliseconds. The default is `DEFAULT_PING_WAIT_MS`. */
+  readonly waitMs?: number | undefined;
+}
+
+/** The default number of echo requests. The feature `path.loss` needs `LOSS_MIN_SENT` requests or more. */
+export const DEFAULT_PING_COUNT = 4;
+
+/** The default time to wait for each reply, in milliseconds. */
+export const DEFAULT_PING_WAIT_MS = 1000;
+
+/** The largest number of echo requests in one input. */
+export const MAX_PING_COUNT = 100;
+
+/** The time between two echo requests on Linux and macOS, in milliseconds. A user without privileges can set it. */
+export const PING_INTERVAL_MS = 200;
+
+/**
+ * The time that the `ping6` of macOS waits after its last request when a reply is missing, in milliseconds. The tool
+ * has no option for it.
+ */
+export const PING6_LAST_WAIT_MS = 10_000;
+
+interface CheckedInput extends ToolAddress {
+  readonly count: number;
+  readonly waitMs: number;
+}
+
+function checked(input: PingInput): CheckedInput {
+  return {
+    ...toolAddress(input.address),
+    count: integerIn(input.count ?? DEFAULT_PING_COUNT, 1, MAX_PING_COUNT, "a number of requests"),
+    waitMs: integerIn(input.waitMs ?? DEFAULT_PING_WAIT_MS, 1, 60_000, "a time in milliseconds"),
+  };
+}
+
+/**
+ * This function gives the command of ping for an operating system and an input. For an operating system that the adapter
+ * does not know, it gives `undefined`. It throws for an input that is not valid.
+ *
+ * - Linux: iputils `ping`, with a deadline (`-w`) in seconds, so that ping writes its statistics.
+ * - macOS: `ping` with a deadline (`-t`), and `ping6` for an IPv6 address.
+ * - Windows: `ping.exe`. It sends one request each second.
+ */
+export function pingCommand(platform: string, input: PingInput): ToolCommand | undefined {
+  const { address, family, count, waitMs } = checked(input);
+  const interval = (count - 1) * PING_INTERVAL_MS;
+  const deadlineS = Math.ceil((interval + waitMs) / 1000) + 1;
+  const seconds = (ms: number): string => String(ms / 1000);
+  switch (platform) {
+    case "linux":
+      return {
+        command: "ping",
+        args: ["-n", "-c", String(count), "-i", seconds(PING_INTERVAL_MS), "-W", String(Math.ceil(waitMs / 1000)), "-w", String(deadlineS), address],
+        timeoutMs: deadlineS * 1000 + TOOL_MARGIN_MS,
+        env: ENGLISH,
+      };
+    case "darwin":
+      return family === "ipv4"
+        ? {
+            command: "ping",
+            args: ["-n", "-c", String(count), "-i", seconds(PING_INTERVAL_MS), "-W", String(waitMs), "-t", String(deadlineS), address],
+            timeoutMs: deadlineS * 1000 + TOOL_MARGIN_MS,
+            env: ENGLISH,
+          }
+        : { command: "ping6", args: ["-n", "-c", String(count), address], timeoutMs: (count - 1) * 1000 + PING6_LAST_WAIT_MS + TOOL_MARGIN_MS, env: ENGLISH };
+    case "win32":
+      return { command: "ping", args: ["-n", String(count), "-w", String(waitMs), address], timeoutMs: count * Math.max(1000, waitMs) + waitMs + TOOL_MARGIN_MS };
+    default:
+      return undefined;
+  }
+}
+
+/** The command that examines if ping is available on each operating system, and the pattern of its version. */
+const AVAILABILITY: Readonly<Record<string, { readonly args: readonly string[]; readonly version?: RegExp }>> = {
+  linux: { args: ["-V"], version: /iputils\D*(\d+)/i },
+  darwin: { args: [] },
+  win32: { args: ["/?"] },
+};
+
+/** This function tells if ping is available on the host. On Linux, netdiag reads only the ping of iputils. */
+export async function pingAvailability(host: ToolHost, context: ProbeContext): Promise<Availability> {
+  const check = AVAILABILITY[host.platform];
+  if (check === undefined) return { available: false, reason: `netdiag reads the output of ping only on Linux, macOS and Windows, not on ${host.platform}.` };
+  const output = await host.run("ping", check.args, { timeoutMs: AVAILABILITY_TIMEOUT_MS, signal: context.signal, env: ENGLISH });
+  if (host.platform === "linux" && output.error === undefined && !/iputils/i.test(`${output.stdout}\n${output.stderr}`)) {
+    return { available: false, reason: "netdiag reads only the ping of iputils on Linux. This ping does not tell an iputils version." };
+  }
+  return availabilityOf("ping", output, check.version);
+}
+
+/** The replies and the messages that netdiag reads in the output of ping. */
+interface PingLines {
+  /** The number of requests from the statistics. Without statistics, netdiag cannot read the output. */
+  readonly sent?: number | undefined;
+  readonly replies: readonly { readonly rttMs: number; readonly ttl?: number | undefined }[];
+  readonly unreachable?: { readonly from?: string | undefined; readonly detail: string } | undefined;
+  /** A failure of this computer to send a request, for example a firewall rule. */
+  readonly failure?: string | undefined;
+}
+
+/** The messages of a failed send of ping on Linux and macOS, for example `socket: Operation not permitted`. */
+const SEND_FAILURE = /^(?:socket|bind|connect|sendmsg|sendto|send): \S/;
+
+function readUnix(stdout: string, stderr: string): PingLines {
+  const replies: { rttMs: number; ttl?: number }[] = [];
+  let unreachable: PingLines["unreachable"];
+  let failure: string | undefined;
+  for (const line of stdout.split(LINES)) {
+    // Each pattern has one way to match, so a long line cannot make it slow. A second test examines the rest of the line.
+    // iputils: "From 192.0.2.5 icmp_seq=1 Destination Host Unreachable". macOS: "92 bytes from 192.0.2.5: Destination Host Unreachable".
+    const head = /^\d+ bytes from (\S+) (.*)$/.exec(line) ?? /^From (\S+) icmp_seq=\d+ (.*)$/.exec(line);
+    if (head === null) continue;
+    const from = withoutSeparator(head[1] ?? "");
+    const rest = head[2] ?? "";
+    const time = line.startsWith("From ") ? null : /\btime[=<]([\d.]+) ?ms/.exec(rest);
+    if (time !== null) {
+      if (rest.includes("DUP!")) continue;
+      const ttl = /\b(?:ttl|hlim)=(\d+)/.exec(rest)?.[1];
+      replies.push(ttl === undefined ? { rttMs: Number(time[1]) } : { rttMs: Number(time[1]), ttl: Number(ttl) });
+    } else if (/unreachable/i.test(rest) && unreachable === undefined) {
+      unreachable = { from, detail: rest.trim() };
+    }
+  }
+  // A warning on stderr is not a failure. Only a failed send is a failure.
+  for (const line of stderr.split(LINES)) {
+    const text = line.replace(/^ping6?:\s*/, "").trim();
+    const local = LOCAL_UNREACHABLE.exec(text);
+    if (local !== null) unreachable ??= { detail: local[1] ?? text };
+    else if (SEND_FAILURE.test(text)) failure ??= text;
+  }
+  const sent = /^(\d+) packets transmitted, \d+ (?:packets )?received/m.exec(stdout)?.[1];
+  return { sent: sent === undefined ? undefined : Number(sent), replies, unreachable, failure };
+}
+
+/** This function removes the `:` or `,` after an address in a line of ping. An IPv6 address keeps its own last `:`. */
+function withoutSeparator(text: string): string {
+  return isIP(text) === 0 ? text.replace(/[:,]$/, "") : text;
+}
+
+function readWindows(stdout: string): PingLines {
+  const replies: { rttMs: number; ttl?: number }[] = [];
+  let unreachable: PingLines["unreachable"];
+  let failure: string | undefined;
+  for (const line of stdout.split(LINES)) {
+    // "Reply from 192.0.2.1: bytes=32 time=12ms TTL=118". IPv6 has no bytes and no TTL. "time<1ms" counts as 1 ms.
+    const reply = /^Reply from (\S+?): (?:bytes=\d+ )?time([=<])(\d+)ms(?: TTL=(\d+))?/.exec(line);
+    if (reply !== null) {
+      const ttl = reply[4];
+      replies.push(ttl === undefined ? { rttMs: Number(reply[3]) } : { rttMs: Number(reply[3]), ttl: Number(ttl) });
+      continue;
+    }
+    // "Reply from 192.168.1.191: Destination host unreachable." or "Destination net unreachable."
+    const text = line.trim();
+    const message = /^(?:Reply from (\S+): )?(Destination .*)$/i.exec(text);
+    if (message !== null && unreachable === undefined && /unreachable\.?$/i.test(message[2] ?? "")) {
+      const detail = (message[2] ?? "").replace(/\.$/, "");
+      unreachable = message[1] === undefined ? { detail } : { from: message[1], detail };
+    }
+    if (text.startsWith("PING: transmit failed. ")) failure ??= text.slice("PING: ".length);
+  }
+  const sent = /Packets: Sent = (\d+), Received = \d+/.exec(stdout)?.[1];
+  return { sent: sent === undefined ? undefined : Number(sent), replies, unreachable, failure };
+}
+
+/**
+ * This function reads the raw output of the ping probe into the value of a fact `icmp.echo`.
+ *
+ * - The replies are the lines of echo replies. A message of an unreachable address and a duplicate are not replies.
+ * - Output with no statistics gives the outcome `error`, also when it has replies. The time limit stopped such a ping.
+ */
+export function readPing(raw: ToolRaw, address: string): IcmpEcho {
+  const error = (detail: string): IcmpEcho => ({ address, outcome: "error", sent: 0, received: 0, rttMs: [], detail });
+  if (raw.error !== undefined) return error(raw.error);
+  const lines = raw.platform === "win32" ? readWindows(raw.stdout) : readUnix(raw.stdout, raw.stderr);
+  const { sent, replies, unreachable, failure } = lines;
+  const from = unreachable?.from === undefined ? {} : { from: unreachable.from };
+  if (sent === undefined) {
+    if (unreachable !== undefined && raw.timedOut !== true) return { address, outcome: "unreachable", sent: 0, received: 0, rttMs: [], ...from, detail: unreachable.detail };
+    if (raw.timedOut === true) return error("The time limit stopped ping before its statistics.");
+    return error(failure ?? firstLine(raw.stderr) ?? "netdiag cannot read the output of ping. netdiag reads only English output.");
+  }
+  if (replies.length > sent) return error(`The output of ping has ${replies.length} replies to ${sent} requests.`);
+  const first = replies[0];
+  if (first !== undefined) {
+    return { address, outcome: "reply", sent, received: replies.length, rttMs: replies.map((r) => r.rttMs), ...(first.ttl === undefined ? {} : { ttl: first.ttl }) };
+  }
+  if (unreachable !== undefined) return { address, outcome: "unreachable", sent, received: 0, rttMs: [], ...from, detail: unreachable.detail };
+  if (failure !== undefined) return error(failure);
+  return { address, outcome: "none", sent, received: 0, rttMs: [] };
+}
+
+/**
+ * This function makes the probe `icmp.ping`: the echo requests of the tool ping to one IP address. The host starts
+ * the tool. Give `runCommand` of `@procedures/shell`, or a fake host in a test.
+ */
+export function pingProbe(host: ToolHost): Probe<PingInput, ToolRaw> {
+  return defineProbe<PingInput, ToolRaw>({
+    id: "icmp.ping",
+    version: "1",
+    summary: "The ICMP echo requests of the tool ping to one IP address.",
+    layer: "ip",
+    mode: "active",
+    kinds: [ICMP_ECHO],
+    tool: "ping",
+    peers: (input): readonly Target[] => [target(checked(input).address)],
+    available: (context) => pingAvailability(host, context),
+    async run(input, context) {
+      const command = pingCommand(host.platform, input);
+      if (command === undefined) throw new Error(`netdiag has no command of ping for ${host.platform}.`);
+      return runTool(host, command, context);
+    },
+    parse: (raw, input): readonly Observation[] => [observe(ICMP_ECHO, target(input.address), readPing(raw, input.address), { start: raw.start, end: raw.end })],
+  });
+}