@mark1russell7/netdiag 0.1.0 → 0.1.1

package/build/kinds-_NShfZpU.d.ts

@@ -0,0 +1,377 @@
+import { n as Layer } from "./layer-BNg0VYuK.js";
+import { Result } from "@mark1russell7/optional";
+import { Clock } from "@mark1russell7/algebra/clock";
+/** The kind of the host of a target: a DNS name, an IPv4 address or an IPv6 address. */
+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.
+ */
+interface Target {
+  readonly host: string;
+  readonly kind: HostKind;
+  readonly port?: number | undefined;
+}
+/** This function gives the kind of a host in its canonical form. */
+declare function hostKind(host: string): HostKind;
+/** This function gives the canonical form of a host: lower case, with no final dot and no brackets. */
+declare function canonicalHost(host: string): string;
+/** This function makes a target from a host and an optional port. */
+declare function target(host: string, port?: number): Target;
+/** This function gives the text of a target: `host`, `host:port`, or `[address]:port` for an IPv6 address. */
+declare function formatTarget(t: Target): string;
+/** This function tells if two targets have the same host and the same port. */
+declare function sameTarget(a: Target, b: Target): boolean;
+/**
+ * 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.
+ */
+declare function parseTarget(text: string): Result<Target, string>;
+/**
+ * The time of a fact, in milliseconds on the monotonic clock of the runner.
+ *
+ * The field `origin` of the runner gives the wall-clock time of one monotonic time. Thus each fact time has a wall-clock time.
+ */
+interface FactTime {
+  readonly start: number;
+  readonly end: number;
+}
+/** The source of a fact: the probe and its version, and the outside tool when the probe starts one. */
+interface FactSource {
+  readonly probe: string;
+  readonly version: string;
+  readonly tool?: string | undefined;
+}
+/**
+ * A typed fact of one layer of the network stack.
+ *
+ * A fact has a layer, a time, a source and a value. Its kind names the type of its value, for example `tcp.connect`.
+ * The subject is the target of the fact. A fact is plain data, so a record of facts is JSON.
+ */
+interface Fact<V = unknown> {
+  /** The id is unique in the facts of one runner, for example `f12`. */
+  readonly id: string;
+  readonly kind: string;
+  readonly layer: Layer;
+  readonly subject: Target;
+  readonly time: FactTime;
+  readonly source: FactSource;
+  readonly value: V;
+}
+/**
+ * The definition of a kind of fact: its name, its layer and the check of its value.
+ *
+ * The check is the contract of the value. The runner refuses a value that does not pass it, thus each fact of a kind has a
+ * value of the type `V`.
+ */
+interface FactKind<V> {
+  readonly kind: string;
+  readonly layer: Layer;
+  readonly summary: string;
+  readonly check: (value: unknown) => value is V;
+}
+/** The value type of a fact kind. */
+type ValueOf<K> = K extends FactKind<infer V> ? V : never;
+/** This function makes a fact kind. The name has lower-case words with dots, for example `tls.handshake`. */
+declare function defineFactKind<V>(spec: FactKind<V>): FactKind<V>;
+/** This function tells if a fact is of a kind, and if its value passes the check of the kind. */
+declare function isFactOf<V>(kind: FactKind<V>, fact: Fact): fact is Fact<V>;
+/** This function gives the facts of one kind, in their order. */
+declare function factsOf<V>(kind: FactKind<V>, facts: readonly Fact[]): Fact<V>[];
+/**
+ * An observation is a fact that a probe parsed, before the runner gives it an id, a layer and a source.
+ *
+ * The time is optional. Without a time, the fact gets the time of the run of the probe.
+ */
+interface Observation<V = unknown> {
+  readonly kind: FactKind<V>;
+  readonly subject: Target;
+  readonly value: V;
+  readonly time?: FactTime | undefined;
+}
+/** This function makes an observation with a type check of its value against its kind. */
+declare function observe<V>(kind: FactKind<V>, subject: Target, value: V, time?: FactTime): Observation<V>;
+/**
+ * The mode of a probe.
+ *
+ * - `active`: the probe sends packets to its peers, for example a TCP connect.
+ * - `passive`: the probe reads only the state of this computer, for example its routes. It has no peers.
+ */
+type ProbeMode = "active" | "passive";
+/** The context of a run: the clock of the runner, and the signal that stops the run. */
+interface ProbeContext {
+  readonly clock: Clock;
+  readonly signal: AbortSignal;
+}
+/** The availability of a probe on this computer. An unavailable probe tells why, for example a tool that is not installed. */
+type Availability = {
+  readonly available: true;
+  readonly version?: string | undefined;
+} | {
+  readonly available: false;
+  readonly reason: string;
+};
+/**
+ * The contract of a probe. A probe is an adapter: it tells if it is available, it does its work, and it parses its raw output into
+ * observations.
+ *
+ * - `peers` gives each host that `run` sends packets to. A passive probe gives no peers. The runner examines each peer
+ *   against the scope before `run` starts.
+ * - `run` does the effects and gives the raw output. A network failure is an observation, not an error. For example, a
+ *   TCP connect that times out gives the outcome `timeout`. `run` throws only for a fault of the probe.
+ * - `parse` is a pure function of the raw output and the input. Thus a record of a raw output gives the same facts again,
+ *   also after a correction of the parser.
+ *
+ * The input and the raw output are plain JSON data, so a record can keep them.
+ */
+interface Probe<I, R> {
+  /** The id has lower-case words with dots, for example `tcp.connect`. */
+  readonly id: string;
+  /** The version of the probe changes when its facts change. */
+  readonly version: string;
+  readonly summary: string;
+  readonly layer: Layer;
+  readonly mode: ProbeMode;
+  /** The kinds of the facts that the probe gives. The runner refuses an observation of a different kind. */
+  readonly kinds: readonly FactKind<unknown>[];
+  /** The outside tool that the probe starts, for example `ping`. A native probe has no tool. */
+  readonly tool?: string | undefined;
+  peers(input: I): readonly Target[];
+  available(context: ProbeContext): Promise<Availability>;
+  run(input: I, context: ProbeContext): Promise<R>;
+  parse(raw: R, input: I): readonly Observation[];
+}
+/** This function makes a probe, and examines its fields. */
+declare function defineProbe<I, R>(probe: Probe<I, R>): Probe<I, R>;
+/** The outcomes of a DNS query. `nodata` tells that the name exists, but it has no record of the type. */
+declare const DNS_OUTCOMES: readonly ["ok", "nodata", "nxdomain", "servfail", "refused", "timeout", "unreachable", "error"];
+type DnsOutcome = (typeof DNS_OUTCOMES)[number];
+/** The record types of a DNS query for addresses. */
+declare const RECORD_TYPES: readonly ["A", "AAAA"];
+type RecordType = (typeof RECORD_TYPES)[number];
+/** The answer of a DNS resolver to one query. */
+interface DnsAnswer {
+  readonly name: string;
+  readonly record: RecordType;
+  /** The resolver, as `address:port`. */
+  readonly resolver: string;
+  readonly outcome: DnsOutcome;
+  readonly addresses: readonly string[];
+  /** The lowest TTL of the records, in seconds. */
+  readonly ttl?: number | undefined;
+  /** The time from the query to the answer or to the failure, in milliseconds. */
+  readonly ms: number;
+  /** The error code of the platform for a failure, for example `ENOTFOUND`. */
+  readonly code?: string | undefined;
+}
+/** The fact kind `dns.answer`. */
+declare const DNS_ANSWER: FactKind<DnsAnswer>;
+/** The outcomes of a TCP connect. */
+declare const CONNECT_OUTCOMES: readonly ["connected", "refused", "timeout", "unreachable", "reset", "error"];
+type ConnectOutcome = (typeof CONNECT_OUTCOMES)[number];
+/** The outcome of one TCP connect. */
+interface TcpConnect {
+  readonly address: string;
+  readonly port: number;
+  readonly family: 4 | 6;
+  readonly outcome: ConnectOutcome;
+  /** The time from the start of the connect to the connection or to the failure, in milliseconds. */
+  readonly ms: number;
+  readonly code?: string | undefined;
+}
+/** The fact kind `tcp.connect`. */
+declare const TCP_CONNECT: FactKind<TcpConnect>;
+/**
+ * The outcomes of a TLS handshake.
+ *
+ * - `cert-error`: the handshake ended, but the certificate is not valid for the name.
+ * - `alert`: the client and the server stopped the handshake, for example because they have no version in common.
+ * - `not-tls`: the server does not speak TLS on the port.
+ * - `closed`: the server closed the connection before the end of the handshake.
+ */
+declare const HANDSHAKE_OUTCOMES: readonly ["ok", "cert-error", "alert", "not-tls", "timeout", "reset", "closed", "error"];
+type HandshakeOutcome = (typeof HANDSHAKE_OUTCOMES)[number];
+/** The roots of trust that a certificate chain ends at: a public root, a root of the computer or the user, or none. */
+declare const TRUSTS: readonly ["public", "private", "none"];
+type Trust = (typeof TRUSTS)[number];
+/** The problems of a certificate. */
+declare const CERT_PROBLEMS: readonly ["expired", "not-yet-valid", "name", "untrusted", "revoked", "other"];
+type CertProblem = (typeof CERT_PROBLEMS)[number];
+/** The certificate of a server. */
+interface TlsCertificate {
+  readonly subject: string;
+  readonly issuer: string;
+  /** The DNS names and the IP addresses of the certificate. */
+  readonly names: readonly string[];
+  /** The start of the validity, as an ISO 8601 time. */
+  readonly validFrom: string;
+  /** The end of the validity, as an ISO 8601 time. */
+  readonly validTo: string;
+  readonly fingerprint256: string;
+  readonly selfSigned: boolean;
+  /** The number of certificates from the certificate of the server to the root, with both. */
+  readonly chain: number;
+  /** The root that the chain ends at. A failed check of the certificate does not change it. */
+  readonly trust: Trust;
+  readonly problem?: CertProblem | undefined;
+}
+/** The outcome of one TLS handshake. */
+interface TlsHandshake {
+  readonly address: string;
+  readonly port: number;
+  readonly servername?: string | undefined;
+  readonly outcome: HandshakeOutcome;
+  /** The time from the TCP connection to the end of the handshake or to the failure, in milliseconds. */
+  readonly ms: number;
+  /** The TLS version, for example `TLSv1.3`. */
+  readonly protocol?: string | undefined;
+  readonly cipher?: string | undefined;
+  /** The application protocol that the server chose with ALPN, for example `http/1.1`. */
+  readonly alpn?: string | undefined;
+  readonly code?: string | undefined;
+  readonly certificate?: TlsCertificate | undefined;
+}
+/** The fact kind `tls.handshake`. */
+declare const TLS_HANDSHAKE: FactKind<TlsHandshake>;
+/**
+ * The outcomes of an HTTP request.
+ *
+ * - `response`: the server sent a response. Its status can be an error.
+ * - `protocol`: the server sent bytes that are not HTTP.
+ * - `closed`: the server closed the connection before the response.
+ */
+declare const HTTP_OUTCOMES: readonly ["response", "protocol", "timeout", "reset", "closed", "error"];
+type HttpOutcome = (typeof HTTP_OUTCOMES)[number];
+/** The outcome of one HTTP request. */
+interface HttpResponse {
+  readonly address: string;
+  readonly port: number;
+  readonly scheme: "http" | "https";
+  readonly method: "GET" | "HEAD";
+  /** The value of the `Host` field of the request. */
+  readonly host: string;
+  readonly path: string;
+  readonly outcome: HttpOutcome;
+  readonly status?: number | undefined;
+  /** The HTTP version of the response, for example `1.1`. */
+  readonly version?: string | undefined;
+  /** Some fields of the response head, with lower-case names: `server`, `via`, `location` and others. */
+  readonly fields: Readonly<Record<string, string>>;
+  /** The bytes of the body that the probe read. */
+  readonly bytes: number;
+  /** The probe stopped the read of the body at its limit. */
+  readonly truncated: boolean;
+  /** The time from the request to the head of the response, in milliseconds. */
+  readonly ttfbMs?: number | undefined;
+  /** The time from the request to the end of the response or to the failure, in milliseconds. */
+  readonly ms: number;
+  readonly code?: string | undefined;
+}
+/** The fact kind `http.response`. */
+declare const HTTP_RESPONSE: FactKind<HttpResponse>;
+/** The fact kinds of the native probes. */
+declare const NATIVE_KINDS: readonly FactKind<unknown>[];
+/**
+ * The outcomes of the ICMP echo requests to one address.
+ *
+ * - `reply`: one or more echo replies came back.
+ * - `none`: no reply came back in the time limit.
+ * - `unreachable`: no echo reply came back, and a router or this computer told that the address is unreachable.
+ * - `error`: the tool did not start, or netdiag cannot read its output.
+ */
+declare const ECHO_OUTCOMES: readonly ["reply", "none", "unreachable", "error"];
+type EchoOutcome = (typeof ECHO_OUTCOMES)[number];
+/** The result of the ICMP echo requests to one address. */
+interface IcmpEcho {
+  readonly address: string;
+  readonly outcome: EchoOutcome;
+  /** The number of echo requests that the tool sent. */
+  readonly sent: number;
+  /** The number of echo replies. A message of an unreachable address is not a reply. */
+  readonly received: number;
+  /** The round-trip time of each reply, in milliseconds. */
+  readonly rttMs: readonly number[];
+  /** The TTL (IPv4) or the hop limit (IPv6) of the first reply. */
+  readonly ttl?: number | undefined;
+  /** The router that told that the address is unreachable. */
+  readonly from?: string | undefined;
+  /** The text of the tool for the outcomes `unreachable` and `error`. */
+  readonly detail?: string | undefined;
+}
+/** The fact kind `icmp.echo`. */
+declare const ICMP_ECHO: FactKind<IcmpEcho>;
+/**
+ * The outcomes of a trace of the path to an address.
+ *
+ * - `reached`: the address answered at the last hop.
+ * - `stopped`: the last hop is not the address, and no router told that the address is unreachable.
+ * - `unreachable`: a router or this computer told that the address is unreachable.
+ * - `error`: the tool failed, or netdiag cannot read its output.
+ */
+declare const TRACE_OUTCOMES: readonly ["reached", "stopped", "unreachable", "error"];
+type TraceOutcome = (typeof TRACE_OUTCOMES)[number];
+/** One hop of a trace: the answers to the probes with one TTL. */
+interface TraceHop {
+  /** The TTL (IPv4) or the hop limit (IPv6) of the probes, from 1. */
+  readonly ttl: number;
+  /** The addresses that answered, in the order of their first answer. */
+  readonly addresses: readonly string[];
+  /** The number of probes that the tool sent with this TTL. */
+  readonly sent: number;
+  /** The number of answers. */
+  readonly received: number;
+  /** The round-trip time of each answer that has a time, in milliseconds. */
+  readonly rttMs: readonly number[];
+  /** The message of an unreachable address at this hop, for example `host unreachable (!H)`. */
+  readonly unreachable?: string | undefined;
+}
+/** The trace of the path to one address: the hops of the tool `traceroute`, or `tracert` on Windows. */
+interface PathTrace {
+  readonly address: string;
+  readonly outcome: TraceOutcome;
+  /** The largest TTL of the probes. */
+  readonly maxHops: number;
+  /** The hops in the order of their TTL. An `error` keeps the hops before the failure. */
+  readonly hops: readonly TraceHop[];
+  /** The text of the tool for the outcomes `unreachable` and `error`. */
+  readonly detail?: string | undefined;
+}
+/** The fact kind `path.trace`. */
+declare const PATH_TRACE: FactKind<PathTrace>;
+/** One hop of a report of `mtr`: the counts and the times of many cycles of probes with one TTL. */
+interface ReportHop {
+  readonly ttl: number;
+  /** The address that answered. A hop with no answer has no address. */
+  readonly address?: string | undefined;
+  /** The number of probes that the tool sent with this TTL. */
+  readonly sent: number;
+  /** The number of answers. The adapter calculates it from the loss and the number of probes of the report. */
+  readonly received: number;
+  /** The best round-trip time, in milliseconds. Only a hop with answers has the times. */
+  readonly bestMs?: number | undefined;
+  /** The mean round-trip time, in milliseconds. */
+  readonly meanMs?: number | undefined;
+  /** The worst round-trip time, in milliseconds. */
+  readonly worstMs?: number | undefined;
+}
+/** The report of the tool `mtr` for the path to one address. */
+interface PathReport {
+  readonly address: string;
+  /** The outcome. A report of `mtr` has no messages of an unreachable address, so it does not have the outcome `unreachable`. */
+  readonly outcome: TraceOutcome;
+  /** The number of cycles of probes. */
+  readonly cycles: number;
+  readonly hops: readonly ReportHop[];
+  /** The text of the tool for the outcome `error`. */
+  readonly detail?: string | undefined;
+}
+/** The fact kind `path.report`. */
+declare const PATH_REPORT: FactKind<PathReport>;
+/** The fact kinds of the adapters of outside tools (`@mark1russell7/netdiag/tools`). */
+declare const TOOL_KINDS: readonly FactKind<unknown>[];
+export { HostKind as $, TRACE_OUTCOMES as A, ProbeContext as B, PathTrace as C, TCP_CONNECT as D, ReportHop as E, TraceHop as F, FactSource as G, defineProbe as H, TraceOutcome as I, ValueOf as J, FactTime as K, Trust as L, TcpConnect as M, TlsCertificate as N, TLS_HANDSHAKE as O, TlsHandshake as P, observe as Q, Availability as R, PathReport as S, RecordType as T, Fact as U, ProbeMode as V, FactKind as W, factsOf as X, defineFactKind as Y, isFactOf as Z, ICMP_ECHO as _, DNS_ANSWER as a, sameTarget as at, PATH_REPORT as b, DnsOutcome as c, HANDSHAKE_OUTCOMES as d, Target as et, HTTP_OUTCOMES as f, HttpResponse as g, HttpOutcome as h, ConnectOutcome as i, parseTarget as it, TRUSTS as j, TOOL_KINDS as k, ECHO_OUTCOMES as l, HandshakeOutcome as m, CONNECT_OUTCOMES as n, formatTarget as nt, DNS_OUTCOMES as o, target as ot, HTTP_RESPONSE as p, Observation as q, CertProblem as r, hostKind as rt, DnsAnswer as s, CERT_PROBLEMS as t, canonicalHost as tt, EchoOutcome as u, IcmpEcho as v, RECORD_TYPES as w, PATH_TRACE as x, NATIVE_KINDS as y, Probe as z };
+//# sourceMappingURL=kinds-_NShfZpU.d.ts.map

