@mark1russell7/netdiag 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,245 @@
-# Temporary Holding Version
+# @mark1russell7/netdiag
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package has the core model of netdiag. It has the typed facts at each layer of the stack, the contract of a probe and the scope rule. It also has the catalog of faults and the probability model.
+
+**State: ND-1, ND-2, ND-4, and the lab score and the loopback lab of ND-7 of the [roadmap](../../docs/ROADMAP.md).** The kernel lab and the bars of the gate come next.
+
+## Facts
+
+A fact has a layer, a time, a source and a value. Its kind names the type of its value, for example `tcp.connect`.
+
+| Field | What it is |
+| --- | --- |
+| `id` | An id that is unique in the facts of one runner, for example `f12`. |
+| `kind` | The name of the fact kind. The kind has the check of the value. |
+| `layer` | One of `link`, `wifi`, `ip`, `route`, `path`, `dns`, `tcp`, `tls` and `http`. |
+| `subject` | The target of the fact: a host and an optional port. |
+| `time` | The start and the end, in milliseconds on the monotonic clock of the runner. |
+| `source` | The probe, its version, and the outside tool when the probe starts one. |
+| `value` | The value. It passes the check of its kind. |
+
+A fact is plain data, so a record of facts is JSON.
+
+## Probes
+
+A probe is an adapter. It tells if it is available, it does its work, and it parses its raw output into observations.
+
+- `peers(input)` gives each host that the probe sends packets to. A passive probe gives no peers.
+- `run(input, context)` does the effects and gives the raw output.
+- `parse(raw, input)` is a pure function. A record of a raw output thus gives the same facts again.
+
+A network failure is a fact, not an error. For example, a TCP connect that times out gives the outcome `timeout`.
+
+## The scope rule
+
+An active probe sends packets only to a peer that the user owns or names. The runner examines each peer before the probe starts.
+
+| Basis | Why the target is in the scope |
+| --- | --- |
+| `named` | The user named the target for this diagnosis. |
+| `owned` | The user declares that the user owns the network or the host. |
+| `configured` | The configuration of the computer names it, for example the gateway or the DNS resolver. |
+| `resolved` | A DNS answer for a granted name gave this address. |
+
+The scope also limits the number of ports of each host. The default limit is 8. Thus netdiag does no port scan.
+
+## IP addresses
+
+The entry `@mark1russell7/netdiag/address` has plain functions for IP addresses and networks. It uses only the module `node:net`.
+
+| Function | What it gives |
+| --- | --- |
+| `addressFamily(address)` | `ipv4`, `ipv6`, or `undefined` for a text that is not an address. |
+| `addressClass(address)` | The class of the address, from the special-purpose ranges of RFC 6890. |
+| `addressKind(address)` | `private` for an address that the internet does not route to, else `public`. |
+| `parseCidr(text)` | A CIDR range, or the problem of the text. |
+| `cidrSet(ranges)` | A set of ranges. Its `has(address)` tells if an address is in a range of the set. |
+
+- The classes are `unspecified`, `loopback`, `private`, `shared`, `link-local`, `unique-local`, `documentation`, `benchmarking`, `multicast`, `reserved` and `public`.
+- The table `ADDRESS_CLASSES` holds the ranges of the classes as data.
+- An IPv4 address in IPv6 form, for example `::ffff:192.0.2.1`, is its IPv4 address.
+- An address for documentation is `public`. Thus a lab can use `203.0.113.0/24` for hosts on the internet.
+
+```ts
+import { addressClass, cidrSet, parseCidr } from "@mark1russell7/netdiag/address";
+
+addressClass("100.64.0.1"); // "shared": the carrier-grade NAT range
+const lab = parseCidr("203.0.113.0/24");
+if (lab.tag === "ok") cidrSet([lab.value]).has("::ffff:203.0.113.7"); // true
+```
+
+## Native probes
+
+The native probes use only the `node:` modules. They need no outside tool.
+
+| Probe | Id | Facts |
+| --- | --- | --- |
+| `DNS_PROBE` | `dns.query` | `dns.answer`: the outcome, the addresses and the lowest TTL of one query for `A` or `AAAA` records. |
+| `tcpProbe()` | `tcp.connect` | `tcp.connect`: the outcome and the time of one connect. |
+| `tlsProbe()` | `tls.handshake` | `tcp.connect` and `tls.handshake`: the time of the handshake, the version, the cipher, ALPN and the certificate. |
+| `httpProbe()` | `http.request` | `tcp.connect`, `tls.handshake` for `https`, and `http.response`: the status, some fields of the head and the time to the first byte. |
+
+- A probe connects only to an IP address. The DNS probe gives the addresses of a name first. Thus the runner examines each address against the scope.
+- The peer of the DNS probe is the resolver, not the name.
+- A time limit or a stop of the signal closes the socket. The probe then gives the outcome `timeout`, or the runner gives `aborted`.
+- The TLS probe does not refuse a certificate that is not valid. It records the problem, for example `expired`, `name` or `untrusted`.
+- The trust tells the root of the chain. `public` is a root of Node.js. `private` is a different root, for example the root of a proxy that examines TLS.
+- The option `roots` adds roots that the user trusts, for example the root of a company. Their trust is `private`.
+- The option `publicRoots` adds roots with the trust `public`. A lab gives its own root here, so its servers stand for servers on the internet.
+- The HTTP probe follows no redirect. It reads the body up to 64 KiB.
+- For `https`, the HTTP probe sends its request only when the certificate passes its check. Thus an interceptor does not get the path.
+
+```ts
+import { realClock } from "@mark1russell7/algebra/clock";
+import { TCP_PROBE, createRunner, scopeOf } from "@mark1russell7/netdiag";
+
+const scope = scopeOf([{ kind: "range", cidr: "192.168.1.0/24", basis: "owned" }]);
+if (scope.tag === "err") throw new Error(scope.error.join(" "));
+
+const runner = createRunner({ scope: scope.value, clock: realClock });
+const outcome = await runner.run(TCP_PROBE, { address: "192.168.1.1", port: 443 });
+// The fact tcp.connect has the outcome connected, refused, timeout, unreachable, reset or error.
+```
+
+## Outside tools
+
+The entry `@mark1russell7/netdiag/tools` has optional adapters of outside tools. netdiag bundles no tool. The user installs each tool.
+
+| Probe | Id | Tool | Facts |
+| --- | --- | --- | --- |
+| `pingProbe(host)` | `icmp.ping` | `ping` | `icmp.echo`: the echo replies, their round-trip times, and the messages of an unreachable address. |
+| `tracerouteProbe(host)` | `path.traceroute` | `traceroute`, `tracert` on Windows | `path.trace`: the routers that answered each TTL, their round-trip times, and the messages of an unreachable address. |
+| `mtrProbe(host)` | `path.mtr` | `mtr` (Linux and macOS) | `path.report`: the loss and the round-trip times of each hop over many cycles. |
+
+- A host starts each tool. Its `run(command, args, options)` starts a program with a list of arguments and no shell.
+- The function `runCommand` of `@procedures/shell` is a host with no change. A test gives a fake host.
+- An adapter reads only English output. On Linux and macOS, it sets `LC_ALL=C`. On Windows, the language of the system sets the output.
+- On Linux, the adapter reads the `ping` of iputils. On macOS, it uses `ping6` for an IPv6 address.
+- On Linux, the trace adapter reads the Modern traceroute (the package `traceroute`). On macOS, it uses `traceroute6` for an IPv6 address.
+- The `mtr` adapter reads the JSON report of `mtr --json` (version 0.92 or later). The default of 20 cycles takes approximately 20 seconds.
+- Output that netdiag cannot read gives the outcome `error` with the reason. It does not give a reply that did not occur.
+- The table `TOOL_LICENSES` holds the license of each tool as data. A tool with a restrictive license has no adapter.
+
+```ts
+import { runCommand } from "@procedures/shell";
+import { pingProbe, type ToolHost } from "@mark1russell7/netdiag/tools";
+
+const host: ToolHost = {
+  platform: process.platform,
+  run: (command, args, options) => runCommand(command, { args: [...args], timeout: options.timeoutMs, signal: options.signal, env: options.env }),
+};
+// The runner comes from the example of the native probes.
+const outcome = await runner.run(pingProbe(host), { address: "192.168.1.1", count: 20 });
+```
+
+## Diagnosis
+
+The entry `@mark1russell7/netdiag/diagnosis` has the probability model. It imports no `node:` module, so a browser can also use it.
+
+- A feature is a discrete observation. For example, `tcp.connect` has the values `connected`, `refused`, `timeout`, `unreachable` and `reset`.
+- Each feature has a healthy distribution: the probability of each value when there is no fault.
+- A fault names a part of the network and the feature values that it predicts. The other features keep their healthy distributions.
+- The hypotheses are `none` (no fault), each fault of the catalog, and `unknown` (a cause that the catalog does not have).
+- The hypothesis `unknown` gives the same probability to each value. Thus it wins when no fault of the catalog explains the observations.
+
+| Function | What it gives |
+| --- | --- |
+| `diagnose(catalog, evidence)` | The probability of each hypothesis, from the most probable. The model is naive Bayes with logarithms. |
+| `explain(catalog, evidence, id)` | The weight of each observation for a cause: the `log10` of its likelihood ratio against `none`. |
+| `predictive(catalog, diagnosis, feature, primary)` | The probability of each value of a feature before a probe observes it. The choice of the next probe (ND-5) uses it. |
+
+Evidence with `primary: false` comes from a reference host, for example a second public server. A fault with the reach `target` does not change the reference host. A fault with the reach `shared` changes both hosts. Thus a slow TLS handshake on both hosts points to a TLS proxy. A slow handshake on the target only points to a slow server.
+
+The standard catalog `STANDARD_CATALOG` has 15 features and 20 faults. The rules of practice give its first likelihoods, and each hypothesis has the same prior. The lab runs (ND-7) then fit these numbers.
+
+```ts
+import { STANDARD_CATALOG, diagnose } from "@mark1russell7/netdiag/diagnosis";
+
+const result = diagnose(STANDARD_CATALOG, [
+  { feature: "icmp.reply", value: "none", primary: true },
+  { feature: "tcp.connect", value: "connected", primary: true },
+]);
+// result.causes[0].id is "filter.icmp": a filter blocks ICMP, and the host is up.
+```
+
+## Readers
+
+`readEvidence(facts, options)` changes the facts of the native probes and of the adapters into evidence for the model. Each value that it gives is a value of a feature of `STANDARD_CATALOG`.
+
+| Feature | The source of the value |
+| --- | --- |
+| `dns.answer` | The outcome of each DNS query. One answer `ok` for a name and a resolver decides. `nodata` gives `ok`, because the name exists. |
+| `dns.address` | The addresses of a public name. One private address decides. A local name, for example `nas.local`, gives no value. |
+| `ip.family` | The TCP connects to the IPv4 and the IPv6 addresses of one name. |
+| `tcp.connect`, `tcp.time` | The outcome and the time of each TCP connect. A time of 900 ms or more tells that the SYN went again. |
+| `tls.handshake`, `tls.trust` | The outcome of the handshake and the root of the certificate chain. A chain with no root of the store gives `private`. |
+| `tls.ratio` | The time of the handshake divided by the time of the last TCP connect to the same address and port. |
+| `http.status`, `http.ttfb` | The class of the status, and the time to the first byte divided by the time of the TCP connect. |
+| `gateway.reply` | The echo requests to the address of the option `gateway`. An unreachable gateway gives `none`. |
+| `icmp.reply` | The echo requests to each other address: `reply`, `none` or `unreachable`. |
+| `path.loss` | The share of the echo requests with a reply, for 20 requests or more: `none`, `some` (up to 5 % loss) or `high`. A report of `mtr` that reached the address gives it from its last hop. |
+
+- The reader gives one evidence for each feature, subject and role. When a subject has more facts, the last fact decides.
+- A fact that gives no evidence goes in `skipped`, with the reason. For example, the catalog has no value for the TLS outcome `not-tls` yet.
+- A fact `path.trace` gives no evidence yet. The catalog has no feature for the hops of a path. The lab runs (ND-7) fit one.
+- The option `primary` tells which facts are about the target. The other facts are about a reference host.
+- The option `gateway` gives the IP address of the default gateway.
+
+```ts
+import { STANDARD_CATALOG, TCP_PROBE, diagnose, readEvidence } from "@mark1russell7/netdiag";
+
+// The runner comes from the example of the native probes.
+const outcome = await runner.run(TCP_PROBE, { address: "192.168.1.1", port: 443 });
+if (outcome.status === "done") {
+  const { evidence, skipped } = readEvidence(outcome.facts);
+  const result = diagnose(STANDARD_CATALOG, evidence);
+  // A connect with the outcome refused gives result.causes[0].id "port.closed".
+}
+```
+
+## The lab score
+
+A lab makes one fault on purpose. Then netdiag must name it. The entry `@mark1russell7/netdiag/diagnosis` has the score of these runs.
+
+| Function | What it gives |
+| --- | --- |
+| `labRecordOf(catalog, case, truth, diagnosis)` | The record of one run: the true hypothesis, the predicted cause, the rank of the truth and the probability of each cause. |
+| `scoreLab(catalog, records)` | The confusion table, the recall of each hypothesis with its Wilson interval, the accuracy and the mean Brier score. |
+| `labGate(score, bars)` | A verdict for each hypothesis with a bar: `pass`, `fail` or `no-read`. |
+
+- The recall of a hypothesis is the part of its runs where the diagnosis names it.
+- A hypothesis passes when the lower end of its recall interval is its bar or more.
+- A hypothesis with no runs gets `no-read`, and the gate does not pass.
+- A hypothesis with no bar goes in `unbarred`, for example a fault that no lab can make.
+
+```ts
+import { STANDARD_CATALOG, diagnose, labGate, labRecordOf, scoreLab } from "@mark1russell7/netdiag/diagnosis";
+
+const diagnosis = diagnose(STANDARD_CATALOG, [{ feature: "tcp.connect", value: "refused", primary: true }]);
+const record = labRecordOf(STANDARD_CATALOG, "port.closed/refused", "port.closed", diagnosis);
+if (record.tag === "err") throw new Error(record.error);
+
+const score = scoreLab(STANDARD_CATALOG, [record.value]);
+if (score.tag === "err") throw new Error(score.error.join(" "));
+const gate = labGate(score.value, { "port.closed": 0.1 });
+// gate.value.verdicts[0].status is "pass": the lower end of the recall of 1 run of 1 is 0.21.
+```
+
+## Example
+
+```ts
+import { fakeClock } from "@mark1russell7/algebra/clock";
+import { createRunner, namedGrant, parseTarget, scopeOf } from "@mark1russell7/netdiag";
+
+const named = parseTarget("https://example.com");
+if (named.tag === "err") throw new Error(named.error);
+const scope = scopeOf([namedGrant(named.value)]);
+if (scope.tag === "err") throw new Error(scope.error.join(" "));
+
+const runner = createRunner({ scope: scope.value, clock: fakeClock() });
+// runner.run(probe, input) gives the outcome: done, refused, unavailable, failed or aborted.
+```
+
+## License
+
+[MIT](../../LICENSE)

