@mark1russell7/netdiag-cli 0.0.0-stage → 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 +115 -2
- 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 +74 -3
- 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/src/next.ts
ADDED
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
import {
|
|
2
|
+
DNS_ANSWER,
|
|
3
|
+
GAIN_RESOLUTION,
|
|
4
|
+
HTTP_RESPONSE,
|
|
5
|
+
ICMP_ECHO,
|
|
6
|
+
LOSS_MIN_SENT,
|
|
7
|
+
STANDARD_CATALOG,
|
|
8
|
+
TCP_CONNECT,
|
|
9
|
+
TLS_HANDSHAKE,
|
|
10
|
+
featuresOf,
|
|
11
|
+
formatTarget,
|
|
12
|
+
hostKind,
|
|
13
|
+
rankProbes,
|
|
14
|
+
type Candidate,
|
|
15
|
+
type Diagnosis,
|
|
16
|
+
type Evidence,
|
|
17
|
+
type Observable,
|
|
18
|
+
type VisitRole,
|
|
19
|
+
} from "@mark1russell7/netdiag";
|
|
20
|
+
import type { CheckPlan } from "./plan.ts";
|
|
21
|
+
|
|
22
|
+
// The choice of the next step. Each candidate is a probe of the visit for one role. Its features are the features that
|
|
23
|
+
// the facts of the probe give, and that the evidence does not have yet. `rankProbes` orders the candidates by the
|
|
24
|
+
// information that they can give about the most probable causes.
|
|
25
|
+
|
|
26
|
+
/** A probe of a visit: the DNS query, the ICMP echo requests, the TLS handshake, or the HTTP request. */
|
|
27
|
+
export type NextProbeKind = "dns" | "ping" | "tls" | "http";
|
|
28
|
+
|
|
29
|
+
/** A probe that the next step can start, for one role of the visit. */
|
|
30
|
+
export interface NextProbe {
|
|
31
|
+
/** The id of the candidate: the role and the probe, for example `gateway.ping`. */
|
|
32
|
+
readonly id: string;
|
|
33
|
+
readonly role: VisitRole;
|
|
34
|
+
readonly probe: NextProbeKind;
|
|
35
|
+
/** The fact kinds that the probe gives. A TLS handshake and an HTTP request also give the TCP connect before them. */
|
|
36
|
+
readonly kinds: readonly string[];
|
|
37
|
+
/** An approximate time of the probe, in seconds. When two gains are equal, the lower cost comes first. */
|
|
38
|
+
readonly cost: number;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** The next step of a check: the instruction in plain words, its information gain, and the features that it observes. */
|
|
42
|
+
export interface NextStep {
|
|
43
|
+
/** The id of the probe of the step, for example `gateway.ping`. */
|
|
44
|
+
readonly id: string;
|
|
45
|
+
/** The instruction to the user. */
|
|
46
|
+
readonly step: string;
|
|
47
|
+
/** The expected information gain over the most probable causes, in bits. */
|
|
48
|
+
readonly gain: number;
|
|
49
|
+
/** The features that the step observes and that the evidence does not have. */
|
|
50
|
+
readonly observes: readonly Observable[];
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** The number of the most probable causes that the report shows, and that the gain of a next step tells apart. */
|
|
54
|
+
export const TOP_CAUSES = 3;
|
|
55
|
+
|
|
56
|
+
const PROBE_KINDS: Readonly<Record<NextProbeKind, readonly string[]>> = {
|
|
57
|
+
dns: [DNS_ANSWER.kind],
|
|
58
|
+
ping: [ICMP_ECHO.kind],
|
|
59
|
+
tls: [TCP_CONNECT.kind, TLS_HANDSHAKE.kind],
|
|
60
|
+
http: [TCP_CONNECT.kind, HTTP_RESPONSE.kind],
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
const PROBE_COSTS: Readonly<Record<NextProbeKind, number>> = { dns: 1, tls: 2, http: 3, ping: 5 };
|
|
64
|
+
|
|
65
|
+
const PROBE_NAMES: Readonly<Record<NextProbeKind, string>> = { dns: "DNS query", ping: "ping", tls: "TLS handshake", http: "HTTP request" };
|
|
66
|
+
|
|
67
|
+
function nextProbe(role: VisitRole, probe: NextProbeKind): NextProbe {
|
|
68
|
+
return { id: `${role}.${probe}`, role, probe, kinds: PROBE_KINDS[probe], cost: PROBE_COSTS[probe] };
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* The candidates of the next step: each probe of the target and of the reference hosts, and the ping of the gateway.
|
|
73
|
+
* The TLS handshake and the HTTP request are two candidates, so that the joint values of each candidate stay below the
|
|
74
|
+
* limit `MAX_JOINT_VALUES` of `rankProbes`.
|
|
75
|
+
*/
|
|
76
|
+
export const NEXT_PROBES: readonly NextProbe[] = [
|
|
77
|
+
...(["target", "reference"] as const).flatMap((role) => (["dns", "ping", "tls", "http"] as const).map((probe) => nextProbe(role, probe))),
|
|
78
|
+
nextProbe("gateway", "ping"),
|
|
79
|
+
];
|
|
80
|
+
|
|
81
|
+
/** The instruction to add a reference host. */
|
|
82
|
+
export const ADD_REFERENCE = "Add a host that works for you with --reference <host>, for example a large web site.";
|
|
83
|
+
|
|
84
|
+
/** The instruction to add the gateway. */
|
|
85
|
+
export const ADD_GATEWAY = "Give the address of your router with --gateway <address>.";
|
|
86
|
+
|
|
87
|
+
const keyOf = (item: Observable): string => `${item.feature}\u0000${item.primary ? 1 : 0}`;
|
|
88
|
+
|
|
89
|
+
/** This function tells if the evidence of a role has no value of a feature, or has the value `value`. */
|
|
90
|
+
function openOrIs(evidence: readonly Evidence[], primary: boolean, feature: string, value: string): boolean {
|
|
91
|
+
const values = evidence.filter((item) => item.feature === feature && item.primary === primary).map((item) => item.value);
|
|
92
|
+
return values.length === 0 || values.includes(value);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* The features that a probe gives only after a stage with one value. For example, a DNS answer gives addresses only
|
|
97
|
+
* when its outcome is `ok`. A new check cannot give such a feature when the evidence has another value of the stage.
|
|
98
|
+
*/
|
|
99
|
+
const AFTER_STAGE: Readonly<Record<string, readonly [feature: string, value: string]>> = {
|
|
100
|
+
"dns.address": ["dns.answer", "ok"],
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
/** This function tells if a new check can give a feature, from the stage before the feature. */
|
|
104
|
+
function observable(item: Observable, evidence: readonly Evidence[]): boolean {
|
|
105
|
+
const stage = AFTER_STAGE[item.feature];
|
|
106
|
+
return stage === undefined || openOrIs(evidence, item.primary, stage[0], stage[1]);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** This function tells if the user can add the host of a role with an option. The step of such a role tells how. */
|
|
110
|
+
function absent(role: VisitRole, plan: CheckPlan): boolean {
|
|
111
|
+
if (role === "reference") return (plan.visit.references ?? []).length === 0;
|
|
112
|
+
return role === "gateway" && plan.visit.gateway === undefined;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* This function tells if a probe can give its facts in a new check. A probe after a stage that failed cannot: for
|
|
117
|
+
* example, no TLS handshake follows a TCP connect that the server refused.
|
|
118
|
+
*/
|
|
119
|
+
function ready(probe: NextProbe, plan: CheckPlan, addressed: ReadonlySet<VisitRole>, evidence: readonly Evidence[]): boolean {
|
|
120
|
+
const primary = probe.role === "target";
|
|
121
|
+
if (absent(probe.role, plan)) return probe.probe !== "tls" || plan.scheme === "https";
|
|
122
|
+
switch (probe.probe) {
|
|
123
|
+
case "dns":
|
|
124
|
+
return probe.role === "target" ? plan.target.kind === "name" : (plan.visit.references ?? []).some((host) => hostKind(host.host) === "name");
|
|
125
|
+
case "ping":
|
|
126
|
+
return probe.role === "gateway" || addressed.has(probe.role);
|
|
127
|
+
case "tls":
|
|
128
|
+
return addressed.has(probe.role) && openOrIs(evidence, primary, "tcp.connect", "connected");
|
|
129
|
+
case "http":
|
|
130
|
+
return (
|
|
131
|
+
addressed.has(probe.role) &&
|
|
132
|
+
openOrIs(evidence, primary, "tcp.connect", "connected") &&
|
|
133
|
+
(plan.scheme === "http" || openOrIs(evidence, primary, "tls.handshake", "ok"))
|
|
134
|
+
);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** This function gives the instruction of a next step in plain words. */
|
|
139
|
+
export function stepText(probe: NextProbe, observes: readonly Observable[], plan: CheckPlan): string {
|
|
140
|
+
const morePings = `Run the check again with --ping-count ${LOSS_MIN_SENT}.`;
|
|
141
|
+
if (probe.role === "reference" && absent("reference", plan)) return ADD_REFERENCE;
|
|
142
|
+
if (probe.role === "gateway" && absent("gateway", plan)) return plan.pingCount === 0 ? `${ADD_GATEWAY} ${morePings}` : ADD_GATEWAY;
|
|
143
|
+
const who = probe.role === "target" ? formatTarget(plan.target) : probe.role === "gateway" ? `the gateway ${plan.visit.gateway ?? ""}` : "the reference hosts";
|
|
144
|
+
switch (probe.probe) {
|
|
145
|
+
case "dns":
|
|
146
|
+
if (plan.visit.resolver === undefined) return "Give the address of a DNS resolver with --resolver <address>.";
|
|
147
|
+
break;
|
|
148
|
+
case "ping":
|
|
149
|
+
if (plan.pingCount === 0 || (plan.pingCount < LOSS_MIN_SENT && observes.every((item) => item.feature === "path.loss"))) return morePings;
|
|
150
|
+
break;
|
|
151
|
+
case "tls":
|
|
152
|
+
if (plan.scheme === "http") return "Run the check again with --scheme https.";
|
|
153
|
+
break;
|
|
154
|
+
case "http":
|
|
155
|
+
break;
|
|
156
|
+
}
|
|
157
|
+
const features = [...new Set(observes.map((item) => item.feature))].join(", ");
|
|
158
|
+
return `The check has no value of ${features} from the ${PROBE_NAMES[probe.probe]} of ${who}. Look at the problems of the visit, then run the check again.`;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* This function gives the next steps of a check, from the largest information gain. The first step is the next step.
|
|
163
|
+
*
|
|
164
|
+
* - A candidate observes the features of its fact kinds that the evidence does not have, with the role of the probe.
|
|
165
|
+
* A feature after a stage that gave another value is not observable: no address follows an answer `nxdomain`.
|
|
166
|
+
* - A probe that cannot give its facts is not a candidate. `addressed` has the roles with an address to probe: an IP
|
|
167
|
+
* address, or an address of a DNS answer.
|
|
168
|
+
* - A step with a gain of `GAIN_RESOLUTION` or less tells nothing, so the list does not have it.
|
|
169
|
+
* - Two probes with the same instruction give one step, with the larger gain. For example, each probe of a reference
|
|
170
|
+
* host that the user did not give has the instruction `ADD_REFERENCE`.
|
|
171
|
+
*/
|
|
172
|
+
export function nextSteps(diagnosis: Diagnosis, plan: CheckPlan, addressed: ReadonlySet<VisitRole>): NextStep[] {
|
|
173
|
+
if (diagnosis.causes.length === 0) return [];
|
|
174
|
+
const seen = new Set(diagnosis.used.map(keyOf));
|
|
175
|
+
const probes = new Map(NEXT_PROBES.filter((probe) => ready(probe, plan, addressed, diagnosis.used)).map((probe) => [probe.id, probe]));
|
|
176
|
+
const candidates: Candidate[] = [...probes.values()]
|
|
177
|
+
.map((probe) => ({
|
|
178
|
+
id: probe.id,
|
|
179
|
+
cost: probe.cost,
|
|
180
|
+
observes: featuresOf(probe.kinds, { gateway: probe.role === "gateway" })
|
|
181
|
+
.map((feature) => ({ feature, primary: probe.role === "target" }))
|
|
182
|
+
.filter((item) => !seen.has(keyOf(item)) && observable(item, diagnosis.used)),
|
|
183
|
+
}))
|
|
184
|
+
.filter((candidate) => candidate.observes.length > 0);
|
|
185
|
+
if (candidates.length === 0) return [];
|
|
186
|
+
const steps: NextStep[] = [];
|
|
187
|
+
const said = new Set<string>();
|
|
188
|
+
for (const choice of rankProbes(STANDARD_CATALOG, diagnosis, candidates, { top: TOP_CAUSES })) {
|
|
189
|
+
const probe = probes.get(choice.candidate.id);
|
|
190
|
+
if (probe === undefined || choice.gain <= GAIN_RESOLUTION) continue;
|
|
191
|
+
const step = stepText(probe, choice.counted, plan);
|
|
192
|
+
if (said.has(step)) continue;
|
|
193
|
+
said.add(step);
|
|
194
|
+
steps.push({ id: probe.id, step, gain: choice.gain, observes: choice.counted });
|
|
195
|
+
}
|
|
196
|
+
return steps;
|
|
197
|
+
}
|
package/src/plan.ts
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
import {
|
|
2
|
+
canonicalHost,
|
|
3
|
+
grantProblems,
|
|
4
|
+
hostKind,
|
|
5
|
+
namedGrant,
|
|
6
|
+
parseTarget,
|
|
7
|
+
type Grant,
|
|
8
|
+
type Target,
|
|
9
|
+
type VisitHost,
|
|
10
|
+
type VisitInput,
|
|
11
|
+
type VisitResolver,
|
|
12
|
+
} from "@mark1russell7/netdiag";
|
|
13
|
+
import { DEFAULT_PING_COUNT, MAX_PING_COUNT } from "@mark1russell7/netdiag/tools";
|
|
14
|
+
import { err, ok, type Result } from "@mark1russell7/optional";
|
|
15
|
+
|
|
16
|
+
// The plan of a check: the options of the command line, changed into the input of a visit. The plan is the scope rule
|
|
17
|
+
// of the command: it grants only the hosts that the user names, the DNS resolver and the ranges of `--grant`.
|
|
18
|
+
|
|
19
|
+
/** The schemes of the HTTP request of a check. */
|
|
20
|
+
export const SCHEMES: readonly ["http", "https"] = ["http", "https"];
|
|
21
|
+
|
|
22
|
+
/** A scheme of the HTTP request of a check. */
|
|
23
|
+
export type Scheme = (typeof SCHEMES)[number];
|
|
24
|
+
|
|
25
|
+
/** The options of the command `check`. Each field is a flag of the command line. */
|
|
26
|
+
export interface CheckOptions {
|
|
27
|
+
/** The host to check: a DNS name, an IP address, `host:port` or a URL. */
|
|
28
|
+
readonly target: string;
|
|
29
|
+
/** The port of the HTTP request. The default is the port in the target, then the port of the scheme. */
|
|
30
|
+
readonly port?: number | undefined;
|
|
31
|
+
/** The scheme of the HTTP request. The default is the scheme of a URL target, then `https`. */
|
|
32
|
+
readonly scheme?: Scheme | undefined;
|
|
33
|
+
/** The path of the HTTP request. The default is the path of a URL target, then `/`. */
|
|
34
|
+
readonly path?: string | undefined;
|
|
35
|
+
/** The hosts that work, for a comparison with the target. */
|
|
36
|
+
readonly reference?: readonly string[] | undefined;
|
|
37
|
+
/** The address of the DNS resolver, with an optional port. The default is the first resolver of the computer. */
|
|
38
|
+
readonly resolver?: string | undefined;
|
|
39
|
+
/** The IP address of the default gateway. Without it, the check does not ping a gateway. */
|
|
40
|
+
readonly gateway?: string | undefined;
|
|
41
|
+
/** The CIDR ranges that the user owns. The check can probe each address in them. */
|
|
42
|
+
readonly grant?: readonly string[] | undefined;
|
|
43
|
+
/** The number of echo requests to each address. The default is `DEFAULT_PING_COUNT`. */
|
|
44
|
+
readonly pingCount?: number | undefined;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The parts of the computer that a plan reads. */
|
|
48
|
+
export interface PlanSystem {
|
|
49
|
+
/** The DNS resolvers of the computer, in the form of `getServers()` of `node:dns`. */
|
|
50
|
+
readonly resolvers: readonly string[];
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** The plan of a check: the target, the HTTP request, the number of echo requests, and the input of the visit. */
|
|
54
|
+
export interface CheckPlan {
|
|
55
|
+
/** The target, with the port of the HTTP request when the user gives one. */
|
|
56
|
+
readonly target: Target;
|
|
57
|
+
readonly scheme: Scheme;
|
|
58
|
+
readonly path: string;
|
|
59
|
+
readonly pingCount: number;
|
|
60
|
+
/** The input of `visitTarget`, with the grants of the scope. */
|
|
61
|
+
readonly visit: VisitInput;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
interface Located {
|
|
65
|
+
readonly target: Target;
|
|
66
|
+
readonly scheme?: Scheme | undefined;
|
|
67
|
+
readonly path?: string | undefined;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function isScheme(text: string): text is Scheme {
|
|
71
|
+
return (SCHEMES as readonly string[]).includes(text);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** 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. */
|
|
75
|
+
function locate(text: string, what: string): Result<Located, string> {
|
|
76
|
+
const parsed = parseTarget(text);
|
|
77
|
+
if (parsed.tag === "err") return err(`The ${what} is not valid. ${parsed.error}`);
|
|
78
|
+
if (!text.includes("://")) return ok({ target: parsed.value });
|
|
79
|
+
const url = new URL(text.trim());
|
|
80
|
+
const scheme = url.protocol.slice(0, -1);
|
|
81
|
+
if (!isScheme(scheme)) return err(`The ${what} "${text}" has the scheme ${scheme}. A check sends HTTP and HTTPS requests only.`);
|
|
82
|
+
// `parseTarget` gives the port of the scheme to a URL with no port. The check keeps only a port that the URL names.
|
|
83
|
+
const host = { host: parsed.value.host, kind: parsed.value.kind };
|
|
84
|
+
const target = url.port === "" ? host : { ...host, port: Number(url.port) };
|
|
85
|
+
return ok({ target, scheme, path: `${url.pathname}${url.search}` });
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** This function gives a grant of one IP address. */
|
|
89
|
+
function addressGrant(address: Target, basis: Grant["basis"], note: string): Grant {
|
|
90
|
+
return { ...namedGrant(address, note), basis };
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function visitHost(target: Target): VisitHost {
|
|
94
|
+
return target.port === undefined ? { host: target.host } : { host: target.host, port: target.port };
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
function whole(value: number, low: number, high: number): boolean {
|
|
98
|
+
return Number.isInteger(value) && value >= low && value <= high;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* This function gives the plan of a check from the options of the command line, or each problem of the options.
|
|
103
|
+
*
|
|
104
|
+
* The grants of the plan are the scope rule of the command. The plan grants only these hosts:
|
|
105
|
+
*
|
|
106
|
+
* - the target, and each reference host, with the basis `named`
|
|
107
|
+
* - the DNS resolver, with the basis `named` from `--resolver`, or `configured` from the computer
|
|
108
|
+
* - the gateway, when the user gives it, with the basis `named`
|
|
109
|
+
* - each range of `--grant`, with the basis `owned`
|
|
110
|
+
*
|
|
111
|
+
* The visit also puts in the scope the addresses that the resolver gives for a named host.
|
|
112
|
+
*/
|
|
113
|
+
export function planCheck(options: CheckOptions, system: PlanSystem): Result<CheckPlan, readonly string[]> {
|
|
114
|
+
const problems: string[] = [];
|
|
115
|
+
const grants: Grant[] = [];
|
|
116
|
+
|
|
117
|
+
const located = locate(options.target, "target");
|
|
118
|
+
if (located.tag === "err") return err([located.error]);
|
|
119
|
+
const scheme = options.scheme ?? located.value.scheme ?? "https";
|
|
120
|
+
const path = options.path ?? located.value.path ?? "/";
|
|
121
|
+
if (!isScheme(scheme)) problems.push(`The scheme ${String(scheme)} is not http or https.`);
|
|
122
|
+
if (!path.startsWith("/")) problems.push(`The path "${path}" does not start with "/".`);
|
|
123
|
+
const port = options.port ?? located.value.target.port;
|
|
124
|
+
if (port !== undefined && !whole(port, 1, 65535)) problems.push(`The port ${port} is not an integer from 1 to 65535.`);
|
|
125
|
+
const pingCount = options.pingCount ?? DEFAULT_PING_COUNT;
|
|
126
|
+
if (!whole(pingCount, 0, MAX_PING_COUNT)) problems.push(`The ping count ${pingCount} is not an integer from 0 to ${MAX_PING_COUNT}.`);
|
|
127
|
+
const target: Target = port === undefined ? { host: located.value.target.host, kind: located.value.target.kind } : { ...located.value.target, port };
|
|
128
|
+
grants.push(namedGrant(target, "the target"));
|
|
129
|
+
|
|
130
|
+
const references: VisitHost[] = [];
|
|
131
|
+
for (const text of options.reference ?? []) {
|
|
132
|
+
const reference = locate(text, "reference");
|
|
133
|
+
if (reference.tag === "err") problems.push(reference.error);
|
|
134
|
+
else {
|
|
135
|
+
references.push(visitHost(reference.value.target));
|
|
136
|
+
grants.push(namedGrant(reference.value.target, "a reference host"));
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
let resolver: VisitResolver | undefined;
|
|
141
|
+
const resolverText = options.resolver ?? system.resolvers[0];
|
|
142
|
+
if (resolverText !== undefined) {
|
|
143
|
+
const from = options.resolver === undefined ? "The DNS resolver of the computer" : "The DNS resolver";
|
|
144
|
+
const parsed = parseTarget(resolverText);
|
|
145
|
+
if (parsed.tag === "err") problems.push(`${from} is not valid. ${parsed.error}`);
|
|
146
|
+
else if (parsed.value.kind === "name") problems.push(`${from} "${resolverText}" is not an IP address.`);
|
|
147
|
+
else {
|
|
148
|
+
resolver = parsed.value.port === undefined ? { address: parsed.value.host } : { address: parsed.value.host, port: parsed.value.port };
|
|
149
|
+
grants.push(addressGrant(parsed.value, options.resolver === undefined ? "configured" : "named", "the DNS resolver"));
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
let gateway: string | undefined;
|
|
154
|
+
if (options.gateway !== undefined) {
|
|
155
|
+
const host = canonicalHost(options.gateway);
|
|
156
|
+
const kind = hostKind(host);
|
|
157
|
+
if (kind === "name") problems.push(`The gateway "${options.gateway}" is not an IP address.`);
|
|
158
|
+
else {
|
|
159
|
+
gateway = host;
|
|
160
|
+
grants.push(addressGrant({ host, kind }, "named", "the default gateway"));
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
for (const cidr of options.grant ?? []) grants.push({ kind: "range", cidr: cidr.trim(), basis: "owned", note: "a range of --grant" });
|
|
165
|
+
|
|
166
|
+
// A grant with a problem stops the plan, so a typing error cannot widen the scope.
|
|
167
|
+
for (const grant of grants) {
|
|
168
|
+
for (const problem of grantProblems(grant)) problems.push(grant.basis === "configured" ? `${problem} Give a resolver with --resolver <address>.` : problem);
|
|
169
|
+
}
|
|
170
|
+
if (problems.length > 0) return err(problems);
|
|
171
|
+
|
|
172
|
+
const visit: VisitInput = {
|
|
173
|
+
target: visitHost(target),
|
|
174
|
+
references,
|
|
175
|
+
...(gateway === undefined ? {} : { gateway }),
|
|
176
|
+
...(resolver === undefined ? {} : { resolver }),
|
|
177
|
+
grants,
|
|
178
|
+
};
|
|
179
|
+
return ok({ target, scheme, path, pingCount, visit });
|
|
180
|
+
}
|
package/src/report.ts
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
import {
|
|
2
|
+
DNS_ANSWER,
|
|
3
|
+
STANDARD_CATALOG,
|
|
4
|
+
diagnose,
|
|
5
|
+
formatTarget,
|
|
6
|
+
hostKind,
|
|
7
|
+
isFactOf,
|
|
8
|
+
readEvidence,
|
|
9
|
+
type Cause,
|
|
10
|
+
type Diagnosis,
|
|
11
|
+
type Evidence,
|
|
12
|
+
type Fact,
|
|
13
|
+
type Grant,
|
|
14
|
+
type Skipped,
|
|
15
|
+
type VisitRole,
|
|
16
|
+
type VisitStep,
|
|
17
|
+
} from "@mark1russell7/netdiag";
|
|
18
|
+
import { countOf } from "@mark1russell7/text";
|
|
19
|
+
import { pad } from "@mark1russell7/text/length";
|
|
20
|
+
import { TOP_CAUSES, nextSteps, type NextStep } from "./next.ts";
|
|
21
|
+
import type { CheckPlan, Scheme } from "./plan.ts";
|
|
22
|
+
|
|
23
|
+
// The report of a check: the steps of the visit, changed into evidence, the causes and the next step. Each function of
|
|
24
|
+
// this module is pure: the same plan and the same steps give the same report.
|
|
25
|
+
|
|
26
|
+
/** The format of the JSON report of a check. A change to the shape of `CheckReport` changes the format. */
|
|
27
|
+
export const CHECK_FORMAT = "netdiag-check/1";
|
|
28
|
+
|
|
29
|
+
/** A fact of a visit, with the role and the host of the step that gave it. */
|
|
30
|
+
export interface CheckFact {
|
|
31
|
+
readonly role: VisitRole;
|
|
32
|
+
readonly host: string;
|
|
33
|
+
readonly fact: Fact;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** A problem of a visit: a probe that did not end, with the role and the host of the step. */
|
|
37
|
+
export interface CheckProblem {
|
|
38
|
+
readonly role: VisitRole;
|
|
39
|
+
readonly host: string;
|
|
40
|
+
readonly problem: string;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** The report of a check. `--json` writes this object. */
|
|
44
|
+
export interface CheckReport {
|
|
45
|
+
readonly format: typeof CHECK_FORMAT;
|
|
46
|
+
/** The target, as `host` or `host:port`. */
|
|
47
|
+
readonly target: string;
|
|
48
|
+
readonly scheme: Scheme;
|
|
49
|
+
readonly path: string;
|
|
50
|
+
/** The grants of the scope of the check. */
|
|
51
|
+
readonly grants: readonly Grant[];
|
|
52
|
+
/** Each cause, from the most probable. */
|
|
53
|
+
readonly causes: readonly Cause[];
|
|
54
|
+
/** The next step, or `null` when no probe can tell more about the most probable causes. */
|
|
55
|
+
readonly next: NextStep | null;
|
|
56
|
+
/** Each next step with a gain, from the largest gain. The first one is `next`. */
|
|
57
|
+
readonly choices: readonly NextStep[];
|
|
58
|
+
readonly problems: readonly CheckProblem[];
|
|
59
|
+
/** The evidence that the diagnosis used. A fact of the role `target` gives primary evidence. */
|
|
60
|
+
readonly evidence: readonly Evidence[];
|
|
61
|
+
/** The evidence that the diagnosis did not use, with the reason. */
|
|
62
|
+
readonly ignored: Diagnosis["ignored"];
|
|
63
|
+
/** The facts that gave no evidence, with the reason. */
|
|
64
|
+
readonly skipped: readonly Skipped[];
|
|
65
|
+
readonly facts: readonly CheckFact[];
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** This function gives the roles with an address to probe: an IP address of the plan, or an address of a DNS answer. */
|
|
69
|
+
function addressedRoles(plan: CheckPlan, facts: readonly CheckFact[]): Set<VisitRole> {
|
|
70
|
+
const roles = new Set<VisitRole>();
|
|
71
|
+
if (plan.target.kind !== "name") roles.add("target");
|
|
72
|
+
if ((plan.visit.references ?? []).some((host) => hostKind(host.host) !== "name")) roles.add("reference");
|
|
73
|
+
if (plan.visit.gateway !== undefined) roles.add("gateway");
|
|
74
|
+
for (const { role, fact } of facts) if (isFactOf(DNS_ANSWER, fact) && fact.value.addresses.length > 0) roles.add(role);
|
|
75
|
+
return roles;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* This function gives the report of the steps of a visit.
|
|
80
|
+
*
|
|
81
|
+
* - A fact of the role `target` gives primary evidence. A fact of each other role gives reference evidence.
|
|
82
|
+
* - The report finds the facts of the target by their role, not by their position. Thus a first step of the role
|
|
83
|
+
* `local` is not a problem.
|
|
84
|
+
* - The causes come from `diagnose` with `STANDARD_CATALOG`. The next steps come from `nextSteps`.
|
|
85
|
+
*/
|
|
86
|
+
export function reportOf(plan: CheckPlan, steps: readonly VisitStep[]): CheckReport {
|
|
87
|
+
const facts: CheckFact[] = steps.flatMap((step) => (step.kind === "fact" ? [{ role: step.role, host: step.host, fact: step.fact }] : []));
|
|
88
|
+
const problems: CheckProblem[] = steps.flatMap((step) => (step.kind === "problem" ? [{ role: step.role, host: step.host, problem: step.problem }] : []));
|
|
89
|
+
const primary = new Set(facts.filter((item) => item.role === "target").map((item) => item.fact.id));
|
|
90
|
+
const reading = readEvidence(
|
|
91
|
+
facts.map((item) => item.fact),
|
|
92
|
+
{ primary: (fact) => primary.has(fact.id), gateway: plan.visit.gateway },
|
|
93
|
+
);
|
|
94
|
+
const diagnosis = diagnose(STANDARD_CATALOG, reading.evidence);
|
|
95
|
+
const choices = nextSteps(diagnosis, plan, addressedRoles(plan, facts));
|
|
96
|
+
return {
|
|
97
|
+
format: CHECK_FORMAT,
|
|
98
|
+
target: formatTarget(plan.target),
|
|
99
|
+
scheme: plan.scheme,
|
|
100
|
+
path: plan.path,
|
|
101
|
+
grants: plan.visit.grants,
|
|
102
|
+
causes: diagnosis.causes,
|
|
103
|
+
next: choices[0] ?? null,
|
|
104
|
+
choices,
|
|
105
|
+
problems,
|
|
106
|
+
evidence: diagnosis.used,
|
|
107
|
+
ignored: diagnosis.ignored,
|
|
108
|
+
skipped: reading.skipped,
|
|
109
|
+
facts,
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** This function gives a probability as a percent for a person: `<1%` for a probability above 0 that rounds to 0. */
|
|
114
|
+
export function percentOf(probability: number): string {
|
|
115
|
+
const value = Math.round(probability * 100);
|
|
116
|
+
return value === 0 && probability > 0 ? "<1%" : `${value}%`;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* 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
|
|
121
|
+
* this computer, so its text is `this computer`.
|
|
122
|
+
*/
|
|
123
|
+
export function subjectText(role: string, host: string): string {
|
|
124
|
+
return role === "local" ? "this computer" : `${role} ${host}`;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** The indent of the lines under a cause. */
|
|
128
|
+
const UNDER = " ".repeat(8);
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* This function gives the lines of the text report of a check. The lines show the most probable causes with their
|
|
132
|
+
* probabilities and the next step with its gain. They also show the problems of the visit and the count of the evidence.
|
|
133
|
+
*/
|
|
134
|
+
export function formatReport(report: CheckReport): string[] {
|
|
135
|
+
const lines = [`netdiag check ${report.target} (${report.scheme}, path ${report.path})`, "", "The probable causes"];
|
|
136
|
+
for (const cause of report.causes.slice(0, TOP_CAUSES)) {
|
|
137
|
+
lines.push(` ${pad(percentOf(cause.probability), 4, { side: "start" })} ${cause.summary}`, `${UNDER}To do: ${cause.step}`);
|
|
138
|
+
}
|
|
139
|
+
if (report.evidence.length === 0) lines.push(" The visit gave no evidence. These probabilities are the probabilities before a probe.");
|
|
140
|
+
lines.push("");
|
|
141
|
+
if (report.next === null) lines.push("The next step", " netdiag has no probe that can tell more about these causes.");
|
|
142
|
+
else lines.push(`The next step (it can give ${report.next.gain.toFixed(2)} bits of information about the causes)`, ` ${report.next.step}`);
|
|
143
|
+
if (report.problems.length > 0) {
|
|
144
|
+
lines.push("", `The problems of the visit (${report.problems.length})`);
|
|
145
|
+
for (const item of report.problems) lines.push(` ${subjectText(item.role, item.host)}: ${item.problem}`);
|
|
146
|
+
}
|
|
147
|
+
lines.push("", `${countOf(report.evidence.length, "observation")} from ${countOf(report.facts.length, "fact")}. The option --json gives each fact.`);
|
|
148
|
+
return lines;
|
|
149
|
+
}
|