package/build/kinds-_NShfZpU.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds-_NShfZpU.d.ts","names":[],"sources":["../src/target.ts","../src/fact.ts","../src/probe.ts","../src/kinds.ts"],"mappings":";;;;KAIY;;;;;;UAOK;WACN;WACA,MAAM;WACN;;;iBAcK,SAAS,eAAe;;iBAQxB,cAAc;;iBAQd,OAAO,cAAc,gBAAgB;;iBAMrC,aAAa,GAAG;;iBAMhB,WAAW,GAAG,QAAQ,GAAG;;;;;;;;iBAwBzB,YAAY,eAAe,OAAO;;;;;;UCxEjC;WACN;WACA;;;UAIM;WACN;WACA;WACA;;;;;;;;UASM,KAAK;;WAEX;WACA;WACA,OAAO;WACP,SAAS;WACT,MAAM;WACN,QAAQ;WACR,OAAO;;;;;;;;UASD,SAAS;WACf;WACA,OAAO;WACP;WACA,QAAQ,mBAAmB,SAAS;;;KAInC,QAAQ,KAAK,UAAU,eAAe,KAAK;;iBAKvC,eAAe,GAAG,MAAM,SAAS,KAAK,SAAS;;iBAM/C,SAAS,GAAG,MAAM,SAAS,IAAI,MAAM,OAAO,QAAQ,KAAK;;iBAKzD,QAAQ,GAAG,MAAM,SAAS,IAAI,gBAAgB,SAAS,KAAK;;;;;;UAS3D,YAAY;WAClB,MAAM,SAAS;WACf,SAAS;WACT,OAAO;WACP,OAAO;;;iBAIF,QAAQ,GAAG,MAAM,SAAS,IAAI,SAAS,QAAQ,OAAO,GAAG,OAAO,WAAW,YAAY;;;;;;;KCzE3F;;UAGK;WACN,OAAO;WACP,QAAQ;;;KAIP;WACG;WAA0B;;WAC1B;WAA2B;;;;;;;;;;;;;;;UAezB,MAAM,GAAG;;WAEf;;WAEA;WACA;WACA,OAAO;WACP,MAAM;;WAEN,gBAAgB;;WAEhB;EACT,MAAM,OAAO,aAAa;EAC1B,UAAU,SAAS,eAAe,QAAQ;EAC1C,IAAI,OAAO,GAAG,SAAS,eAAe,QAAQ;EAC9C,MAAM,KAAK,GAAG,OAAO,aAAa;;;iBAIpB,YAAY,GAAG,GAAG,OAAO,MAAM,GAAG,KAAK,MAAM,GAAG;;cCnBnD;KACD,qBAAqB;;cAGpB;KACD,qBAAqB;;UAGhB;WACN;WACA,QAAQ;;WAER;WACA,SAAS;WACT;;WAEA;;WAEA;;WAEA;;;cAIE,YAAY,SAAS;;cAkBrB;KACD,yBAAyB;;UAGpB;WACN;WACA;WACA;WACA,SAAS;;WAET;WACA;;;cAIE,aAAa,SAAS;;;;;;;;;cAsBtB;KACD,2BAA2B;;cAG1B;KACD,gBAAgB;;cAGf;KACD,sBAAsB;;UAGjB;WACN;WACA;;WAEA;;WAEA;;WAEA;WACA;WACA;;WAEA;;WAEA,OAAO;WACP,UAAU;;;UAIJ;WACN;WACA;WACA;WACA,SAAS;;WAET;;WAEA;WACA;;WAEA;WACA;WACA,cAAc;;;cAsBZ,eAAe,SAAS;;;;;;;;cAyBxB;KACD,sBAAsB;;UAGjB;WACN;WACA;WACA;WACA;;WAEA;WACA;WACA,SAAS;WACT;;WAEA;;WAEA,QAAQ,SAAS;;WAEjB;;WAEA;;WAEA;;WAEA;WACA;;;cAIE,eAAe,SAAS;;cA4BxB,uBAAuB;;;;;;;;;cAUvB;KACD,sBAAsB;;UAGjB;WACN;WACA,SAAS;;WAET;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;cAIE,WAAW,SAAS;;;;;;;;;cA4BpB;KACD,uBAAuB;;UAGlB;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;UAIM;WACN;WACA,SAAS;;WAET;;WAEA,eAAe;;WAEf;;;cA0BE,YAAY,SAAS;;UAiBjB;WACN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;UAIM;WACN;;WAEA,SAAS;;WAET;WACA,eAAe;;WAEf;;;cAoBE,aAAa,SAAS;;cAkBtB,qBAAqB"}

