IF Commons GitHub

logical/remote

Written to: 5 requirements: 5 proved, 0 partly, 0 failing, 0 with no test recorded. 0005-reach-and-targets FR-009, 0005-reach-and-targets FR-005, 0005-reach-and-targets FR-006, 0005-reach-and-targets FR-007, 0005-reach-and-targets FR-008

An action run on a target (commons headless 0005-reach-and-targets): the target (its id, class, address, port, jump chain, the reference of its host key and of its credential, never a value), the invocation that runs <program> run --json <verb> ... there, and what comes back as the typed outcome and the one JSON envelope of a local run. A host that cannot be reached, a host key that does not match and a time out are the environment's (status 3); a forced command that refuses is a usage problem (status 2); a partial failure over many targets is status 1 with a table for each host.

import { target, remoteArgv } from "./remote.ts";
const t = target({ id: "alpha", class: "server", address: "10.0.0.5" });
remoteArgv({ program: "ops", verb: ["boot", "doctor"], args: ["--quiet"] }); // ["ops", "run", "--json", "boot", "doctor", "--quiet"]

Source: commons/headless/src/logical/remote.ts

10 of 34 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

logical.CredentialReftypeno test imports it
type CredentialRef = { readonly kind: "ref"; readonly name: string };

A credential, by reference: the name a program resolves to a key file or an agent at the moment it is needed. It is never the credential.

logical.Targettypeno test imports it
type Target = { readonly id: string; readonly class: TargetClass; /** A host name or an address; never one that be… (555 characters)
type Target = {
  readonly id: string;
  readonly class: TargetClass;
  /** A host name or an address; never one that begins with a dash. */
  readonly address: string;
  readonly user: string | undefined;
  readonly port: number | undefined;
  /** The ids of the targets this one is reached through, in order. */
  readonly jump: readonly string[];
  /** The reference of the host's key (a fingerprint's name in the repository's known hosts), not the key. */
  readonly hostKeyRef: string | undefined;
  readonly credential: CredentialRef | undefined;
};

A machine a command can run on.

logical.TargetDefinitiontypeno test imports it
type TargetDefinition = {
  readonly id: string;
  readonly class: TargetClass;
  readonly address: string;
  readonly user?: string;
  readonly port?: number;
  readonly jump?: readonly string[];
  readonly hostKeyRef?: string;
  readonly credential?: string;
};

What target takes.

logical.targetfunctionno test imports it
function target(d: TargetDefinition): Result<Target, string>

A target, or why it is not one: an id of lower-case words, a class there is, an address that cannot be taken for an option, a port in range, a user and jump ids that are names.

logical.selectTargetsfunctionno test imports it
function selectTargets(all: readonly Target[], selector: string): Result<readonly Target[], string>

The targets a selector names: all, class:<class>, or ids joined by commas; an id or class that is not known is an error naming it.

logical.RemoteInvocationtypeno test imports it
type RemoteInvocation = { readonly program: string; readonly verb: readonly string[]; readonly args: readonly string[] };

What is run on a target: the program, the verb's words and the arguments.

logical.remoteArgvfunctionno test imports it
function remoteArgv(i: RemoteInvocation): readonly string[]

The argument vector that runs the invocation: <program> run --json <verb> ..., the one way a command is dispatched to a target.

logical.RemoteKindtypeno test imports it
type RemoteKind = "ran" | "unreachable" | "hostkey" | "timeout" | "refused" | "missing" | "malformed";

What came of a run on a target.

logical.RemoteOutcometypeno test imports it
type RemoteOutcome = {
  readonly target: string;
  readonly kind: RemoteKind;
  /** The status this target's run counts as: its own where it ran, 3 where it could not be reached, 2 where it refused. */
  readonly code: number;
  readonly outcome: Outcome;
};

A run on one target, as a report: how it went, its status, and what it found as the typed outcome.

logical.REMOTE_CATALOGUEconstno test imports it
const REMOTE_CATALOGUE: Readonly<Record<string, Explanation>>

The codes that remote failures carry, with their explanations, for a program to merge into its catalogue.

logical.decodeEnvelopefunctionno test imports it
function decodeEnvelope(text: string): Result<{ readonly code: number; readonly outcome: Outcome; }, string>

The outcome and the status of the one JSON envelope a remote run wrote, or why it is not one.

logical.outcomeOfRemotefunctionno test imports it
function outcomeOfRemote(targetId: string, out: Output | undefined, timedOut: boolean): RemoteOutcome

