IF Commons GitHub

physical/fleet

Written to: 9 requirements: 9 proved, 0 partly, 0 failing, 0 with no test recorded. 0006-estate-fleet-store FR-001, 0006-estate-fleet-store FR-002, 0006-estate-fleet-store FR-003, 0006-estate-fleet-store FR-004, 0006-estate-fleet-store FR-005, 0006-estate-fleet-store FR-006 and 3 more

The fleet store (commons estate 0006-estate-fleet-store): the physical layer of Estate, which keeps an estate as typed documents in a store of AnyFS. The store of the system of record is the primary, typically a host reached by SSH; the replicas are mirrors of it (a branch of a Git repository, a bucket, a folder) and are brought up to it by settle. Every write states what it expects, so that two operators who change the same asset are one winner and one conflict; every document comes back with its revision; and what is in a folder and is not a good document is a finding, never a failure.

import { devFleetStore } from "./dev.ts";
const fleet = await devFleetStore({ kind: "memory" }, { actor: "operator" });
fleet.kind; // "ok"

Source: commons/estate/src/physical/fleet.ts

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

FleetCapabilitiestypeno test imports it
type FleetCapabilities = "read" | "write" | "list" | "stat" | "delete" | "cas";

What the primary must have: the core of a store, and revisions that can be expected.

PrimaryStoretypeno test imports it
type PrimaryStore = Store<FleetCapabilities>;

The store of the system of record.

ReplicaStoretypeno test imports it
type ReplicaStore = Store<"read" | "write" | "list" | "stat" | "delete">;

A mirror of the system of record: a store that can be read, listed and written, as the bridge asks of a destination.