package/build/layer-BNg0VYuK.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The layers of the network stack that netdiag examines, from the bottom to the top.
+ *
+ * - `link`: the network interface and its physical link.
+ * - `wifi`: the Wi-Fi link: the signal, the channel and the rate.
+ * - `ip`: the addresses of the interfaces.
+ * - `route`: the routes of this computer and its gateway.
+ * - `path`: the hops through the provider networks to the remote host.
+ * - `dns`: the resolution of names to addresses.
+ * - `tcp`: the connections to a port.
+ * - `tls`: the handshake and the certificate of the server.
+ * - `http`: the request and the response.
+ */
+declare const LAYERS: readonly ["link", "wifi", "ip", "route", "path", "dns", "tcp", "tls", "http"];
+/** A layer of the network stack. The list `LAYERS` gives each layer in its order. */
+type Layer = (typeof LAYERS)[number];
+/** This function tells if a value is the name of a layer. */
+declare function isLayer(value: unknown): value is Layer;
+/** This function gives the position of a layer in `LAYERS`. The bottom layer `link` has the position 0. */
+declare function layerRank(layer: Layer): number;
+export { layerRank as i, Layer as n, isLayer as r, LAYERS as t };
+//# sourceMappingURL=layer-BNg0VYuK.d.ts.map

