IF Commons GitHub

sql/federate/fanout

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0059-sql-federate FR-001, 0059-sql-federate FR-002, 0059-sql-federate FR-003, 0059-sql-federate FR-004

Fan-out (commons data 0059-sql-federate): one read-only query asked of many targets at once. A target is anything that answers a query: a Driver (0056) with a name and, where it matters, a platform: a database, or a machine asked through osquery (0058). Every target's answer is a value: its rows, or a typed error (it timed out, it failed, it gave more rows than the plan allows), so that one target failing is a line in the result and not the end of the run. The result is partial by default; a quorum says how many must answer for it to count.

Source: commons/data/sql/federate/fanout.ts

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

failuresconst
const failures: (r: FanOut) => readonly ({ readonly target: string; readonly status: "error"; readonly error: FanOutError; readonly durationMs: number; readonly collectedAt: string; } & { readonly status: "error"; })[]

The outcomes that failed, with the targets they are of.

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

fanOutfunction
function fanOut(plan: Plan): Promise<FanOut>

Asks every target the query, at most concurrency at a time.

ParameterWhat it is
planthe query, the targets and the limits

Returns: every target's outcome; a target that fails is an outcome, never a throw

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

FanOutinterfaceno test imports it
interface FanOut

What a fan-out gave.

MemberTypeWhat it is
sqlstring
outcomesreadonly Outcome[]Every target's outcome, in the order of the plan.
oknumber
failednumber
completebooleanWhether every target answered.
quorumMetbooleanWhether enough answered: the share that did is at least the plan's quorum.
quorumnumber
startedAtstringWhen the run began.
FanOutErrortypeno test imports it
type FanOutError =
  | { readonly kind: "timeout"; readonly ms: number }
  | { readonly kind: "too-many-rows"; readonly max: number }
  | { readonly kind: "failed"; readonly message: string; /** What the driver rejected with, where it is a typed error (osquery's `OsqueryFailure` has `.error`). */ readonly cause?: unknown };

Why a target gave no rows.

Valuetypeno test imports it
type Value = string | number | boolean | null;

A value of a row as a target gives it.

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