What a run on a target came to, from how its program ended: a time out and an exit of 255 (ssh's own failure) are the environment's, status 3, the host key apart from the rest; a 127 or 126 is that the program is not there, status 3; a refusal of the forced command (status 2 with no report) is status 2; a report that is not the one JSON document is malformed; otherwise the remote report, with its own status.

logical.remoteOfFannedfunctionno test imports it
function remoteOfFanned(row: Fanned<RemoteOutcome>): RemoteOutcome

The outcome a fan-out row comes to.

logical.exitOfRemotefunctionno test imports it
function exitOfRemote(rows: readonly RemoteOutcome[]): number

The status of a run over many targets: 0 where every target's run ended with 0; 3 where every one failed for the environment; 2 where every one refused; else 1, a partial failure, with the table of each host to say which.

logical.statusWordfunctionno test imports it
function statusWord(r: RemoteOutcome): string

The status word of a row for the table.

logical.hostTablefunctionno test imports it
function hostTable(rows: readonly RemoteOutcome[]): string

A table of one line for each host: its id, how it went, its status and the first thing it said.

logical.reportOfRemotefunctionno test imports it
function reportOfRemote(rows: readonly RemoteOutcome[]): Outcome

One report of a run over targets (the nested hand-off for many hosts): the table as its text, the data of each host under its id, and every problem of every host once, each marked with the target it is of; a failure of the run as a whole where some host failed.

CredentialReftypeno test imports it
type CredentialRef = { readonly kind: "ref"; readonly name: string };

A credential, by reference: the name a program resolves to a key file or an agent at the moment it is needed. It is never the credential.

Targettype
type Target = { readonly id: string; readonly class: TargetClass; /** A host name or an address; never one that be… (555 characters)
type Target = {
  readonly id: string;
  readonly class: TargetClass;
  /** A host name or an address; never one that begins with a dash. */
  readonly address: string;
  readonly user: string | undefined;
  readonly port: number | undefined;
  /** The ids of the targets this one is reached through, in order. */
  readonly jump: readonly string[];
  /** The reference of the host's key (a fingerprint's name in the repository's known hosts), not the key. */
  readonly hostKeyRef: string | undefined;
  readonly credential: CredentialRef | undefined;
};

A machine a command can run on.

Imported by 32 tests of the run (32 passed, 0 failed): the library's results

TargetDefinitiontypeno test imports it
type TargetDefinition = {
  readonly id: string;
  readonly class: TargetClass;
  readonly address: string;
  readonly user?: string;
  readonly port?: number;
  readonly jump?: readonly string[];
  readonly hostKeyRef?: string;
  readonly credential?: string;
};

What target takes.

targetfunction
function target(d: TargetDefinition): Result<Target, string>

A target, or why it is not one: an id of lower-case words, a class there is, an address that cannot be taken for an option, a port in range, a user and jump ids that are names.

Imported by 32 tests of the run (32 passed, 0 failed): the library's results

selectTargetsfunction
function selectTargets(all: readonly Target[], selector: string): Result<readonly Target[], string>

The targets a selector names: all, class:<class>, or ids joined by commas; an id or class that is not known is an error naming it.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

RemoteInvocationtypeno test imports it
type RemoteInvocation = { readonly program: string; readonly verb: readonly string[]; readonly args: readonly string[] };

What is run on a target: the program, the verb's words and the arguments.

remoteArgvfunctionno test imports it
function remoteArgv(i: RemoteInvocation): readonly string[]

The argument vector that runs the invocation: <program> run --json <verb> ..., the one way a command is dispatched to a target.

RemoteKindtypeno test imports it
type RemoteKind = "ran" | "unreachable" | "hostkey" | "timeout" | "refused" | "missing" | "malformed";

What came of a run on a target.

RemoteOutcometype
type RemoteOutcome = {
  readonly target: string;
  readonly kind: RemoteKind;
  /** The status this target's run counts as: its own where it ran, 3 where it could not be reached, 2 where it refused. */
  readonly code: number;
  readonly outcome: Outcome;
};

A run on one target, as a report: how it went, its status, and what it found as the typed outcome.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

REMOTE_CATALOGUEconst
const REMOTE_CATALOGUE: Readonly<Record<string, Explanation>>

The codes that remote failures carry, with their explanations, for a program to merge into its catalogue.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

decodeEnvelopefunction
function decodeEnvelope(text: string): Result<{ readonly code: number; readonly outcome: Outcome; }, string>

The outcome and the status of the one JSON envelope a remote run wrote, or why it is not one.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

outcomeOfRemotefunction
function outcomeOfRemote(targetId: string, out: Output | undefined, timedOut: boolean): RemoteOutcome

What a run on a target came to, from how its program ended: a time out and an exit of 255 (ssh's own failure) are the environment's, status 3, the host key apart from the rest; a 127 or 126 is that the program is not there, status 3; a refusal of the forced command (status 2 with no report) is status 2; a report that is not the one JSON document is malformed; otherwise the remote report, with its own status.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

remoteOfFannedfunctionno test imports it
function remoteOfFanned(row: Fanned<RemoteOutcome>): RemoteOutcome

The outcome a fan-out row comes to.

exitOfRemotefunction
function exitOfRemote(rows: readonly RemoteOutcome[]): number

The status of a run over many targets: 0 where every target's run ended with 0; 3 where every one failed for the environment; 2 where every one refused; else 1, a partial failure, with the table of each host to say which.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

statusWordfunctionno test imports it
function statusWord(r: RemoteOutcome): string

The status word of a row for the table.

hostTablefunction
function hostTable(rows: readonly RemoteOutcome[]): string

A table of one line for each host: its id, how it went, its status and the first thing it said.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

reportOfRemotefunction
function reportOfRemote(rows: readonly RemoteOutcome[]): Outcome

One report of a run over targets (the nested hand-off for many hosts): the table as its text, the data of each host under its id, and every problem of every host once, each marked with the target it is of; a failure of the run as a whole where some host failed.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.