package/build/layer-BNg0VYuK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer-BNg0VYuK.d.ts","names":[],"sources":["../src/layer.ts"],"mappings":";;;;;;;;;;;;;cAaa;;KAGD,gBAAgB;;iBAKZ,QAAQ,iBAAiB,SAAS;;iBAKlC,UAAU,OAAO"}

package/build/tools.d.ts

@@ -0,0 +1,206 @@
+import { B as ProbeContext, C as PathTrace, R as Availability, S as PathReport, v as IcmpEcho, z as Probe } from "./kinds-_NShfZpU.js";
+/**
+ * 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).
+ */
+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. */
+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.
+ */
+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. */
+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 declare 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. */
+export declare 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.
+ */
+export declare function availabilityOf(tool: string, output: ToolOutput, version?: RegExp): Availability;
+/** A command of an outside tool: the program, its arguments, its time limit and the environment variables to add. */
+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 declare function runTool(host: ToolHost, tool: ToolCommand, context: ProbeContext): Promise<ToolRaw>;
+/**
+ * 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.
+ */
+type ToolUse = "adapter" | "not-bundled";
+/** A row of the table of the licenses of the outside tools. */
+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 declare const TOOL_LICENSES: readonly ToolLicense[];
+/** This function gives the row of a tool, or `undefined` for a tool that is not in the table. */
+export declare function toolLicense(tool: string): ToolLicense | undefined;
+/** The input of the ping probe: echo requests to one IP address. */
+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 declare const DEFAULT_PING_COUNT = 4;
+/** The default time to wait for each reply, in milliseconds. */
+export declare const DEFAULT_PING_WAIT_MS = 1e3;
+/** The largest number of echo requests in one input. */
+export declare 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 declare 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 declare const PING6_LAST_WAIT_MS = 1e4;
+/**
+ * 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 declare function pingCommand(platform: string, input: PingInput): ToolCommand | undefined;
+/** This function tells if ping is available on the host. On Linux, netdiag reads only the ping of iputils. */
+export declare function pingAvailability(host: ToolHost, context: ProbeContext): Promise<Availability>;
+/**
+ * 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 declare function readPing(raw: ToolRaw, address: string): IcmpEcho;
+/**
+ * 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 declare function pingProbe(host: ToolHost): Probe<PingInput, ToolRaw>;
+/** The input of the traceroute probe: the path to one IP address. */
+interface TraceInput {
+  readonly address: string;
+  /** The largest TTL. The default is `DEFAULT_TRACE_HOPS`. */
+  readonly maxHops?: number | undefined;
+  /** The time to wait for each answer, in milliseconds. On Linux and macOS, the tool rounds it up to full seconds. */
+  readonly waitMs?: number | undefined;
+}
+/** The default largest TTL. */
+export declare const DEFAULT_TRACE_HOPS = 30;
+/** The largest TTL of one input. */
+export declare const MAX_TRACE_HOPS = 64;
+/** The default time to wait for each answer, in milliseconds. */
+export declare const DEFAULT_TRACE_WAIT_MS = 1e3;
+/** The number of probes for each TTL. `tracert` on Windows always sends 3 probes. */
+export declare const TRACE_QUERIES = 3;
+/**
+ * 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.
+ */
+export declare function tracerouteCommand(platform: string, input: TraceInput): ToolCommand | undefined;
+/** This function tells if traceroute is available on the host. On Linux, netdiag reads only the Modern traceroute for Linux. */
+export declare function tracerouteAvailability(host: ToolHost, context: ProbeContext): Promise<Availability>;
+/**
+ * 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.
+ */
+export declare function readTraceroute(raw: ToolRaw, input: {
+  readonly address: string;
+  readonly maxHops?: number | undefined;
+}): PathTrace;
+/**
+ * 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.
+ */
+export declare function tracerouteProbe(host: ToolHost): Probe<TraceInput, ToolRaw>;
+/** The input of the mtr probe: many cycles of probes on the path to one IP address. */
+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 declare const DEFAULT_MTR_CYCLES = 20;
+/** The largest number of cycles of one input. */
+export declare const MAX_MTR_CYCLES = 100;
+/** The time that mtr waits for the last answers after the last cycle, in milliseconds (its option `--gracetime`). */
+export declare const MTR_GRACE_MS = 5e3;
+/**
+ * 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 declare function mtrCommand(platform: string, input: MtrInput): ToolCommand | undefined;
+/** This function tells if mtr is available on the host. The adapter knows Linux and macOS. */
+export declare function mtrAvailability(host: ToolHost, context: ProbeContext): Promise<Availability>;
+/**
+ * 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 declare function readMtr(raw: ToolRaw, input: {
+  readonly address: string;
+  readonly cycles?: number | undefined;
+}): PathReport;
+/** This function makes the probe `path.mtr`: many cycles of probes on the path to one IP address with the tool mtr. */
+export declare function mtrProbe(host: ToolHost): Probe<MtrInput, ToolRaw>;
+export type { MtrInput, PingInput, ToolCommand, ToolHost, ToolLicense, ToolOutput, ToolRaw, ToolRunOptions, ToolUse, TraceInput };
+//# sourceMappingURL=tools.d.ts.map