package/build/address.d.ts

@@ -0,0 +1,56 @@
+import { Result } from "@mark1russell7/optional";
+/** The family of an IP address. */
+export type AddressFamily = "ipv4" | "ipv6";
+/**
+ * The class of an IP address, from the special-purpose ranges of RFC 6890.
+ *
+ * - `unspecified`: `0.0.0.0/8` and `::`.
+ * - `loopback`: `127.0.0.0/8` and `::1`.
+ * - `private`: the ranges of RFC 1918.
+ * - `shared`: `100.64.0.0/10`, the carrier-grade NAT range of RFC 6598.
+ * - `link-local`: `169.254.0.0/16` and `fe80::/10`.
+ * - `unique-local`: `fc00::/7`, the private range of IPv6 (RFC 4193).
+ * - `documentation`: the ranges of RFC 5737 and RFC 3849 for examples.
+ * - `benchmarking`: `198.18.0.0/15` (RFC 2544).
+ * - `multicast`: `224.0.0.0/4` and `ff00::/8`.
+ * - `reserved`: `240.0.0.0/4`, with the broadcast address.
+ * - `public`: each other address.
+ */
+export type AddressClass = "unspecified" | "loopback" | "private" | "shared" | "link-local" | "unique-local" | "documentation" | "benchmarking" | "multicast" | "reserved" | "public";
+/** A CIDR range: an address of the network and the length of its prefix. */
+export interface Cidr {
+  readonly address: string;
+  readonly prefix: number;
+  readonly family: AddressFamily;
+}
+/** The special-purpose ranges, as data. An address that is in no range is `public`. */
+export declare const ADDRESS_CLASSES: readonly {
+  readonly cidr: string;
+  readonly class: Exclude<AddressClass, "public">;
+}[];
+/** This function gives the canonical form of an address: no spaces, no brackets, lower case, and IPv4 for a mapped IPv4 address. */
+export declare function canonicalAddress(address: string): string;
+/** This function gives the family of an IP address, or `undefined` for a text that is not an IP address. */
+export declare function addressFamily(address: string): AddressFamily | undefined;
+/** This function gives the CIDR range of a text, for example `192.0.2.0/24` or `2001:db8::/32`. An address alone is a range of one address. */
+export declare function parseCidr(text: string): Result<Cidr, string>;
+/** This function gives the text of a CIDR range. */
+export declare function formatCidr(cidr: Cidr): string;
+/** A set of CIDR ranges. */
+export interface CidrSet {
+  readonly ranges: readonly Cidr[];
+  /** This function tells if an address is in a range of the set. A text that is not an IP address is in no set. */
+  has(address: string): boolean;
+}
+/** This function gives the set of some CIDR ranges. */
+export declare function cidrSet(ranges: readonly Cidr[]): CidrSet;
+/** This function tells if an address is in a CIDR range. */
+export declare function cidrContains(cidr: Cidr, address: string): boolean;
+/** This function gives the class of an IP address, or `undefined` for a text that is not an IP address. */
+export declare function addressClass(address: string): AddressClass | undefined;
+/**
+ * This function tells if the internet routes to an address. A `private` address is unspecified, loopback, private,
+ * shared, link-local or unique-local. Each other address is `public`, also an address for documentation.
+ */
+export declare function addressKind(address: string): "public" | "private" | undefined;
+//# sourceMappingURL=address.d.ts.map

