IF Commons GitHub

physical/run

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-machine-probe-observation FR-004

Asking a probe: a request sent through a way of running the command (the ssh client on a target, a container, the machine itself), the facts read into an observation, and one osquery SELECT answered as rows. A probe that cannot be reached, refuses, or gives what cannot be read is an error that says so, never an observation that is guessed.

import { observe } from "./run.ts";
const r = await observe(async () => ({ code: 0, stdout: "@probe\nat=2026-12-01T00:00:00Z\nversion=1\n", stderr: "" }));
r.kind; // "ok"

Source: commons/machine-probe/src/physical/run.ts

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

physical.Rantypeno test imports it
type Ran = { readonly code: number; readonly stdout: string; readonly stderr: string };

What running a command gave.

physical.Sendtypeno test imports it
type Send = (request: string) => Promise<Ran>;

A way of sending one request to a probe and getting what it printed: the request is the text the probe is given.

physical.ProbeErrortypeno test imports it
type ProbeError = { readonly kind: "refused" | "unreachable" | "unreadable"; readonly message: string };

Why a probe gave no answer.

physical.observefunctionno test imports it
function observe(send: Send): Promise<Result<Observed, ProbeError>>

The facts of a machine as an observation, or why none: unreachable where the command did not run, refused where the probe refused, unreadable where what it printed is not facts.

physical.Rowtypeno test imports it
type Row = Readonly<Record<string, string>>;

One row of an osquery answer: every value is text, as osquery prints it.

physical.queryfunctionno test imports it
function query(send: Send, sql: string): Promise<Result<readonly Readonly<Record<string, string>>[], ProbeError>>

The rows of one osquery SELECT, or why not: the query is refused here before it is sent where it is not a single SELECT.

physical.sendViafunctionno test imports it
function sendVia(executor: Executor): Send

A way of sending requests through an executor of Headless: the ssh target (its host key checked against the repository's known hosts), a container or this machine. The request is the command, as the probe's forced command reads it.

Rantypeno test imports it
type Ran = { readonly code: number; readonly stdout: string; readonly stderr: string };

What running a command gave.

Sendtype
type Send = (request: string) => Promise<Ran>;

A way of sending one request to a probe and getting what it printed: the request is the text the probe is given.

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

ProbeErrortypeno test imports it
type ProbeError = { readonly kind: "refused" | "unreachable" | "unreadable"; readonly message: string };

Why a probe gave no answer.

observefunction
function observe(send: Send): Promise<Result<Observed, ProbeError>>

The facts of a machine as an observation, or why none: unreachable where the command did not run, refused where the probe refused, unreadable where what it printed is not facts.

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

Rowtypeno test imports it
type Row = Readonly<Record<string, string>>;

One row of an osquery answer: every value is text, as osquery prints it.

queryfunction
function query(send: Send, sql: string): Promise<Result<readonly Readonly<Record<string, string>>[], ProbeError>>

The rows of one osquery SELECT, or why not: the query is refused here before it is sent where it is not a single SELECT.

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

sendViafunction
function sendVia(executor: Executor): Send

A way of sending requests through an executor of Headless: the ssh target (its host key checked against the repository's known hosts), a container or this machine. The request is the command, as the probe's forced command reads it.

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

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