@mark1russell7/netdiag 0.1.0 → 0.1.1

package/build/tools.js

@@ -0,0 +1,896 @@
+import { C as observe, d as PATH_REPORT, f as PATH_TRACE, k as target, l as ICMP_ECHO, y as defineProbe } from "./kinds-CQv769lK.js";
+import { addressFamily, canonicalAddress } from "./address.js";
+import { isIP } from "node:net";
+// src/tools/host.ts
+/** The time limit of the command that examines if a tool is available, in milliseconds. */
+const AVAILABILITY_TIMEOUT_MS = 5e3;
+/** The time that an adapter adds to the time limit of a command, in milliseconds. In this time, a tool writes its last lines. */
+const TOOL_MARGIN_MS = 3e3;
+/**
+* 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.
+*/
+function availabilityOf(tool, output, version) {
+	if (output.error !== void 0) return {
+		available: false,
+		reason: `The tool ${tool} does not start: ${output.error}`
+	};
+	const found = version?.exec(`${output.stdout}\n${output.stderr}`)?.[1];
+	return found === void 0 ? { available: true } : {
+		available: true,
+		version: found
+	};
+}
+/** This function starts a command on the host, and gives its raw output with the times of the clock of the runner. */
+async function runTool(host, tool, context) {
+	const { command, args, timeoutMs, env } = tool;
+	const start = context.clock.now();
+	const output = await host.run(command, args, env === void 0 ? {
+		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 === void 0 ? {} : { error: output.error }
+	};
+}
+// src/tools/licenses.ts
+/**
+* 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`.
+*/
+const TOOL_LICENSES = [
+	{
+		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. */
+function toolLicense(tool) {
+	return TOOL_LICENSES.find((row) => row.tool === tool);
+}
+// src/tools/common.ts
+/** The environment that makes the output of a tool English on Linux and macOS. */
+const ENGLISH = { LC_ALL: "C" };
+/** The end of a line of output, on each operating system. */
+const LINES = /\r?\n/;
+/** The messages of a local send that tell that the address is unreachable, on Linux and macOS. */
+const LOCAL_UNREACHABLE = /\b(Network is unreachable|No route to host|Host is down|Network is down)\b/i;
+/**
+* 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.
+*/
+function toolAddress(address) {
+	const family = addressFamily(address);
+	if (family === void 0) 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. */
+function integerIn(value, min, max, what) {
+	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. */
+function sameAddress(a, b) {
+	return canonicalAddress(a) === canonicalAddress(b);
+}
+/** This function gives the first line of a text that is not empty, with no spaces at its ends. */
+function firstLine(text) {
+	return text.split(LINES).find((line) => line.trim().length > 0)?.trim();
+}
+// src/tools/ping.ts
+/** The default number of echo requests. The feature `path.loss` needs `LOSS_MIN_SENT` requests or more. */
+const DEFAULT_PING_COUNT = 4;
+/** The default time to wait for each reply, in milliseconds. */
+const DEFAULT_PING_WAIT_MS = 1e3;
+/** The largest number of echo requests in one input. */
+const MAX_PING_COUNT = 100;
+/** The time between two echo requests on Linux and macOS, in milliseconds. A user without privileges can set it. */
+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.
+*/
+const PING6_LAST_WAIT_MS = 1e4;
+function checked$2(input) {
+	return {
+		...toolAddress(input.address),
+		count: integerIn(input.count ?? 4, 1, 100, "a number of requests"),
+		waitMs: integerIn(input.waitMs ?? 1e3, 1, 6e4, "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.
+*/
+function pingCommand(platform, input) {
+	const { address, family, count, waitMs } = checked$2(input);
+	const interval = (count - 1) * 200;
+	const deadlineS = Math.ceil((interval + waitMs) / 1e3) + 1;
+	const seconds = (ms) => String(ms / 1e3);
+	switch (platform) {
+		case "linux": return {
+			command: "ping",
+			args: [
+				"-n",
+				"-c",
+				String(count),
+				"-i",
+				seconds(200),
+				"-W",
+				String(Math.ceil(waitMs / 1e3)),
+				"-w",
+				String(deadlineS),
+				address
+			],
+			timeoutMs: deadlineS * 1e3 + TOOL_MARGIN_MS,
+			env: ENGLISH
+		};
+		case "darwin": return family === "ipv4" ? {
+			command: "ping",
+			args: [
+				"-n",
+				"-c",
+				String(count),
+				"-i",
+				seconds(200),
+				"-W",
+				String(waitMs),
+				"-t",
+				String(deadlineS),
+				address
+			],
+			timeoutMs: deadlineS * 1e3 + TOOL_MARGIN_MS,
+			env: ENGLISH
+		} : {
+			command: "ping6",
+			args: [
+				"-n",
+				"-c",
+				String(count),
+				address
+			],
+			timeoutMs: (count - 1) * 1e3 + 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(1e3, waitMs) + waitMs + TOOL_MARGIN_MS
+		};
+		default: return;
+	}
+}
+/** The command that examines if ping is available on each operating system, and the pattern of its version. */
+const AVAILABILITY$1 = {
+	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. */
+async function pingAvailability(host, context) {
+	const check = AVAILABILITY$1[host.platform];
+	if (check === void 0) 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 === void 0 && !/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 messages of a failed send of ping on Linux and macOS, for example `socket: Operation not permitted`. */
+const SEND_FAILURE$1 = /^(?:socket|bind|connect|sendmsg|sendto|send): \S/;
+function readUnix$1(stdout, stderr) {
+	const replies = [];
+	let unreachable;
+	let failure;
+	for (const line of stdout.split(LINES)) {
+		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 === void 0 ? { rttMs: Number(time[1]) } : {
+				rttMs: Number(time[1]),
+				ttl: Number(ttl)
+			});
+		} else if (/unreachable/i.test(rest) && unreachable === void 0) unreachable = {
+			from,
+			detail: rest.trim()
+		};
+	}
+	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$1.test(text)) failure ??= text;
+	}
+	const sent = /^(\d+) packets transmitted, \d+ (?:packets )?received/m.exec(stdout)?.[1];
+	return {
+		sent: sent === void 0 ? void 0 : 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) {
+	return isIP(text) === 0 ? text.replace(/[:,]$/, "") : text;
+}
+function readWindows$1(stdout) {
+	const replies = [];
+	let unreachable;
+	let failure;
+	for (const line of stdout.split(LINES)) {
+		const reply = /^Reply from (\S+?): (?:bytes=\d+ )?time([=<])(\d+)ms(?: TTL=(\d+))?/.exec(line);
+		if (reply !== null) {
+			const ttl = reply[4];
+			replies.push(ttl === void 0 ? { rttMs: Number(reply[3]) } : {
+				rttMs: Number(reply[3]),
+				ttl: Number(ttl)
+			});
+			continue;
+		}
+		const text = line.trim();
+		const message = /^(?:Reply from (\S+): )?(Destination .*)$/i.exec(text);
+		if (message !== null && unreachable === void 0 && /unreachable\.?$/i.test(message[2] ?? "")) {
+			const detail = (message[2] ?? "").replace(/\.$/, "");
+			unreachable = message[1] === void 0 ? { detail } : {
+				from: message[1],
+				detail
+			};
+		}
+		if (text.startsWith("PING: transmit failed. ")) failure ??= text.slice(6);
+	}
+	const sent = /Packets: Sent = (\d+), Received = \d+/.exec(stdout)?.[1];
+	return {
+		sent: sent === void 0 ? void 0 : 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.
+*/
+function readPing(raw, address) {
+	const error = (detail) => ({
+		address,
+		outcome: "error",
+		sent: 0,
+		received: 0,
+		rttMs: [],
+		detail
+	});
+	if (raw.error !== void 0) return error(raw.error);
+	const { sent, replies, unreachable, failure } = raw.platform === "win32" ? readWindows$1(raw.stdout) : readUnix$1(raw.stdout, raw.stderr);
+	const from = unreachable?.from === void 0 ? {} : { from: unreachable.from };
+	if (sent === void 0) {
+		if (unreachable !== void 0 && 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 !== void 0) return {
+		address,
+		outcome: "reply",
+		sent,
+		received: replies.length,
+		rttMs: replies.map((r) => r.rttMs),
+		...first.ttl === void 0 ? {} : { ttl: first.ttl }
+	};
+	if (unreachable !== void 0) return {
+		address,
+		outcome: "unreachable",
+		sent,
+		received: 0,
+		rttMs: [],
+		...from,
+		detail: unreachable.detail
+	};
+	if (failure !== void 0) 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.
+*/
+function pingProbe(host) {
+	return defineProbe({
+		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) => [target(checked$2(input).address)],
+		available: (context) => pingAvailability(host, context),
+		async run(input, context) {
+			const command = pingCommand(host.platform, input);
+			if (command === void 0) throw new Error(`netdiag has no command of ping for ${host.platform}.`);
+			return runTool(host, command, context);
+		},
+		parse: (raw, input) => [observe(ICMP_ECHO, target(input.address), readPing(raw, input.address), {
+			start: raw.start,
+			end: raw.end
+		})]
+	});
+}
+// src/tools/traceroute.ts
+/** The default largest TTL. */
+const DEFAULT_TRACE_HOPS = 30;
+/** The largest TTL of one input. */
+const MAX_TRACE_HOPS = 64;
+/** The default time to wait for each answer, in milliseconds. */
+const DEFAULT_TRACE_WAIT_MS = 1e3;
+/** The number of probes for each TTL. `tracert` on Windows always sends 3 probes. */
+const TRACE_QUERIES = 3;
+function checked$1(input) {
+	return {
+		...toolAddress(input.address),
+		maxHops: integerIn(input.maxHops ?? 30, 1, 64, "a number of hops"),
+		waitMs: integerIn(input.waitMs ?? 1e3, 1, 1e4, "a time in milliseconds")
+	};
+}
+/**
+* This function gives the command of traceroute 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: `traceroute`, with UDP probes. A user without privileges can send them.
+* - macOS: `traceroute`, and `traceroute6` for an IPv6 address.
+* - Windows: `tracert.exe`, with ICMP echo requests.
+*
+* The time limit is the time of a trace that waits for each probe of each hop.
+*/
+function tracerouteCommand(platform, input) {
+	const { address, family, maxHops, waitMs } = checked$1(input);
+	const waitS = Math.ceil(waitMs / 1e3);
+	const unix = [
+		"-n",
+		"-q",
+		String(3),
+		"-w",
+		String(waitS),
+		"-m",
+		String(maxHops)
+	];
+	const unixTimeoutMs = maxHops * 3 * waitS * 1e3 + TOOL_MARGIN_MS;
+	switch (platform) {
+		case "linux": return {
+			command: "traceroute",
+			args: [
+				family === "ipv6" ? "-6" : "-4",
+				...unix,
+				address
+			],
+			timeoutMs: unixTimeoutMs,
+			env: ENGLISH
+		};
+		case "darwin": return {
+			command: family === "ipv6" ? "traceroute6" : "traceroute",
+			args: [...unix, address],
+			timeoutMs: unixTimeoutMs,
+			env: ENGLISH
+		};
+		case "win32": return {
+			command: "tracert",
+			args: [
+				"-d",
+				"-h",
+				String(maxHops),
+				"-w",
+				String(waitMs),
+				address
+			],
+			timeoutMs: maxHops * 3 * waitMs + TOOL_MARGIN_MS
+		};
+		default: return;
+	}
+}
+/** The command that examines if traceroute is available on each operating system, and the pattern of its version. */
+const AVAILABILITY = {
+	linux: {
+		command: "traceroute",
+		args: ["--version"],
+		version: /version (\d[\d.]*)/
+	},
+	darwin: {
+		command: "traceroute",
+		args: []
+	},
+	win32: {
+		command: "tracert",
+		args: ["/?"]
+	}
+};
+/** This function tells if traceroute is available on the host. On Linux, netdiag reads only the Modern traceroute for Linux. */
+async function tracerouteAvailability(host, context) {
+	const check = AVAILABILITY[host.platform];
+	if (check === void 0) return {
+		available: false,
+		reason: `netdiag reads the output of traceroute only on Linux, macOS and Windows, not on ${host.platform}.`
+	};
+	const output = await host.run(check.command, check.args, {
+		timeoutMs: AVAILABILITY_TIMEOUT_MS,
+		signal: context.signal,
+		env: ENGLISH
+	});
+	if (host.platform === "linux" && output.error === void 0 && !/Modern traceroute/i.test(`${output.stdout}\n${output.stderr}`)) return {
+		available: false,
+		reason: "netdiag reads only the Modern traceroute for Linux (the package traceroute). This traceroute does not tell that name."
+	};
+	return availabilityOf(check.command, output, check.version);
+}
+/** The flags of the Linux and BSD traceroute after the time of an answer, and their meaning. */
+const FLAGS = {
+	"!H": "host unreachable",
+	"!N": "network unreachable",
+	"!P": "protocol unreachable",
+	"!S": "source route failed",
+	"!F": "fragmentation needed",
+	"!X": "communication administratively prohibited",
+	"!A": "communication with the network administratively prohibited",
+	"!Z": "communication with the host administratively prohibited",
+	"!U": "destination network unknown",
+	"!W": "destination host unknown",
+	"!V": "host precedence violation",
+	"!C": "precedence cutoff"
+};
+/** This function gives the meaning of a flag, or `undefined` for the flag `!` alone. That flag tells only that the TTL of the answer is 1 or less. */
+function flagText(flag) {
+	if (flag === "!") return void 0;
+	const code = /^!<?(\d+)>?$/.exec(flag)?.[1];
+	if (code !== void 0) return `unreachable, ICMP code ${code} (${flag})`;
+	return `${FLAGS[flag.replace(/^(!F)-?\d+$/, "$1")] ?? "unreachable"} (${flag})`;
+}
+/** One hop while the reader reads it. */
+var HopBuilder = class {
+	addresses = [];
+	rttMs = [];
+	sent = 0;
+	received = 0;
+	unreachable;
+	/** This field is true when a time comes before an address. */
+	unread = false;
+	ttl;
+	current;
+	constructor(ttl) {
+		this.ttl = ttl;
+	}
+	address(text) {
+		this.current = text;
+		if (!this.addresses.some((known) => sameAddress(known, text))) this.addresses.push(text);
+	}
+	lost() {
+		this.sent += 1;
+	}
+	answer(rttMs) {
+		this.sent += 1;
+		if (this.current === void 0) {
+			this.unread = true;
+			return;
+		}
+		this.received += 1;
+		if (rttMs !== void 0) this.rttMs.push(rttMs);
+	}
+	hop() {
+		const hop = {
+			ttl: this.ttl,
+			addresses: [...this.addresses],
+			sent: this.sent,
+			received: this.received,
+			rttMs: [...this.rttMs]
+		};
+		return this.unreachable === void 0 ? hop : {
+			...hop,
+			unreachable: this.unreachable
+		};
+	}
+};
+/** This function gives the address of a token, for example `192.0.2.1` or `(192.0.2.1)`, or `undefined`. */
+function addressOf(token) {
+	const text = token.replace(/^\((.*)\)$/, "$1");
+	return isIP(text) === 0 ? void 0 : text;
+}
+/** The messages of traceroute on Linux and macOS when a socket operation fails, for example `socket: Operation not permitted`. */
+const SEND_FAILURE = /^(?:socket|bind|connect|sendmsg|sendto|send): \S/;
+function readUnix(stdout, stderr) {
+	const builders = [];
+	for (const line of stdout.split(LINES)) {
+		const numbered = /^\s*(\d+)\s(.*)$/.exec(line);
+		const continued = numbered === null && /^\s+\S/.test(line) ? builders.at(-1) : void 0;
+		if (numbered === null && continued === void 0) continue;
+		const builder = continued ?? new HopBuilder(Number(numbered?.[1]));
+		if (continued === void 0) builders.push(builder);
+		const tokens = (numbered?.[2] ?? line).trim().split(/\s+/);
+		for (let i = 0; i < tokens.length; i += 1) {
+			const token = tokens[i] ?? "";
+			const address = addressOf(token);
+			const time = /^(\d+(?:\.\d+)?)(ms)?$/.exec(token);
+			if (token === "*") builder.lost();
+			else if (address !== void 0) builder.address(address);
+			else if (time !== null && (time[2] === "ms" || tokens[i + 1] === "ms")) {
+				builder.answer(Number(time[1]));
+				if (time[2] === void 0) i += 1;
+			} else if (token.startsWith("!")) builder.unreachable ??= flagText(token);
+		}
+	}
+	let failure;
+	let local;
+	for (const line of stderr.split(LINES)) {
+		const text = line.replace(/^traceroute6?:\s*/, "").trim();
+		const unreachable = LOCAL_UNREACHABLE.exec(text);
+		if (unreachable !== null) local ??= unreachable[1] ?? text;
+		else if (SEND_FAILURE.test(text)) failure ??= text;
+	}
+	const header = /^traceroute6? to /m.test(`${stdout}\n${stderr}`);
+	return {
+		hops: builders.map((b) => b.hop()),
+		header,
+		complete: true,
+		unread: builders.find((b) => b.unread)?.ttl,
+		failure,
+		local
+	};
+}
+/** The text between the address of a router and its message in the output of `tracert`. */
+const REPORTS = " reports: ";
+function readWindows(stdout) {
+	const builders = [];
+	let failure;
+	for (const line of stdout.split(LINES)) {
+		const numbered = /^\s*(\d+)\s(.*)$/.exec(line);
+		if (numbered === null) continue;
+		const builder = new HopBuilder(Number(numbered[1]));
+		builders.push(builder);
+		const rest = (numbered[2] ?? "").trim();
+		const at = rest.indexOf(REPORTS);
+		const tokens = (at < 0 ? rest : rest.slice(0, at)).split(/\s+/).filter((token) => token.length > 0);
+		const address = tokens.map(addressOf).find((found) => found !== void 0);
+		if (address !== void 0) builder.address(address);
+		for (let i = 0; i < tokens.length; i += 1) {
+			const token = tokens[i] ?? "";
+			const time = /^<?(\d+)$/.exec(token);
+			if (token === "*") builder.lost();
+			else if (time !== null && tokens[i + 1] === "ms") {
+				builder.answer(Math.max(1, Number(time[1])));
+				i += 1;
+			} else if (/^(General failure|Transmit error)/i.test(tokens.slice(i).join(" "))) {
+				failure ??= tokens.slice(i).join(" ").replace(/\.$/, "");
+				break;
+			}
+		}
+		if (at >= 0) {
+			builder.answer(void 0);
+			builder.unreachable = rest.slice(at + 10).trim().replace(/\.$/, "");
+		}
+	}
+	return {
+		hops: builders.map((b) => b.hop()),
+		header: /^Tracing route to /m.test(stdout),
+		complete: /^Trace complete\./m.test(stdout),
+		unread: builders.find((b) => b.unread)?.ttl,
+		failure
+	};
+}
+/**
+* This function reads the raw output of the traceroute probe into the value of a fact `path.trace`.
+*
+* - The outcome is `reached` when the address answered at the last hop.
+* - Output that netdiag cannot read gives the outcome `error`. An `error` keeps the hops that netdiag read.
+*/
+function readTraceroute(raw, input) {
+	const { address } = input;
+	const maxHops = input.maxHops ?? 30;
+	const result = (outcome, hops, detail) => detail === void 0 ? {
+		address,
+		outcome,
+		maxHops,
+		hops
+	} : {
+		address,
+		outcome,
+		maxHops,
+		hops,
+		detail
+	};
+	if (raw.error !== void 0) return result("error", [], raw.error);
+	const { hops, header, complete, unread, failure, local } = raw.platform === "win32" ? readWindows(raw.stdout) : readUnix(raw.stdout, raw.stderr);
+	if (unread !== void 0) return result("error", hops.filter((hop) => hop.ttl < unread), `netdiag cannot read the hop ${unread} of traceroute.`);
+	if (!header && local === void 0) return result("error", [], failure ?? firstLine(raw.stderr) ?? "netdiag cannot read the output of traceroute. netdiag reads only English output.");
+	if (raw.timedOut === true || !complete) return result("error", hops, "The time limit stopped traceroute before its end.");
+	const last = hops.at(-1);
+	if (last?.addresses.some((known) => sameAddress(known, address)) === true) return result("reached", hops);
+	if (last?.unreachable !== void 0) return result("unreachable", hops, last.unreachable);
+	if (local !== void 0) return result("unreachable", hops, local);
+	if (failure !== void 0) return result("error", hops, failure);
+	return result("stopped", hops);
+}
+/**
+* This function makes the probe `path.traceroute`: the trace of the path to one IP address with the tool traceroute,
+* or `tracert` on Windows. The host starts the tool.
+*/
+function tracerouteProbe(host) {
+	return defineProbe({
+		id: "path.traceroute",
+		version: "1",
+		summary: "The hops of the path to one IP address, from the tool traceroute or tracert.",
+		layer: "path",
+		mode: "active",
+		kinds: [PATH_TRACE],
+		tool: "traceroute",
+		peers: (input) => [target(checked$1(input).address)],
+		available: (context) => tracerouteAvailability(host, context),
+		async run(input, context) {
+			const command = tracerouteCommand(host.platform, input);
+			if (command === void 0) throw new Error(`netdiag has no command of traceroute for ${host.platform}.`);
+			return runTool(host, command, context);
+		},
+		parse: (raw, input) => [observe(PATH_TRACE, target(input.address), readTraceroute(raw, input), {
+			start: raw.start,
+			end: raw.end
+		})]
+	});
+}
+// src/tools/mtr.ts
+/** The default number of cycles. It is `LOSS_MIN_SENT` of the readers, so a report gives the feature `path.loss`. */
+const DEFAULT_MTR_CYCLES = 20;
+/** The largest number of cycles of one input. */
+const MAX_MTR_CYCLES = 100;
+/** The time that mtr waits for the last answers after the last cycle, in milliseconds (its option `--gracetime`). */
+const MTR_GRACE_MS = 5e3;
+function checked(input) {
+	return {
+		...toolAddress(input.address),
+		cycles: integerIn(input.cycles ?? 20, 1, 100, "a number of cycles"),
+		maxHops: integerIn(input.maxHops ?? 30, 1, 64, "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.
+*/
+function mtrCommand(platform, input) {
+	const { address, family, cycles, maxHops } = checked(input);
+	if (platform !== "linux" && platform !== "darwin") return void 0;
+	return {
+		command: "mtr",
+		args: [
+			"--json",
+			"--no-dns",
+			family === "ipv6" ? "-6" : "-4",
+			"-c",
+			String(cycles),
+			"-m",
+			String(maxHops),
+			address
+		],
+		timeoutMs: cycles * 1e3 + MTR_GRACE_MS + TOOL_MARGIN_MS,
+		env: ENGLISH
+	};
+}
+/** This function tells if mtr is available on the host. The adapter knows Linux and macOS. */
+async function mtrAvailability(host, context) {
+	if (host.platform !== "linux" && host.platform !== "darwin") return {
+		available: false,
+		reason: `netdiag starts mtr only on Linux and macOS, not on ${host.platform}.`
+	};
+	return availabilityOf("mtr", await host.run("mtr", ["--version"], {
+		timeoutMs: AVAILABILITY_TIMEOUT_MS,
+		signal: context.signal,
+		env: ENGLISH
+	}), /mtr (\d[\d.]*)/);
+}
+function finite(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+/** This function reads one hub of the JSON report, or gives `undefined` when netdiag cannot read it. */
+function readHub(hub) {
+	if (typeof hub !== "object" || hub === null) return void 0;
+	const record = hub;
+	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 === void 0 || loss > 100) return void 0;
+	if (typeof host !== "string") return void 0;
+	const received = sent - Math.round(sent * loss / 100);
+	if (host === "???") return received === 0 ? {
+		ttl,
+		sent,
+		received
+	} : void 0;
+	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 === void 0 ? {} : { bestMs: times.bestMs },
+		...times.meanMs === void 0 ? {} : { meanMs: times.meanMs },
+		...times.worstMs === void 0 ? {} : { 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) {
+	try {
+		const parsed = JSON.parse(text);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		const report = parsed.report;
+		if (typeof report !== "object" || report === null) return void 0;
+		const hubs = report.hubs;
+		return Array.isArray(hubs) ? hubs : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* 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`.
+*/
+function readMtr(raw, input) {
+	const { address } = input;
+	const cycles = input.cycles ?? 20;
+	const error = (detail) => ({
+		address,
+		outcome: "error",
+		cycles,
+		hops: [],
+		detail
+	});
+	if (raw.error !== void 0) 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 === void 0) return error(firstLine(raw.stderr) ?? "netdiag cannot read the JSON report of mtr.");
+	const hops = [];
+	for (const hub of hubs) {
+		const hop = readHub(hub);
+		if (hop === void 0) 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 === void 0) return error(firstLine(raw.stderr) ?? "The report of mtr has no hub.");
+	return {
+		address,
+		outcome: last.address !== void 0 && last.received > 0 && sameAddress(last.address, address) ? "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. */
+function mtrProbe(host) {
+	return defineProbe({
+		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) => [target(checked(input).address)],
+		available: (context) => mtrAvailability(host, context),
+		async run(input, context) {
+			const command = mtrCommand(host.platform, input);
+			if (command === void 0) throw new Error(`netdiag has no command of mtr for ${host.platform}.`);
+			return runTool(host, command, context);
+		},
+		parse: (raw, input) => [observe(PATH_REPORT, target(input.address), readMtr(raw, input), {
+			start: raw.start,
+			end: raw.end
+		})]
+	});
+}
+export { AVAILABILITY_TIMEOUT_MS, DEFAULT_MTR_CYCLES, DEFAULT_PING_COUNT, DEFAULT_PING_WAIT_MS, DEFAULT_TRACE_HOPS, DEFAULT_TRACE_WAIT_MS, MAX_MTR_CYCLES, MAX_PING_COUNT, MAX_TRACE_HOPS, MTR_GRACE_MS, PING6_LAST_WAIT_MS, PING_INTERVAL_MS, TOOL_LICENSES, TOOL_MARGIN_MS, TRACE_QUERIES, availabilityOf, mtrAvailability, mtrCommand, mtrProbe, pingAvailability, pingCommand, pingProbe, readMtr, readPing, readTraceroute, runTool, toolLicense, tracerouteAvailability, tracerouteCommand, tracerouteProbe };
+
+//# sourceMappingURL=tools.js.map