package/build/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","names":[],"sources":["../src/tools/host.ts","../src/tools/licenses.ts","../src/tools/ping.ts","../src/tools/traceroute.ts","../src/tools/mtr.ts"],"mappings":";;;;;;UAOiB;;WAEN;WACA;WACA;;WAEA;;WAEA;;;UAIM;;WAEN;WACA,QAAQ;;WAER,MAAM,SAAS;;;;;;;;UAST;WACN;EACT,IAAI,iBAAiB,yBAAyB,SAAS,iBAAiB,QAAQ;;;UAIjE,gBAAgB;WACtB;WACA;WACA;WACA;WACA;;;qBAIE;;qBAGA;;;;;wBAMG,eAAe,cAAc,QAAQ,YAAY,UAAU,SAAS;;UAOnE;WACN;WACA;WACA;WACA,MAAM,SAAS;;;wBAIJ,QAAQ,MAAM,UAAU,MAAM,aAAa,SAAS,eAAe,QAAQ;;;;;;;KClErF;;UAGK;;WAEN;WACA;WACA,KAAK;;WAEL;;;;;;qBAOE,wBAAwB;;wBAYrB,YAAY,eAAe;;UCrB1B;WACN;;WAEA;;WAEA;;;qBAIE;;qBAGA;;qBAGA;;qBAGA;;;;;qBAMA;;;;;;;;;wBAuBG,YAAY,kBAAkB,OAAO,YAAY;;wBAqC3C,iBAAiB,MAAM,UAAU,SAAS,eAAe,QAAQ;;;;;;;wBA0FvE,SAAS,KAAK,SAAS,kBAAkB;;;;;wBAyBzC,UAAU,MAAM,WAAW,MAAM,WAAW;;UCxM3C;WACN;;WAEA;;WAEA;;;qBAIE;;qBAGA;;qBAGA;;qBAGA;;;;;;;;;;;wBAyBG,kBAAkB,kBAAkB,OAAO,aAAa;;wBAyBlD,uBAAuB,MAAM,UAAU,SAAS,eAAe,QAAQ;;;;;;;wBA4L7E,eAAe,KAAK,SAAS;WAAkB;WAA0B;IAAiC;;;;;wBA0B1G,gBAAgB,MAAM,WAAW,MAAM,YAAY;;UC1RlD;WACN;;WAEA;;WAEA;;;qBAIE;;qBAGA;;qBAGA;;;;;wBAmBG,WAAW,kBAAkB,OAAO,WAAW;;wBAYzC,gBAAgB,MAAM,UAAU,SAAS,eAAe,QAAQ;;;;;;;wBAyDtE,QAAQ,KAAK,SAAS;WAAkB;WAA0B;IAAgC;;wBAsBlG,SAAS,MAAM,WAAW,MAAM,UAAU"}