IF Commons GitHub

logical/executor

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0005-reach-and-targets FR-004, 0005-reach-and-targets FR-009

Where a command runs, as a port (commons headless 0005-reach-and-targets FR-004): an Executor takes an argument vector and options and gives how the program ended, in the shapes of the system's proc (RunOptions and Output, the same fields, so that the system's own functions are executors without a wrapper). The command is defined once; local runs it here and ssh on a target, and what is told about it is the same either way. Also here, the bounded fan-out over several targets: a cap on how many run at once, a time for each, and a partial failure that is neither a success nor a crash.

import { fanOut } from "./executor.ts";
const rows = await fanOut(["a", "b"], async (id) => id.toUpperCase(), { concurrency: 1, perHostTimeoutMs: 1000 });
rows.map((r) => r.kind); // ["done", "done"]

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

5 of 24 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.ExecStdiotypeno test imports it
type ExecStdio = "piped" | "inherit" | "null";

Where a program's output goes: kept, shared with this process, or thrown away (the system's Stdio).

logical.RunOptionstypeno test imports it
type RunOptions = { readonly cwd?: string; readonly env?: Readonly<Record<string, string>>; readonly clearEnv?: bo… (409 characters)
type RunOptions = {
  readonly cwd?: string;
  readonly env?: Readonly<Record<string, string>>;
  readonly clearEnv?: boolean;
  readonly input?: string | Uint8Array;
  readonly stdin?: "inherit" | "null";
  readonly stdout?: ExecStdio;
  readonly stderr?: ExecStdio;
  readonly onLine?: (stream: "stdout" | "stderr", line: string) => void;
  readonly signal?: AbortSignal;
  readonly killAfterMs?: number;
};

What a program is run with: the same fields as the system's RunOptions.

logical.Outputtypeno test imports it
type Output = {
  readonly code: number;
  readonly success: boolean;
  readonly signal: string | null;
  readonly stdout: Uint8Array;
  readonly stderr: Uint8Array;
};

How a program ended: the same fields as the system's Output.

logical.SpawnOptionstypeno test imports it
type SpawnOptions = {
  readonly cwd?: string;
  readonly env?: Readonly<Record<string, string>>;
  readonly clearEnv?: boolean;
  readonly signal?: AbortSignal;
  readonly killAfterMs?: number;
};

What a program started for a session is given: the fields of the system's SpawnOptions, with the streams always piped.

logical.SessionStatustypeno test imports it
type SessionStatus = { readonly code: number; readonly success: boolean; readonly signal: string | null };

How a program ended, once it ends: the fields of the system's Status.

logical.Sessiontypeno test imports it
type Session = { /** Its standard input; closing the stream closes its input. */ readonly stdin: WritableStream<Uint… (551 characters)
type Session = {
  /** Its standard input; closing the stream closes its input. */
  readonly stdin: WritableStream<Uint8Array> | null;
  readonly stdout: ReadableStream<Uint8Array> | null;
  readonly stderr: ReadableStream<Uint8Array> | null;
  /** How it ended, once it ends. */
  readonly status: Promise<SessionStatus>;
  /** Sends it a signal (SIGTERM by default). */
  kill(signal?: "SIGTERM" | "SIGKILL" | "SIGINT"): void;
  /** Its whole output and error, read from the streams, and its status, once it ends. */
  output(): Promise<Output>;
};

A program that runs while it is talked to (a tool server over ssh, newline-delimited JSON-RPC on its standard input and output): its three streams, how it ended, a way to stop it, and its whole output where that is wanted at the end. The system's Child is one.

logical.Executortypeno test imports it
type Executor = { exec(argv: readonly string[], opts?: RunOptions): Promise<Output>; /** Copies the local files into… (498 characters)
type Executor = {
  exec(argv: readonly string[], opts?: RunOptions): Promise<Output>;
  /** Copies the local files into the folder `remoteDir` there. */
  put?(files: readonly string[], remoteDir: string, opts?: RunOptions): Promise<Output>;
  /** Copies the file `remote` there to the local path. */
  get?(remote: string, local: string, opts?: RunOptions): Promise<Output>;
  /** Starts the program there with piped streams. */
  spawn?(argv: readonly string[], opts?: SpawnOptions): Session;
};

Runs a program, here or elsewhere: exec(argv, opts) -> Output, which gives its output when it has ended (it does not stream). Besides: put copies files into a folder there and get copies a file from there, each by argument vectors with no shell between; spawn starts a program with piped streams and gives the session, for a protocol that is talked over its standard input and output. An executor that cannot do one of these leaves it out.

logical.ExecutorFortypeno test imports it
type ExecutorFor = (targetId: string) => Executor | undefined;

The executor for a target by its id, where there is one.

logical.textOffunctionno test imports it
function textOf(bytes: Uint8Array<ArrayBufferLike>): string

The text of an output stream.

logical.Fannedtypeno test imports it
type Fanned<T> =
  | { readonly kind: "done"; readonly id: string; readonly value: T }
  | { readonly kind: "timeout"; readonly id: string }
  | { readonly kind: "failed"; readonly id: string; readonly message: string };

What fan-out gives for one item: its value, a time out, or what it threw.

logical.FanOutLimitstypeno test imports it
type FanOutLimits = {
  /** The most that run at once; at least 1. */
  readonly concurrency: number;
  /** How long each may take; it is given an aborted signal at the end of it. */
  readonly perHostTimeoutMs: number;
};

How a fan-out is bounded.

logical.fanOutfunctionno test imports it
function fanOut<T>(ids: readonly string[], work: (id: string, signal: AbortSignal) => Promise<T>, limits: FanOutLimits): Promise<readonly Fanned<T>[]>

Runs work for each id with at most concurrency at once and at most perHostTimeoutMs each, and gives one row for each id in the order of the ids: its value, that it timed out, or that it threw. The rows are never fewer than the ids, so that one host that hangs or fails does not take the others with it.

ExecStdiotypeno test imports it
type ExecStdio = "piped" | "inherit" | "null";

Where a program's output goes: kept, shared with this process, or thrown away (the system's Stdio).

RunOptionstype
type RunOptions = { readonly cwd?: string; readonly env?: Readonly<Record<string, string>>; readonly clearEnv?: bo… (409 characters)
type RunOptions = {
  readonly cwd?: string;
  readonly env?: Readonly<Record<string, string>>;
  readonly clearEnv?: boolean;
  readonly input?: string | Uint8Array;
  readonly stdin?: "inherit" | "null";
  readonly stdout?: ExecStdio;
  readonly stderr?: ExecStdio;
  readonly onLine?: (stream: "stdout" | "stderr", line: string) => void;
  readonly signal?: AbortSignal;
  readonly killAfterMs?: number;
};

What a program is run with: the same fields as the system's RunOptions.

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

Outputtype
type Output = {
  readonly code: number;
  readonly success: boolean;
  readonly signal: string | null;
  readonly stdout: Uint8Array;
  readonly stderr: Uint8Array;
};

How a program ended: the same fields as the system's Output.

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

SpawnOptionstypeno test imports it
type SpawnOptions = {
  readonly cwd?: string;
  readonly env?: Readonly<Record<string, string>>;
  readonly clearEnv?: boolean;
  readonly signal?: AbortSignal;
  readonly killAfterMs?: number;
};

What a program started for a session is given: the fields of the system's SpawnOptions, with the streams always piped.

SessionStatustypeno test imports it
type SessionStatus = { readonly code: number; readonly success: boolean; readonly signal: string | null };

How a program ended, once it ends: the fields of the system's Status.

Sessiontypeno test imports it
type Session = { /** Its standard input; closing the stream closes its input. */ readonly stdin: WritableStream<Uint… (551 characters)
type Session = {
  /** Its standard input; closing the stream closes its input. */
  readonly stdin: WritableStream<Uint8Array> | null;
  readonly stdout: ReadableStream<Uint8Array> | null;
  readonly stderr: ReadableStream<Uint8Array> | null;
  /** How it ended, once it ends. */
  readonly status: Promise<SessionStatus>;
  /** Sends it a signal (SIGTERM by default). */
  kill(signal?: "SIGTERM" | "SIGKILL" | "SIGINT"): void;
  /** Its whole output and error, read from the streams, and its status, once it ends. */
  output(): Promise<Output>;
};

A program that runs while it is talked to (a tool server over ssh, newline-delimited JSON-RPC on its standard input and output): its three streams, how it ended, a way to stop it, and its whole output where that is wanted at the end. The system's Child is one.

Executortype
type Executor = { exec(argv: readonly string[], opts?: RunOptions): Promise<Output>; /** Copies the local files into… (498 characters)
type Executor = {
  exec(argv: readonly string[], opts?: RunOptions): Promise<Output>;
  /** Copies the local files into the folder `remoteDir` there. */
  put?(files: readonly string[], remoteDir: string, opts?: RunOptions): Promise<Output>;
  /** Copies the file `remote` there to the local path. */
  get?(remote: string, local: string, opts?: RunOptions): Promise<Output>;
  /** Starts the program there with piped streams. */
  spawn?(argv: readonly string[], opts?: SpawnOptions): Session;
};

Runs a program, here or elsewhere: exec(argv, opts) -> Output, which gives its output when it has ended (it does not stream). Besides: put copies files into a folder there and get copies a file from there, each by argument vectors with no shell between; spawn starts a program with piped streams and gives the session, for a protocol that is talked over its standard input and output. An executor that cannot do one of these leaves it out.

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

ExecutorFortypeno test imports it
type ExecutorFor = (targetId: string) => Executor | undefined;

The executor for a target by its id, where there is one.

textOffunction
function textOf(bytes: Uint8Array<ArrayBufferLike>): string

The text of an output stream.

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

Fannedtypeno test imports it
type Fanned<T> =
  | { readonly kind: "done"; readonly id: string; readonly value: T }
  | { readonly kind: "timeout"; readonly id: string }
  | { readonly kind: "failed"; readonly id: string; readonly message: string };

What fan-out gives for one item: its value, a time out, or what it threw.

FanOutLimitstypeno test imports it
type FanOutLimits = {
  /** The most that run at once; at least 1. */
  readonly concurrency: number;
  /** How long each may take; it is given an aborted signal at the end of it. */
  readonly perHostTimeoutMs: number;
};

How a fan-out is bounded.

fanOutfunction
function fanOut<T>(ids: readonly string[], work: (id: string, signal: AbortSignal) => Promise<T>, limits: FanOutLimits): Promise<readonly Fanned<T>[]>

Runs work for each id with at most concurrency at once and at most perHostTimeoutMs each, and gives one row for each id in the order of the ids: its value, that it timed out, or that it threw. The rows are never fewer than the ids, so that one host that hangs or fails does not take the others with it.

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

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