@mark1russell7/netdiag-cli 0.0.0-bootstrap.0 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +114 -1
- package/build/bin.d.ts +1 -0
- package/build/bin.js +7 -0
- package/build/bin.js.map +1 -0
- package/build/cli-CaUDBEoh.js +468 -0
- package/build/cli-CaUDBEoh.js.map +1 -0
- package/build/index.d.ts +213 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +1 -0
- package/package.json +68 -4
- package/src/bin.ts +5 -0
- package/src/check.ts +50 -0
- package/src/cli.ts +81 -0
- package/src/index.ts +11 -0
- package/src/next.ts +197 -0
- package/src/plan.ts +180 -0
- package/src/report.ts +149 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mark Russell
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,116 @@
|
|
|
1
1
|
# @mark1russell7/netdiag-cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The command line of netdiag. The command `netdiag check` probes a target. Then it gives the probable causes of a fault, their probabilities and the next step.
|
|
4
|
+
|
|
5
|
+
**State: ND-8 of the [roadmap](../../docs/ROADMAP.md).** The core model is in [`@mark1russell7/netdiag`](../netdiag/README.md). This package keeps the dependencies of the command line out of the core.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install --global @mark1russell7/netdiag-cli
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
The program needs Node.js 22.12 or later. The program `ping` is optional. Without it, the check sends no ICMP echo request.
|
|
14
|
+
|
|
15
|
+
## The command
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
netdiag check <target> [options]
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
The target is a DNS name, an IP address, `host:port` or a URL. A URL also gives the scheme, the port and the path.
|
|
22
|
+
|
|
23
|
+
The check has these steps:
|
|
24
|
+
|
|
25
|
+
1. It asks the DNS resolver for the IPv4 and IPv6 addresses of each name.
|
|
26
|
+
2. It pings each address, connects to it, does the TLS handshake and sends one HTTP request.
|
|
27
|
+
3. It reads the facts into evidence. The catalog of faults gives the probability of each cause.
|
|
28
|
+
4. It finds the probe with the largest information gain over the 3 most probable causes. This probe is the next step.
|
|
29
|
+
|
|
30
|
+
## The options
|
|
31
|
+
|
|
32
|
+
| Option | Default | What it does |
|
|
33
|
+
| --- | --- | --- |
|
|
34
|
+
| `--port <port>` | The port of the target, then the port of the scheme | It sets the port of the HTTP request, from 1 to 65535. |
|
|
35
|
+
| `--scheme <scheme>` | The scheme of a URL, then `https` | It sets the scheme of the HTTP request: `http` or `https`. |
|
|
36
|
+
| `--path <path>` | The path of a URL, then `/` | It sets the path of the HTTP request. The path starts with `/`. |
|
|
37
|
+
| `--reference <host>` | None | It adds a host that works for you. The check probes it for a comparison. Give the option again for more hosts. |
|
|
38
|
+
| `--resolver <address>` | The first resolver of the computer | It sets the DNS resolver: an IP address with an optional port. |
|
|
39
|
+
| `--gateway <address>` | None | It adds the IP address of your router. The check pings it. |
|
|
40
|
+
| `--grant <cidr>` | None | It adds a CIDR range that you own. Give the option again for more ranges. |
|
|
41
|
+
| `--ping-count <count>` | 4 | It sets the number of echo requests to each address, from 0 to 100. A measure of the loss needs 20 or more. |
|
|
42
|
+
| `--json` | Off | It writes the whole report as JSON. |
|
|
43
|
+
| `--help` | Off | It shows the options. |
|
|
44
|
+
| `--version` | Off | It shows the version. |
|
|
45
|
+
|
|
46
|
+
The exit code is 0 after a check. It is 1 for an option that is not valid. A fault of the network does not change the exit code.
|
|
47
|
+
|
|
48
|
+
## The scope rule
|
|
49
|
+
|
|
50
|
+
netdiag sends packets only to the hosts that you name or own. The check grants only these hosts:
|
|
51
|
+
|
|
52
|
+
- the target and each reference host
|
|
53
|
+
- the DNS resolver, from `--resolver` or from the computer
|
|
54
|
+
- the gateway, when you give `--gateway`
|
|
55
|
+
- each range of `--grant`
|
|
56
|
+
- each address that the resolver gives for a granted name
|
|
57
|
+
|
|
58
|
+
The check sends no packet to another host. A grant with a problem stops the check before the first probe. Thus a typing error cannot make the scope wider.
|
|
59
|
+
|
|
60
|
+
## The output
|
|
61
|
+
|
|
62
|
+
In this example, no program listens on port 443 of the target. The reference host works. The names and the addresses are examples.
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
$ netdiag check shop.example.com --reference example.org
|
|
66
|
+
netdiag check shop.example.com (https, path /)
|
|
67
|
+
|
|
68
|
+
The probable causes
|
|
69
|
+
89% No program listens on the port.
|
|
70
|
+
To do: Start the service, or use the correct port.
|
|
71
|
+
2% A device on the path resets the connections.
|
|
72
|
+
To do: Examine the firewalls and the filters of content on the path, and try a different network.
|
|
73
|
+
1% A filter drops the packets to the port.
|
|
74
|
+
To do: Examine the firewall rules of the host and of each network on the path.
|
|
75
|
+
|
|
76
|
+
The next step (it can give 0.01 bits of information about the causes)
|
|
77
|
+
Run the check again with --ping-count 20.
|
|
78
|
+
|
|
79
|
+
12 observations from 8 facts. The option --json gives each fact.
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The probabilities come from the evidence of this check only. The next step is the option or the probe that gives the most information about the 3 most probable causes. Its gain is in bits. A small gain tells that no probe can change the probabilities much.
|
|
83
|
+
|
|
84
|
+
## The JSON report
|
|
85
|
+
|
|
86
|
+
The option `--json` writes the object `CheckReport` in the format `netdiag-check/1`.
|
|
87
|
+
|
|
88
|
+
| Field | What it is |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| `format` | The text `netdiag-check/1`. |
|
|
91
|
+
| `target`, `scheme`, `path` | The target as `host` or `host:port`, and the HTTP request. |
|
|
92
|
+
| `grants` | The grants of the scope of the check. |
|
|
93
|
+
| `causes` | Each cause with its probability, from the most probable. |
|
|
94
|
+
| `next` | The next step, or `null` when no probe can tell more. |
|
|
95
|
+
| `choices` | Each next step with a gain, from the largest gain. |
|
|
96
|
+
| `problems` | Each probe that did not end, with its role and its host. |
|
|
97
|
+
| `evidence` | The evidence that the diagnosis used. |
|
|
98
|
+
| `ignored`, `skipped` | The evidence and the facts that the diagnosis did not use, with the reason. |
|
|
99
|
+
| `facts` | Each fact of the visit, with its role and its host. |
|
|
100
|
+
|
|
101
|
+
## The API
|
|
102
|
+
|
|
103
|
+
The pure parts of the command are also exports. A program can use them with its own probes.
|
|
104
|
+
|
|
105
|
+
| Export | What it does |
|
|
106
|
+
| --- | --- |
|
|
107
|
+
| `planCheck(options, system)` | It gives the plan of a check with the grants of its scope, or each problem of the options. |
|
|
108
|
+
| `reportOf(plan, steps)` | It gives the report of the steps of a visit. |
|
|
109
|
+
| `formatReport(report)` | It gives the lines of the text output. |
|
|
110
|
+
| `nextSteps(diagnosis, plan, addressed)` | It gives the next steps, from the largest gain. |
|
|
111
|
+
| `check(options, deps)` | It plans a check, starts the visit with the given clock and tool host, and gives the report. |
|
|
112
|
+
| `createNetdiagCli(options)` | It makes the command line with a given check, output and terminal. |
|
|
113
|
+
|
|
114
|
+
## License
|
|
115
|
+
|
|
116
|
+
MIT
|
package/build/bin.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {}
|
package/build/bin.js
ADDED
package/build/bin.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bin.js","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n// The program `netdiag`. The function `main` has the command line. This file only starts it.\nimport { main } from \"./cli.ts\";\n\nprocess.exitCode = await main(process.argv.slice(2));\n"],"mappings":";;;AAIA,QAAQ,WAAW,MAAM,KAAK,QAAQ,KAAK,MAAM,CAAC,CAAC"}
|
|
@@ -0,0 +1,468 @@
|
|
|
1
|
+
import { DNS_ANSWER, GAIN_RESOLUTION, HTTP_RESPONSE, ICMP_ECHO, LOSS_MIN_SENT, STANDARD_CATALOG, TCP_CONNECT, TLS_HANDSHAKE, canonicalHost, diagnose, featuresOf, formatTarget, grantProblems, hostKind, isFactOf, namedGrant, parseTarget, rankProbes, readEvidence, visitTarget } from "@mark1russell7/netdiag";
|
|
2
|
+
import { DEFAULT_PING_COUNT, MAX_PING_COUNT, commandHost } from "@mark1russell7/netdiag/tools";
|
|
3
|
+
import { err, ok } from "@mark1russell7/optional";
|
|
4
|
+
import { countOf } from "@mark1russell7/text";
|
|
5
|
+
import { pad } from "@mark1russell7/text/length";
|
|
6
|
+
import { getServers } from "node:dns";
|
|
7
|
+
import { realClock } from "@mark1russell7/algebra/clock";
|
|
8
|
+
import { runCommand } from "@procedures/shell/command";
|
|
9
|
+
import { readFileSync } from "node:fs";
|
|
10
|
+
import { createProcedureCli } from "@procedures/cli-kit";
|
|
11
|
+
import { defineProcedure } from "@procedures/client";
|
|
12
|
+
import { z } from "zod";
|
|
13
|
+
// src/plan.ts
|
|
14
|
+
/** The schemes of the HTTP request of a check. */
|
|
15
|
+
const SCHEMES = ["http", "https"];
|
|
16
|
+
function isScheme(text) {
|
|
17
|
+
return SCHEMES.includes(text);
|
|
18
|
+
}
|
|
19
|
+
/** This function reads a host of the user. A URL also gives a scheme and a path. Only a port in the text stays in the target. */
|
|
20
|
+
function locate(text, what) {
|
|
21
|
+
const parsed = parseTarget(text);
|
|
22
|
+
if (parsed.tag === "err") return err(`The ${what} is not valid. ${parsed.error}`);
|
|
23
|
+
if (!text.includes("://")) return ok({ target: parsed.value });
|
|
24
|
+
const url = new URL(text.trim());
|
|
25
|
+
const scheme = url.protocol.slice(0, -1);
|
|
26
|
+
if (!isScheme(scheme)) return err(`The ${what} "${text}" has the scheme ${scheme}. A check sends HTTP and HTTPS requests only.`);
|
|
27
|
+
const host = {
|
|
28
|
+
host: parsed.value.host,
|
|
29
|
+
kind: parsed.value.kind
|
|
30
|
+
};
|
|
31
|
+
const target = url.port === "" ? host : {
|
|
32
|
+
...host,
|
|
33
|
+
port: Number(url.port)
|
|
34
|
+
};
|
|
35
|
+
return ok({
|
|
36
|
+
target,
|
|
37
|
+
scheme,
|
|
38
|
+
path: `${url.pathname}${url.search}`
|
|
39
|
+
});
|
|
40
|
+
}
|
|
41
|
+
/** This function gives a grant of one IP address. */
|
|
42
|
+
function addressGrant(address, basis, note) {
|
|
43
|
+
return {
|
|
44
|
+
...namedGrant(address, note),
|
|
45
|
+
basis
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
function visitHost(target) {
|
|
49
|
+
return target.port === void 0 ? { host: target.host } : {
|
|
50
|
+
host: target.host,
|
|
51
|
+
port: target.port
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
function whole(value, low, high) {
|
|
55
|
+
return Number.isInteger(value) && value >= low && value <= high;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* This function gives the plan of a check from the options of the command line, or each problem of the options.
|
|
59
|
+
*
|
|
60
|
+
* The grants of the plan are the scope rule of the command. The plan grants only these hosts:
|
|
61
|
+
*
|
|
62
|
+
* - the target, and each reference host, with the basis `named`
|
|
63
|
+
* - the DNS resolver, with the basis `named` from `--resolver`, or `configured` from the computer
|
|
64
|
+
* - the gateway, when the user gives it, with the basis `named`
|
|
65
|
+
* - each range of `--grant`, with the basis `owned`
|
|
66
|
+
*
|
|
67
|
+
* The visit also puts in the scope the addresses that the resolver gives for a named host.
|
|
68
|
+
*/
|
|
69
|
+
function planCheck(options, system) {
|
|
70
|
+
const problems = [];
|
|
71
|
+
const grants = [];
|
|
72
|
+
const located = locate(options.target, "target");
|
|
73
|
+
if (located.tag === "err") return err([located.error]);
|
|
74
|
+
const scheme = options.scheme ?? located.value.scheme ?? "https";
|
|
75
|
+
const path = options.path ?? located.value.path ?? "/";
|
|
76
|
+
if (!isScheme(scheme)) problems.push(`The scheme ${String(scheme)} is not http or https.`);
|
|
77
|
+
if (!path.startsWith("/")) problems.push(`The path "${path}" does not start with "/".`);
|
|
78
|
+
const port = options.port ?? located.value.target.port;
|
|
79
|
+
if (port !== void 0 && !whole(port, 1, 65535)) problems.push(`The port ${port} is not an integer from 1 to 65535.`);
|
|
80
|
+
const pingCount = options.pingCount ?? DEFAULT_PING_COUNT;
|
|
81
|
+
if (!whole(pingCount, 0, MAX_PING_COUNT)) problems.push(`The ping count ${pingCount} is not an integer from 0 to ${MAX_PING_COUNT}.`);
|
|
82
|
+
const target = port === void 0 ? {
|
|
83
|
+
host: located.value.target.host,
|
|
84
|
+
kind: located.value.target.kind
|
|
85
|
+
} : {
|
|
86
|
+
...located.value.target,
|
|
87
|
+
port
|
|
88
|
+
};
|
|
89
|
+
grants.push(namedGrant(target, "the target"));
|
|
90
|
+
const references = [];
|
|
91
|
+
for (const text of options.reference ?? []) {
|
|
92
|
+
const reference = locate(text, "reference");
|
|
93
|
+
if (reference.tag === "err") problems.push(reference.error);
|
|
94
|
+
else {
|
|
95
|
+
references.push(visitHost(reference.value.target));
|
|
96
|
+
grants.push(namedGrant(reference.value.target, "a reference host"));
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
let resolver;
|
|
100
|
+
const resolverText = options.resolver ?? system.resolvers[0];
|
|
101
|
+
if (resolverText !== void 0) {
|
|
102
|
+
const from = options.resolver === void 0 ? "The DNS resolver of the computer" : "The DNS resolver";
|
|
103
|
+
const parsed = parseTarget(resolverText);
|
|
104
|
+
if (parsed.tag === "err") problems.push(`${from} is not valid. ${parsed.error}`);
|
|
105
|
+
else if (parsed.value.kind === "name") problems.push(`${from} "${resolverText}" is not an IP address.`);
|
|
106
|
+
else {
|
|
107
|
+
resolver = parsed.value.port === void 0 ? { address: parsed.value.host } : {
|
|
108
|
+
address: parsed.value.host,
|
|
109
|
+
port: parsed.value.port
|
|
110
|
+
};
|
|
111
|
+
grants.push(addressGrant(parsed.value, options.resolver === void 0 ? "configured" : "named", "the DNS resolver"));
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
let gateway;
|
|
115
|
+
if (options.gateway !== void 0) {
|
|
116
|
+
const host = canonicalHost(options.gateway);
|
|
117
|
+
const kind = hostKind(host);
|
|
118
|
+
if (kind === "name") problems.push(`The gateway "${options.gateway}" is not an IP address.`);
|
|
119
|
+
else {
|
|
120
|
+
gateway = host;
|
|
121
|
+
grants.push(addressGrant({
|
|
122
|
+
host,
|
|
123
|
+
kind
|
|
124
|
+
}, "named", "the default gateway"));
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
for (const cidr of options.grant ?? []) grants.push({
|
|
128
|
+
kind: "range",
|
|
129
|
+
cidr: cidr.trim(),
|
|
130
|
+
basis: "owned",
|
|
131
|
+
note: "a range of --grant"
|
|
132
|
+
});
|
|
133
|
+
for (const grant of grants) for (const problem of grantProblems(grant)) problems.push(grant.basis === "configured" ? `${problem} Give a resolver with --resolver <address>.` : problem);
|
|
134
|
+
if (problems.length > 0) return err(problems);
|
|
135
|
+
const visit = {
|
|
136
|
+
target: visitHost(target),
|
|
137
|
+
references,
|
|
138
|
+
...gateway === void 0 ? {} : { gateway },
|
|
139
|
+
...resolver === void 0 ? {} : { resolver },
|
|
140
|
+
grants
|
|
141
|
+
};
|
|
142
|
+
return ok({
|
|
143
|
+
target,
|
|
144
|
+
scheme,
|
|
145
|
+
path,
|
|
146
|
+
pingCount,
|
|
147
|
+
visit
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
// src/next.ts
|
|
151
|
+
/** The number of the most probable causes that the report shows, and that the gain of a next step tells apart. */
|
|
152
|
+
const TOP_CAUSES = 3;
|
|
153
|
+
const PROBE_KINDS = {
|
|
154
|
+
dns: [DNS_ANSWER.kind],
|
|
155
|
+
ping: [ICMP_ECHO.kind],
|
|
156
|
+
tls: [TCP_CONNECT.kind, TLS_HANDSHAKE.kind],
|
|
157
|
+
http: [TCP_CONNECT.kind, HTTP_RESPONSE.kind]
|
|
158
|
+
};
|
|
159
|
+
const PROBE_COSTS = {
|
|
160
|
+
dns: 1,
|
|
161
|
+
tls: 2,
|
|
162
|
+
http: 3,
|
|
163
|
+
ping: 5
|
|
164
|
+
};
|
|
165
|
+
const PROBE_NAMES = {
|
|
166
|
+
dns: "DNS query",
|
|
167
|
+
ping: "ping",
|
|
168
|
+
tls: "TLS handshake",
|
|
169
|
+
http: "HTTP request"
|
|
170
|
+
};
|
|
171
|
+
function nextProbe(role, probe) {
|
|
172
|
+
return {
|
|
173
|
+
id: `${role}.${probe}`,
|
|
174
|
+
role,
|
|
175
|
+
probe,
|
|
176
|
+
kinds: PROBE_KINDS[probe],
|
|
177
|
+
cost: PROBE_COSTS[probe]
|
|
178
|
+
};
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* The candidates of the next step: each probe of the target and of the reference hosts, and the ping of the gateway.
|
|
182
|
+
* The TLS handshake and the HTTP request are two candidates, so that the joint values of each candidate stay below the
|
|
183
|
+
* limit `MAX_JOINT_VALUES` of `rankProbes`.
|
|
184
|
+
*/
|
|
185
|
+
const NEXT_PROBES = [...["target", "reference"].flatMap((role) => [
|
|
186
|
+
"dns",
|
|
187
|
+
"ping",
|
|
188
|
+
"tls",
|
|
189
|
+
"http"
|
|
190
|
+
].map((probe) => nextProbe(role, probe))), nextProbe("gateway", "ping")];
|
|
191
|
+
/** The instruction to add a reference host. */
|
|
192
|
+
const ADD_REFERENCE = "Add a host that works for you with --reference <host>, for example a large web site.";
|
|
193
|
+
/** The instruction to add the gateway. */
|
|
194
|
+
const ADD_GATEWAY = "Give the address of your router with --gateway <address>.";
|
|
195
|
+
const keyOf = (item) => `${item.feature}\u0000${item.primary ? 1 : 0}`;
|
|
196
|
+
/** This function tells if the evidence of a role has no value of a feature, or has the value `value`. */
|
|
197
|
+
function openOrIs(evidence, primary, feature, value) {
|
|
198
|
+
const values = evidence.filter((item) => item.feature === feature && item.primary === primary).map((item) => item.value);
|
|
199
|
+
return values.length === 0 || values.includes(value);
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* The features that a probe gives only after a stage with one value. For example, a DNS answer gives addresses only
|
|
203
|
+
* when its outcome is `ok`. A new check cannot give such a feature when the evidence has another value of the stage.
|
|
204
|
+
*/
|
|
205
|
+
const AFTER_STAGE = { "dns.address": ["dns.answer", "ok"] };
|
|
206
|
+
/** This function tells if a new check can give a feature, from the stage before the feature. */
|
|
207
|
+
function observable(item, evidence) {
|
|
208
|
+
const stage = AFTER_STAGE[item.feature];
|
|
209
|
+
return stage === void 0 || openOrIs(evidence, item.primary, stage[0], stage[1]);
|
|
210
|
+
}
|
|
211
|
+
/** This function tells if the user can add the host of a role with an option. The step of such a role tells how. */
|
|
212
|
+
function absent(role, plan) {
|
|
213
|
+
if (role === "reference") return (plan.visit.references ?? []).length === 0;
|
|
214
|
+
return role === "gateway" && plan.visit.gateway === void 0;
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* This function tells if a probe can give its facts in a new check. A probe after a stage that failed cannot: for
|
|
218
|
+
* example, no TLS handshake follows a TCP connect that the server refused.
|
|
219
|
+
*/
|
|
220
|
+
function ready(probe, plan, addressed, evidence) {
|
|
221
|
+
const primary = probe.role === "target";
|
|
222
|
+
if (absent(probe.role, plan)) return probe.probe !== "tls" || plan.scheme === "https";
|
|
223
|
+
switch (probe.probe) {
|
|
224
|
+
case "dns": return probe.role === "target" ? plan.target.kind === "name" : (plan.visit.references ?? []).some((host) => hostKind(host.host) === "name");
|
|
225
|
+
case "ping": return probe.role === "gateway" || addressed.has(probe.role);
|
|
226
|
+
case "tls": return addressed.has(probe.role) && openOrIs(evidence, primary, "tcp.connect", "connected");
|
|
227
|
+
case "http": return addressed.has(probe.role) && openOrIs(evidence, primary, "tcp.connect", "connected") && (plan.scheme === "http" || openOrIs(evidence, primary, "tls.handshake", "ok"));
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
/** This function gives the instruction of a next step in plain words. */
|
|
231
|
+
function stepText(probe, observes, plan) {
|
|
232
|
+
const morePings = `Run the check again with --ping-count ${LOSS_MIN_SENT}.`;
|
|
233
|
+
if (probe.role === "reference" && absent("reference", plan)) return ADD_REFERENCE;
|
|
234
|
+
if (probe.role === "gateway" && absent("gateway", plan)) return plan.pingCount === 0 ? `${ADD_GATEWAY} ${morePings}` : ADD_GATEWAY;
|
|
235
|
+
const who = probe.role === "target" ? formatTarget(plan.target) : probe.role === "gateway" ? `the gateway ${plan.visit.gateway ?? ""}` : "the reference hosts";
|
|
236
|
+
switch (probe.probe) {
|
|
237
|
+
case "dns":
|
|
238
|
+
if (plan.visit.resolver === void 0) return "Give the address of a DNS resolver with --resolver <address>.";
|
|
239
|
+
break;
|
|
240
|
+
case "ping":
|
|
241
|
+
if (plan.pingCount === 0 || plan.pingCount < LOSS_MIN_SENT && observes.every((item) => item.feature === "path.loss")) return morePings;
|
|
242
|
+
break;
|
|
243
|
+
case "tls": if (plan.scheme === "http") return "Run the check again with --scheme https.";
|
|
244
|
+
}
|
|
245
|
+
return `The check has no value of ${[...new Set(observes.map((item) => item.feature))].join(", ")} from the ${PROBE_NAMES[probe.probe]} of ${who}. Look at the problems of the visit, then run the check again.`;
|
|
246
|
+
}
|
|
247
|
+
/**
|
|
248
|
+
* This function gives the next steps of a check, from the largest information gain. The first step is the next step.
|
|
249
|
+
*
|
|
250
|
+
* - A candidate observes the features of its fact kinds that the evidence does not have, with the role of the probe.
|
|
251
|
+
* A feature after a stage that gave another value is not observable: no address follows an answer `nxdomain`.
|
|
252
|
+
* - A probe that cannot give its facts is not a candidate. `addressed` has the roles with an address to probe: an IP
|
|
253
|
+
* address, or an address of a DNS answer.
|
|
254
|
+
* - A step with a gain of `GAIN_RESOLUTION` or less tells nothing, so the list does not have it.
|
|
255
|
+
* - Two probes with the same instruction give one step, with the larger gain. For example, each probe of a reference
|
|
256
|
+
* host that the user did not give has the instruction `ADD_REFERENCE`.
|
|
257
|
+
*/
|
|
258
|
+
function nextSteps(diagnosis, plan, addressed) {
|
|
259
|
+
if (diagnosis.causes.length === 0) return [];
|
|
260
|
+
const seen = new Set(diagnosis.used.map(keyOf));
|
|
261
|
+
const probes = new Map(NEXT_PROBES.filter((probe) => ready(probe, plan, addressed, diagnosis.used)).map((probe) => [probe.id, probe]));
|
|
262
|
+
const candidates = [...probes.values()].map((probe) => ({
|
|
263
|
+
id: probe.id,
|
|
264
|
+
cost: probe.cost,
|
|
265
|
+
observes: featuresOf(probe.kinds, { gateway: probe.role === "gateway" }).map((feature) => ({
|
|
266
|
+
feature,
|
|
267
|
+
primary: probe.role === "target"
|
|
268
|
+
})).filter((item) => !seen.has(keyOf(item)) && observable(item, diagnosis.used))
|
|
269
|
+
})).filter((candidate) => candidate.observes.length > 0);
|
|
270
|
+
if (candidates.length === 0) return [];
|
|
271
|
+
const steps = [];
|
|
272
|
+
const said = /* @__PURE__ */ new Set();
|
|
273
|
+
for (const choice of rankProbes(STANDARD_CATALOG, diagnosis, candidates, { top: 3 })) {
|
|
274
|
+
const probe = probes.get(choice.candidate.id);
|
|
275
|
+
if (probe === void 0 || choice.gain <= GAIN_RESOLUTION) continue;
|
|
276
|
+
const step = stepText(probe, choice.counted, plan);
|
|
277
|
+
if (said.has(step)) continue;
|
|
278
|
+
said.add(step);
|
|
279
|
+
steps.push({
|
|
280
|
+
id: probe.id,
|
|
281
|
+
step,
|
|
282
|
+
gain: choice.gain,
|
|
283
|
+
observes: choice.counted
|
|
284
|
+
});
|
|
285
|
+
}
|
|
286
|
+
return steps;
|
|
287
|
+
}
|
|
288
|
+
// src/report.ts
|
|
289
|
+
/** The format of the JSON report of a check. A change to the shape of `CheckReport` changes the format. */
|
|
290
|
+
const CHECK_FORMAT = "netdiag-check/1";
|
|
291
|
+
/** This function gives the roles with an address to probe: an IP address of the plan, or an address of a DNS answer. */
|
|
292
|
+
function addressedRoles(plan, facts) {
|
|
293
|
+
const roles = /* @__PURE__ */ new Set();
|
|
294
|
+
if (plan.target.kind !== "name") roles.add("target");
|
|
295
|
+
if ((plan.visit.references ?? []).some((host) => hostKind(host.host) !== "name")) roles.add("reference");
|
|
296
|
+
if (plan.visit.gateway !== void 0) roles.add("gateway");
|
|
297
|
+
for (const { role, fact } of facts) if (isFactOf(DNS_ANSWER, fact) && fact.value.addresses.length > 0) roles.add(role);
|
|
298
|
+
return roles;
|
|
299
|
+
}
|
|
300
|
+
/**
|
|
301
|
+
* This function gives the report of the steps of a visit.
|
|
302
|
+
*
|
|
303
|
+
* - A fact of the role `target` gives primary evidence. A fact of each other role gives reference evidence.
|
|
304
|
+
* - The report finds the facts of the target by their role, not by their position. Thus a first step of the role
|
|
305
|
+
* `local` is not a problem.
|
|
306
|
+
* - The causes come from `diagnose` with `STANDARD_CATALOG`. The next steps come from `nextSteps`.
|
|
307
|
+
*/
|
|
308
|
+
function reportOf(plan, steps) {
|
|
309
|
+
const facts = steps.flatMap((step) => step.kind === "fact" ? [{
|
|
310
|
+
role: step.role,
|
|
311
|
+
host: step.host,
|
|
312
|
+
fact: step.fact
|
|
313
|
+
}] : []);
|
|
314
|
+
const problems = steps.flatMap((step) => step.kind === "problem" ? [{
|
|
315
|
+
role: step.role,
|
|
316
|
+
host: step.host,
|
|
317
|
+
problem: step.problem
|
|
318
|
+
}] : []);
|
|
319
|
+
const primary = new Set(facts.filter((item) => item.role === "target").map((item) => item.fact.id));
|
|
320
|
+
const reading = readEvidence(facts.map((item) => item.fact), {
|
|
321
|
+
primary: (fact) => primary.has(fact.id),
|
|
322
|
+
gateway: plan.visit.gateway
|
|
323
|
+
});
|
|
324
|
+
const diagnosis = diagnose(STANDARD_CATALOG, reading.evidence);
|
|
325
|
+
const choices = nextSteps(diagnosis, plan, addressedRoles(plan, facts));
|
|
326
|
+
return {
|
|
327
|
+
format: CHECK_FORMAT,
|
|
328
|
+
target: formatTarget(plan.target),
|
|
329
|
+
scheme: plan.scheme,
|
|
330
|
+
path: plan.path,
|
|
331
|
+
grants: plan.visit.grants,
|
|
332
|
+
causes: diagnosis.causes,
|
|
333
|
+
next: choices[0] ?? null,
|
|
334
|
+
choices,
|
|
335
|
+
problems,
|
|
336
|
+
evidence: diagnosis.used,
|
|
337
|
+
ignored: diagnosis.ignored,
|
|
338
|
+
skipped: reading.skipped,
|
|
339
|
+
facts
|
|
340
|
+
};
|
|
341
|
+
}
|
|
342
|
+
/** This function gives a probability as a percent for a person: `<1%` for a probability above 0 that rounds to 0. */
|
|
343
|
+
function percentOf(probability) {
|
|
344
|
+
const value = Math.round(probability * 100);
|
|
345
|
+
return value === 0 && probability > 0 ? "<1%" : `${value}%`;
|
|
346
|
+
}
|
|
347
|
+
/**
|
|
348
|
+
* This function gives the role and the host of a step for a person. A step of the role `local` is a passive read of
|
|
349
|
+
* this computer, so its text is `this computer`.
|
|
350
|
+
*/
|
|
351
|
+
function subjectText(role, host) {
|
|
352
|
+
return role === "local" ? "this computer" : `${role} ${host}`;
|
|
353
|
+
}
|
|
354
|
+
/** The indent of the lines under a cause. */
|
|
355
|
+
const UNDER = " ".repeat(8);
|
|
356
|
+
/**
|
|
357
|
+
* This function gives the lines of the text report of a check. The lines show the most probable causes with their
|
|
358
|
+
* probabilities and the next step with its gain. They also show the problems of the visit and the count of the evidence.
|
|
359
|
+
*/
|
|
360
|
+
function formatReport(report) {
|
|
361
|
+
const lines = [
|
|
362
|
+
`netdiag check ${report.target} (${report.scheme}, path ${report.path})`,
|
|
363
|
+
"",
|
|
364
|
+
"The probable causes"
|
|
365
|
+
];
|
|
366
|
+
for (const cause of report.causes.slice(0, 3)) lines.push(` ${pad(percentOf(cause.probability), 4, { side: "start" })} ${cause.summary}`, `${UNDER}To do: ${cause.step}`);
|
|
367
|
+
if (report.evidence.length === 0) lines.push(" The visit gave no evidence. These probabilities are the probabilities before a probe.");
|
|
368
|
+
lines.push("");
|
|
369
|
+
if (report.next === null) lines.push("The next step", " netdiag has no probe that can tell more about these causes.");
|
|
370
|
+
else lines.push(`The next step (it can give ${report.next.gain.toFixed(2)} bits of information about the causes)`, ` ${report.next.step}`);
|
|
371
|
+
if (report.problems.length > 0) {
|
|
372
|
+
lines.push("", `The problems of the visit (${report.problems.length})`);
|
|
373
|
+
for (const item of report.problems) lines.push(` ${subjectText(item.role, item.host)}: ${item.problem}`);
|
|
374
|
+
}
|
|
375
|
+
lines.push("", `${countOf(report.evidence.length, "observation")} from ${countOf(report.facts.length, "fact")}. The option --json gives each fact.`);
|
|
376
|
+
return lines;
|
|
377
|
+
}
|
|
378
|
+
// src/check.ts
|
|
379
|
+
/** This function gives the parts of this computer: the monotonic clock, `runCommand` of `@procedures/shell` and the DNS resolvers. */
|
|
380
|
+
function systemDeps() {
|
|
381
|
+
return {
|
|
382
|
+
clock: realClock,
|
|
383
|
+
tools: commandHost(runCommand, process.platform),
|
|
384
|
+
resolvers: getServers()
|
|
385
|
+
};
|
|
386
|
+
}
|
|
387
|
+
/**
|
|
388
|
+
* This function plans a check, starts its visit, and gives the report.
|
|
389
|
+
*
|
|
390
|
+
* It throws a `RangeError` with each problem of the options before the first probe.
|
|
391
|
+
*/
|
|
392
|
+
async function check(options, deps) {
|
|
393
|
+
const planned = planCheck(options, { resolvers: deps.resolvers });
|
|
394
|
+
if (planned.tag === "err") throw new RangeError(planned.error.join("\n"));
|
|
395
|
+
const plan = planned.value;
|
|
396
|
+
const steps = [];
|
|
397
|
+
const visit = visitTarget(plan.visit, {
|
|
398
|
+
clock: deps.clock,
|
|
399
|
+
tools: deps.tools,
|
|
400
|
+
pingCount: plan.pingCount,
|
|
401
|
+
scheme: plan.scheme,
|
|
402
|
+
path: plan.path,
|
|
403
|
+
tls: deps.tls,
|
|
404
|
+
signal: deps.signal
|
|
405
|
+
});
|
|
406
|
+
for await (const step of visit) steps.push(step);
|
|
407
|
+
return reportOf(plan, steps);
|
|
408
|
+
}
|
|
409
|
+
// src/cli.ts
|
|
410
|
+
/** The name of the program. */
|
|
411
|
+
const PROGRAM = "netdiag";
|
|
412
|
+
const CHECK_INPUT = z.object({
|
|
413
|
+
target: z.string().min(1).describe("The host to check: a DNS name, an IP address, host:port or a URL"),
|
|
414
|
+
port: z.number().int().min(1).max(65535).optional().describe("The port of the HTTP request. The default is the port of the scheme"),
|
|
415
|
+
scheme: z.enum(SCHEMES).optional().describe("The scheme of the HTTP request: http or https. The default is https"),
|
|
416
|
+
path: z.string().optional().describe("The path of the HTTP request. The default is /"),
|
|
417
|
+
reference: z.array(z.string()).optional().describe("A host that works, for a comparison. Give the flag again for more hosts"),
|
|
418
|
+
resolver: z.string().optional().describe("The address of the DNS resolver. The default is the first resolver of this computer"),
|
|
419
|
+
gateway: z.string().optional().describe("The IP address of the default gateway. The check pings it"),
|
|
420
|
+
grant: z.array(z.string()).optional().describe("A CIDR range that you own. The check can probe each address in it"),
|
|
421
|
+
pingCount: z.number().int().min(0).max(MAX_PING_COUNT).optional().describe(`The number of echo requests to each address. The default is ${DEFAULT_PING_COUNT}`)
|
|
422
|
+
});
|
|
423
|
+
/** This function makes the command line of netdiag with the command `check`. */
|
|
424
|
+
function createNetdiagCli(options) {
|
|
425
|
+
const procedure = defineProcedure({
|
|
426
|
+
path: ["check"],
|
|
427
|
+
input: CHECK_INPUT,
|
|
428
|
+
output: z.custom(),
|
|
429
|
+
metadata: {
|
|
430
|
+
description: "Check a target, and show the probable causes of a fault and the next step",
|
|
431
|
+
args: ["target"],
|
|
432
|
+
effects: {
|
|
433
|
+
reads: ["network"],
|
|
434
|
+
writes: ["process"],
|
|
435
|
+
destructive: false
|
|
436
|
+
}
|
|
437
|
+
},
|
|
438
|
+
handler: (input, context) => options.check(input, context.signal)
|
|
439
|
+
});
|
|
440
|
+
return createProcedureCli({
|
|
441
|
+
name: PROGRAM,
|
|
442
|
+
version: options.version,
|
|
443
|
+
description: "the probable causes of a network fault, and the next step",
|
|
444
|
+
procedures: [procedure],
|
|
445
|
+
format: { check: (result) => formatReport(result) },
|
|
446
|
+
print: options.print,
|
|
447
|
+
terminal: options.terminal
|
|
448
|
+
});
|
|
449
|
+
}
|
|
450
|
+
/** This function gives the version in `package.json` of this package. */
|
|
451
|
+
function packageVersion() {
|
|
452
|
+
const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
|
|
453
|
+
const version = typeof manifest === "object" && manifest !== null && "version" in manifest ? manifest.version : void 0;
|
|
454
|
+
return typeof version === "string" ? version : "0.0.0";
|
|
455
|
+
}
|
|
456
|
+
/** This function operates the command line on this computer, and gives the exit code. */
|
|
457
|
+
async function main(argv) {
|
|
458
|
+
return createNetdiagCli({
|
|
459
|
+
version: packageVersion(),
|
|
460
|
+
check: (options, signal) => check(options, {
|
|
461
|
+
...systemDeps(),
|
|
462
|
+
signal
|
|
463
|
+
})
|
|
464
|
+
}).run(argv);
|
|
465
|
+
}
|
|
466
|
+
export { stepText as _, check as a, formatReport as c, subjectText as d, ADD_GATEWAY as f, nextSteps as g, TOP_CAUSES as h, packageVersion as i, percentOf as l, NEXT_PROBES as m, createNetdiagCli as n, systemDeps as o, ADD_REFERENCE as p, main as r, CHECK_FORMAT as s, PROGRAM as t, reportOf as u, SCHEMES as v, planCheck as y };
|
|
467
|
+
|
|
468
|
+
//# sourceMappingURL=cli-CaUDBEoh.js.map
|