package/build/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","names":[],"sources":["../src/address/index.ts"],"mappings":";;YASY;;;;;;;;;;;;;;;;YAiBA;;iBAcK;WACN;WACA;WACA,QAAQ;;;qBAIN;WAAqC;WAAuB,OAAO,QAAQ;;;wBA0BxE,iBAAiB;;wBAQjB,cAAc,kBAAkB;;wBAMhC,UAAU,eAAe,OAAO;;wBAYhC,WAAW,MAAM;;iBAKhB;WACN,iBAAiB;;EAE1B,IAAI;;;wBAIU,QAAQ,iBAAiB,SAAS;;wBAclC,aAAa,MAAM,MAAM;;wBAgBzB,aAAa,kBAAkB;;;;;wBAS/B,YAAY"}

package/build/address.js

@@ -0,0 +1,172 @@
+import { BlockList, isIP } from "node:net";
+import { err, ok } from "@mark1russell7/optional";
+// src/address/index.ts
+/**
+* The IP addresses and the networks of netdiag: the family and the class of an address, CIDR ranges and sets of ranges.
+*
+* This entry uses only the module `node:net`. An IPv4 address in IPv6 form (`::ffff:192.0.2.1`) is its IPv4 address.
+*/
+/** The special-purpose ranges, as data. An address that is in no range is `public`. */
+const ADDRESS_CLASSES = [
+	{
+		cidr: "0.0.0.0/8",
+		class: "unspecified"
+	},
+	{
+		cidr: "10.0.0.0/8",
+		class: "private"
+	},
+	{
+		cidr: "100.64.0.0/10",
+		class: "shared"
+	},
+	{
+		cidr: "127.0.0.0/8",
+		class: "loopback"
+	},
+	{
+		cidr: "169.254.0.0/16",
+		class: "link-local"
+	},
+	{
+		cidr: "172.16.0.0/12",
+		class: "private"
+	},
+	{
+		cidr: "192.0.2.0/24",
+		class: "documentation"
+	},
+	{
+		cidr: "192.168.0.0/16",
+		class: "private"
+	},
+	{
+		cidr: "198.18.0.0/15",
+		class: "benchmarking"
+	},
+	{
+		cidr: "198.51.100.0/24",
+		class: "documentation"
+	},
+	{
+		cidr: "203.0.113.0/24",
+		class: "documentation"
+	},
+	{
+		cidr: "224.0.0.0/4",
+		class: "multicast"
+	},
+	{
+		cidr: "240.0.0.0/4",
+		class: "reserved"
+	},
+	{
+		cidr: "::/128",
+		class: "unspecified"
+	},
+	{
+		cidr: "::1/128",
+		class: "loopback"
+	},
+	{
+		cidr: "2001:db8::/32",
+		class: "documentation"
+	},
+	{
+		cidr: "fc00::/7",
+		class: "unique-local"
+	},
+	{
+		cidr: "fe80::/10",
+		class: "link-local"
+	},
+	{
+		cidr: "ff00::/8",
+		class: "multicast"
+	}
+];
+/** The classes of the addresses that the internet does not route to a host. */
+const NOT_ROUTED = /* @__PURE__ */ new Set([
+	"unspecified",
+	"loopback",
+	"private",
+	"shared",
+	"link-local",
+	"unique-local"
+]);
+/** This function gives the canonical form of an address: no spaces, no brackets, lower case, and IPv4 for a mapped IPv4 address. */
+function canonicalAddress(address) {
+	let text = address.trim().toLowerCase();
+	if (text.startsWith("[") && text.endsWith("]")) text = text.slice(1, -1);
+	return /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(text)?.[1] ?? text;
+}
+/** This function gives the family of an IP address, or `undefined` for a text that is not an IP address. */
+function addressFamily(address) {
+	const family = isIP(canonicalAddress(address));
+	return family === 4 ? "ipv4" : family === 6 ? "ipv6" : void 0;
+}
+/** This function gives the CIDR range of a text, for example `192.0.2.0/24` or `2001:db8::/32`. An address alone is a range of one address. */
+function parseCidr(text) {
+	const slash = text.indexOf("/");
+	const address = canonicalAddress(slash === -1 ? text : text.slice(0, slash));
+	const family = addressFamily(address);
+	if (family === void 0) return err(`"${text}" is not an IP address or a CIDR range.`);
+	const max = family === "ipv4" ? 32 : 128;
+	const prefix = slash === -1 ? String(max) : text.slice(slash + 1).trim();
+	if (!/^\d{1,3}$/.test(prefix) || Number(prefix) > max) return err(`"${text}" has no prefix from 0 to ${max}.`);
+	return ok({
+		address,
+		prefix: Number(prefix),
+		family
+	});
+}
+/** This function gives the text of a CIDR range. */
+function formatCidr(cidr) {
+	return `${cidr.address}/${cidr.prefix}`;
+}
+/** This function gives the set of some CIDR ranges. */
+function cidrSet(ranges) {
+	const list = new BlockList();
+	for (const range of ranges) list.addSubnet(range.address, range.prefix, range.family);
+	return {
+		ranges: [...ranges],
+		has(address) {
+			const host = canonicalAddress(address);
+			const family = addressFamily(host);
+			return family !== void 0 && list.check(host, family);
+		}
+	};
+}
+/** This function tells if an address is in a CIDR range. */
+function cidrContains(cidr, address) {
+	return cidrSet([cidr]).has(address);
+}
+let classSets;
+function classes() {
+	classSets ??= ADDRESS_CLASSES.map((entry) => {
+		const range = parseCidr(entry.cidr);
+		if (range.tag === "err") throw new Error(range.error);
+		return {
+			class: entry.class,
+			set: cidrSet([range.value])
+		};
+	});
+	return classSets;
+}
+/** This function gives the class of an IP address, or `undefined` for a text that is not an IP address. */
+function addressClass(address) {
+	if (addressFamily(address) === void 0) return void 0;
+	return classes().find((entry) => entry.set.has(address))?.class ?? "public";
+}
+/**
+* This function tells if the internet routes to an address. A `private` address is unspecified, loopback, private,
+* shared, link-local or unique-local. Each other address is `public`, also an address for documentation.
+*/
+function addressKind(address) {
+	const found = addressClass(address);
+	if (found === void 0) return void 0;
+	return NOT_ROUTED.has(found) ? "private" : "public";
+}
+export { ADDRESS_CLASSES, addressClass, addressFamily, addressKind, canonicalAddress, cidrContains, cidrSet, formatCidr, parseCidr };
+
+//# sourceMappingURL=address.js.map