FleetConfigtypeno test imports it
type FleetConfig = { /** The store of the system of record, and the name it has in the mirror. */ readonly primary: … (1291 characters)
type FleetConfig = {
  /** The store of the system of record, and the name it has in the mirror. */
  readonly primary: Member<PrimaryStore>;
  /** The mirrors of it. */
  readonly replicas?: readonly Member<ReplicaStore>[];
  /** How the mirror works: it deletes nothing at a replica, a read never falls back to one, and a settlement is made when `settle` is called, unless it says otherwise. */
  readonly mirror?: Partial<MirrorPolicy>;
  /** The name of the fleet: made the manifest's where one is made, and asked for where one is read. The name of the primary where it is not given. */
  readonly identity?: string;
  /** Whether a store with no manifest is made a fleet store. A store is made one only when it is asked to be. */
  readonly create?: boolean;
  /** Who writes: put in the declarations and in the events. */
  readonly actor: string;
  /** The time in milliseconds since the epoch: the system's where not given. */
  readonly clock?: () => number;
  /** How a call that failed because the host could not be reached is repeated. Not at all where not given. */
  readonly retry?: { readonly policy: RetryPolicy; readonly clock: Pick<Clock, "sleep"> };
  /** The attempts of an update that another writer changed first; 5 where not given. */
  readonly attempts?: number;
};

What a fleet store is opened with, written as code.

ObservationInputtypeno test imports it
type ObservationInput = {
  readonly asset: string;
  /** When it was observed, as an instant. */
  readonly at: string;
  /** What it is attributed to: a probe, an agent, a connector. Never empty. */
  readonly source: string;
  readonly state: Readonly<Record<string, Json>>;
  readonly results?: readonly StoredResult[];
};

What an observation is made from.

Recordedtypeno test imports it
type Recorded = { readonly created: boolean; readonly path: Path; readonly rev: Revision };

What an observation was written as.

ObservationRangetypeno test imports it
type ObservationRange = { readonly from?: string; readonly to?: string; readonly limit?: number };

The observations of an asset between two instants, as many as asked for.

Listedtypeno test imports it
type Listed<T> = { readonly docs: readonly Doc<T, DocId>[]; readonly findings: readonly Finding[] };

Documents and what was found beside them.

FleetEventtype
type FleetEvent = | { readonly kind: "manifest-made"; readonly at: number; readonly actor: string; readonly store: str… (932 characters)
type FleetEvent =
  | { readonly kind: "manifest-made"; readonly at: number; readonly actor: string; readonly store: string }
  | { readonly kind: "asset"; readonly at: number; readonly actor: string; readonly asset: string; readonly rev: Revision; readonly created: boolean }
  | { readonly kind: "observation"; readonly at: number; readonly actor: string; readonly asset: string; readonly observedAt: string; readonly created: boolean }
  | { readonly kind: "declaration"; readonly at: number; readonly actor: string; readonly asset: string; readonly rev: Revision }
  | { readonly kind: "risk"; readonly at: number; readonly actor: string; readonly asset: string; readonly policy: string }
  | { readonly kind: "evidence"; readonly at: number; readonly actor: string; readonly subject: string; readonly digest: string; readonly created: boolean }
  | { readonly kind: "mirror"; readonly at: number; readonly event: MirrorEvent };

What an event of a fleet store says.

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

SnapshotOptionstypeno test imports it
type SnapshotOptions = {
  /** The latest observation of each asset, or all of them. Latest where not given. */
  readonly observations?: "latest" | "all";
  /** Whether the references to evidence are read. Not where not given. */
  readonly evidence?: boolean;
  /** How many times the reading is begun again when a document changed under it. 3 where not given. */
  readonly attempts?: number;
};

What a snapshot is asked for.

FleetStoretypeno test imports it
type FleetStore = { /** What the store says it is. */ readonly manifest: Manifest; /** The store the documents are… (4336 characters)
type FleetStore = {
  /** What the store says it is. */
  readonly manifest: Manifest;
  /** The store the documents are in: the primary, with the mirror in front of it where there are replicas. */
  readonly store: PrimaryStore;
  /** Writes an asset: it is made where the expectation is `absent`, changed where it is the revision read, and written over where it is `any`. */
  putAsset(asset: Asset, expect: Expect): Promise<Result<Saved<DocId>, FleetProblem>>;
  /** The asset with the revision it was read at. */
  getAsset(id: string): Promise<Result<Doc<Asset, DocId>, FleetProblem>>;
  /** Changes an asset by reading it, calling `change` with it (or with nothing where there is none) and writing the result expecting the revision read; it is begun again where another writer changed it first. `change` gives the asset to write or nothing to leave it. */
  updateAsset(id: string, change: (current: Asset | undefined) => Asset | undefined | Promise<Asset | undefined>): Promise<Result<Updated<Asset, DocId>, FleetProblem>>;
  /** Every asset, and what is in the folder that is not one. */
  listAssets(): Promise<Result<Listed<Asset>, FleetProblem>>;
  /** Writes an observation once: the same observation again is `created: false`, and a different one at the same instant is refused. */
  recordObservation(input: ObservationInput): Promise<Result<Recorded, FleetProblem>>;
  /** The observations of an asset in the order of their instants, with what is in its folder that is not one. */
  observationsOf(asset: string, range?: ObservationRange): Promise<Result<{ readonly observations: readonly StoredObservation[]; readonly findings: readonly Finding[] }, FleetProblem>>;
  /** The latest observation of an asset, or nothing where it was never observed. */
  latestObservation(asset: string): Promise<Result<StoredObservation | undefined, FleetProblem>>;
  /** Writes what is declared of an asset, with the expectation that says what it replaces. */
  declare(asset: string, declared: Readonly<Record<string, Json>>, expect: Expect): Promise<Result<Saved<DocId>, FleetProblem>>;
  /** What is declared of an asset, or nothing where nothing is. */
  declarationOf(asset: string): Promise<Result<Doc<StoredDeclaration, DocId> | undefined, FleetProblem>>;
  /** Accepts a risk of an asset as the estate's rule allows (a reason in words, a day within a year); the risk of the same policy is replaced. */
  acceptRisk(asset: string, risk: AcceptedRisk): Promise<Result<StoredAcceptances, FleetProblem>>;
  /** The risks accepted of an asset. */
  risksOf(asset: string): Promise<Result<readonly AcceptedRisk[], FleetProblem>>;
  /** Writes the reference to a piece of evidence, once: the same subject and digest again is `created: false`. */
  recordEvidence(ref: StoredEvidence): Promise<Result<{ readonly created: boolean; readonly path: Path }, FleetProblem>>;
  /** The references to the evidence of a subject. */
  evidenceOf(subject: string): Promise<Result<{ readonly refs: readonly StoredEvidence[]; readonly findings: readonly Finding[] }, FleetProblem>>;
  /** Everything the logical layer judges, read from the documents. It is begun again where a document changed under the reading, and says whether it ended up stable. */
  snapshot(options?: SnapshotOptions): Promise<Result<FleetSnapshot, FleetProblem>>;
  /** The versions a replica that keeps history holds of an asset, newest first. */
  history(asset: string, replica: string): Promise<Result<readonly { readonly rev: Revision; readonly size: number; readonly modified?: string }[], FleetProblem>>;
  /** The state of each replica against the primary; nothing is changed. Nothing where there are no replicas. */
  status(): Promise<readonly ReplicaStatus[]>;
  /** Brings the replicas up to the primary. */
  settle(only?: string): Promise<Result<readonly Settled[], FleetProblem>>;
  /** Makes a replica the primary, as the bridge allows it, and says so in an event. */
  promote(replica: string, options?: { readonly acceptLoss?: number; readonly acceptDivergence?: boolean }): Promise<Result<Promoted, FleetProblem>>;
  /** Calls `listener` for each event; the function it gives stops it. */
  subscribe(listener: (event: FleetEvent) => void): () => void;
  /** Waits for the settlements that were started and stops the mirror. */
  close(): Promise<void>;
};

A fleet store.

openFleetStorefunction
function openFleetStore(config: FleetConfig): Promise<Result<FleetStore, FleetProblem>>

Opens a fleet store. The mirror is made first where there are replicas, and the documents are read and written through it. The manifest is read: a store of a newer schema or another layout, or another fleet than the one asked for, is refused with the reason; a store with none is made a fleet store only when create is set.

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

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