FleetCapabilitiestypeno test imports ittype FleetCapabilities = "read" | "write" | "list" | "stat" | "delete" | "cas";What the primary must have: the core of a store, and revisions that can be expected.
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"FleetCapabilitiestypeno test imports ittype 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 ittype PrimaryStore = Store<FleetCapabilities>;The store of the system of record.
ReplicaStoretypeno test imports ittype 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 ittype 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 ittype 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 ittype Recorded = { readonly created: boolean; readonly path: Path; readonly rev: Revision };What an observation was written as.
ObservationRangetypeno test imports ittype 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 ittype Listed<T> = { readonly docs: readonly Doc<T, DocId>[]; readonly findings: readonly Finding[] };Documents and what was found beside them.
FleetEventtypetype 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.
SnapshotOptionstypeno test imports ittype 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 ittype 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.
openFleetStorefunctionfunction 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.