package/build/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","names":[],"sources":["../src/address/index.ts"],"sourcesContent":["/**\n * The IP addresses and the networks of netdiag: the family and the class of an address, CIDR ranges and sets of ranges.\n *\n * This entry uses only the module `node:net`. An IPv4 address in IPv6 form (`::ffff:192.0.2.1`) is its IPv4 address.\n */\nimport { BlockList, isIP } from \"node:net\";\nimport { err, ok, type Result } from \"@mark1russell7/optional\";\n\n/** The family of an IP address. */\nexport type AddressFamily = \"ipv4\" | \"ipv6\";\n\n/**\n * The class of an IP address, from the special-purpose ranges of RFC 6890.\n *\n * - `unspecified`: `0.0.0.0/8` and `::`.\n * - `loopback`: `127.0.0.0/8` and `::1`.\n * - `private`: the ranges of RFC 1918.\n * - `shared`: `100.64.0.0/10`, the carrier-grade NAT range of RFC 6598.\n * - `link-local`: `169.254.0.0/16` and `fe80::/10`.\n * - `unique-local`: `fc00::/7`, the private range of IPv6 (RFC 4193).\n * - `documentation`: the ranges of RFC 5737 and RFC 3849 for examples.\n * - `benchmarking`: `198.18.0.0/15` (RFC 2544).\n * - `multicast`: `224.0.0.0/4` and `ff00::/8`.\n * - `reserved`: `240.0.0.0/4`, with the broadcast address.\n * - `public`: each other address.\n */\nexport type AddressClass =\n  | \"unspecified\"\n  | \"loopback\"\n  | \"private\"\n  | \"shared\"\n  | \"link-local\"\n  | \"unique-local\"\n  | \"documentation\"\n  | \"benchmarking\"\n  | \"multicast\"\n  | \"reserved\"\n  | \"public\";\n\n/** A CIDR range: an address of the network and the length of its prefix. */\nexport interface Cidr {\n  readonly address: string;\n  readonly prefix: number;\n  readonly family: AddressFamily;\n}\n\n/** The special-purpose ranges, as data. An address that is in no range is `public`. */\nexport const ADDRESS_CLASSES: readonly { readonly cidr: string; readonly class: Exclude<AddressClass, \"public\"> }[] = [\n  { cidr: \"0.0.0.0/8\", class: \"unspecified\" },\n  { cidr: \"10.0.0.0/8\", class: \"private\" },\n  { cidr: \"100.64.0.0/10\", class: \"shared\" },\n  { cidr: \"127.0.0.0/8\", class: \"loopback\" },\n  { cidr: \"169.254.0.0/16\", class: \"link-local\" },\n  { cidr: \"172.16.0.0/12\", class: \"private\" },\n  { cidr: \"192.0.2.0/24\", class: \"documentation\" },\n  { cidr: \"192.168.0.0/16\", class: \"private\" },\n  { cidr: \"198.18.0.0/15\", class: \"benchmarking\" },\n  { cidr: \"198.51.100.0/24\", class: \"documentation\" },\n  { cidr: \"203.0.113.0/24\", class: \"documentation\" },\n  { cidr: \"224.0.0.0/4\", class: \"multicast\" },\n  { cidr: \"240.0.0.0/4\", class: \"reserved\" },\n  { cidr: \"::/128\", class: \"unspecified\" },\n  { cidr: \"::1/128\", class: \"loopback\" },\n  { cidr: \"2001:db8::/32\", class: \"documentation\" },\n  { cidr: \"fc00::/7\", class: \"unique-local\" },\n  { cidr: \"fe80::/10\", class: \"link-local\" },\n  { cidr: \"ff00::/8\", class: \"multicast\" },\n];\n\n/** The classes of the addresses that the internet does not route to a host. */\nconst NOT_ROUTED: ReadonlySet<AddressClass> = new Set([\"unspecified\", \"loopback\", \"private\", \"shared\", \"link-local\", \"unique-local\"]);\n\n/** This function gives the canonical form of an address: no spaces, no brackets, lower case, and IPv4 for a mapped IPv4 address. */\nexport function canonicalAddress(address: string): string {\n  let text = address.trim().toLowerCase();\n  if (text.startsWith(\"[\") && text.endsWith(\"]\")) text = text.slice(1, -1);\n  const mapped = /^::ffff:(\\d+\\.\\d+\\.\\d+\\.\\d+)$/.exec(text)?.[1];\n  return mapped ?? text;\n}\n\n/** This function gives the family of an IP address, or `undefined` for a text that is not an IP address. */\nexport function addressFamily(address: string): AddressFamily | undefined {\n  const family = isIP(canonicalAddress(address));\n  return family === 4 ? \"ipv4\" : family === 6 ? \"ipv6\" : undefined;\n}\n\n/** This function gives the CIDR range of a text, for example `192.0.2.0/24` or `2001:db8::/32`. An address alone is a range of one address. */\nexport function parseCidr(text: string): Result<Cidr, string> {\n  const slash = text.indexOf(\"/\");\n  const address = canonicalAddress(slash === -1 ? text : text.slice(0, slash));\n  const family = addressFamily(address);\n  if (family === undefined) return err(`\"${text}\" is not an IP address or a CIDR range.`);\n  const max = family === \"ipv4\" ? 32 : 128;\n  const prefix = slash === -1 ? String(max) : text.slice(slash + 1).trim();\n  if (!/^\\d{1,3}$/.test(prefix) || Number(prefix) > max) return err(`\"${text}\" has no prefix from 0 to ${max}.`);\n  return ok({ address, prefix: Number(prefix), family });\n}\n\n/** This function gives the text of a CIDR range. */\nexport function formatCidr(cidr: Cidr): string {\n  return `${cidr.address}/${cidr.prefix}`;\n}\n\n/** A set of CIDR ranges. */\nexport interface CidrSet {\n  readonly ranges: readonly Cidr[];\n  /** This function tells if an address is in a range of the set. A text that is not an IP address is in no set. */\n  has(address: string): boolean;\n}\n\n/** This function gives the set of some CIDR ranges. */\nexport function cidrSet(ranges: readonly Cidr[]): CidrSet {\n  const list = new BlockList();\n  for (const range of ranges) list.addSubnet(range.address, range.prefix, range.family);\n  return {\n    ranges: [...ranges],\n    has(address) {\n      const host = canonicalAddress(address);\n      const family = addressFamily(host);\n      return family !== undefined && list.check(host, family);\n    },\n  };\n}\n\n/** This function tells if an address is in a CIDR range. */\nexport function cidrContains(cidr: Cidr, address: string): boolean {\n  return cidrSet([cidr]).has(address);\n}\n\nlet classSets: readonly { readonly class: Exclude<AddressClass, \"public\">; readonly set: CidrSet }[] | undefined;\n\nfunction classes(): NonNullable<typeof classSets> {\n  classSets ??= ADDRESS_CLASSES.map((entry) => {\n    const range = parseCidr(entry.cidr);\n    if (range.tag === \"err\") throw new Error(range.error);\n    return { class: entry.class, set: cidrSet([range.value]) };\n  });\n  return classSets;\n}\n\n/** This function gives the class of an IP address, or `undefined` for a text that is not an IP address. */\nexport function addressClass(address: string): AddressClass | undefined {\n  if (addressFamily(address) === undefined) return undefined;\n  return classes().find((entry) => entry.set.has(address))?.class ?? \"public\";\n}\n\n/**\n * This function tells if the internet routes to an address. A `private` address is unspecified, loopback, private,\n * shared, link-local or unique-local. Each other address is `public`, also an address for documentation.\n */\nexport function addressKind(address: string): \"public\" | \"private\" | undefined {\n  const found = addressClass(address);\n  if (found === undefined) return undefined;\n  return NOT_ROUTED.has(found) ? \"private\" : \"public\";\n}\n"],"mappings":"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"}