@mark1russell7/netdiag 0.0.0-stage → 0.1.1

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"}