ReplicaNametypetype ReplicaName = DocId;The name of a store in a mirror: an identifier, because the ledger of a replica is a document of that name.
A mirrored store: one primary, which is the authority, and replicas that are brought up to it. A write goes to the primary and nowhere else, and is queued for the replicas, which are converged by bridge plans when settle is called or, if the policy says so, after each write; a replica that fails never fails a write, it is behind; a replica that someone else changed is diverged and is never merged. Reads are the primary's alone, so that no stale replica is read by mistake through the store; read of the mirror answers from a replica where the primary cannot be reached, and says that it did, which replica, and what the replica is known to hold. The ledgers, which say what each replica was last brought to, are kept on the primary below a reserved prefix that the store never shows and never lets be changed. The store has the capabilities of the primary, and a replica can become the primary, as an explicit act, only where it has all of them.
import { openMirror, parseReplicaName } from "./mirror.ts";
// const mirror = await openMirror({ name: ssh, store: sshStore }, [{ name: git, store: gitStore }], { deletes: allowDeletes(50), fallback: "never", auto: "manual" });
// await mirror.value.settle();ReplicaNametypetype ReplicaName = DocId;The name of a store in a mirror: an identifier, because the ledger of a replica is a document of that name.
parseReplicaNamefunctionfunction parseReplicaName(text: string): Result<DocId, string>A name from text, or why it is not one.
Membertypetype Member<S> = { readonly name: ReplicaName; readonly store: S };A store of a mirror, with its name.
MirrorPolicytypetype MirrorPolicy = {
/** What a convergence may delete at a replica: nothing, or at most so many paths each time. */
… (719 characters)type MirrorPolicy = {
/** What a convergence may delete at a replica: nothing, or at most so many paths each time. */
readonly deletes: DeletePolicy;
/** Whether `read` answers from a replica where the primary cannot be reached. */
readonly fallback: "never" | "unavailable";
/** Whether a convergence is started after each write (never waited for), or only when `settle` is called. */
readonly auto: "manual" | "after-write";
/** Where the ledgers are kept on the primary: `_mirror-ledger` where not given. */
readonly ledgerPrefix?: Prefix;
readonly pageSize?: number;
/** The time in milliseconds since the epoch, for the events: the system's where not given. */
readonly now?: () => number;
};How a mirror works.
MirrorProblemtypeno test imports ittype MirrorProblem =
| { readonly kind: "primary-lacks"; readonly missing: readonly Capability[] }
| { readonly kind… (592 characters)type MirrorProblem =
| { readonly kind: "primary-lacks"; readonly missing: readonly Capability[] }
| { readonly kind: "duplicate-name"; readonly name: string }
| { readonly kind: "bad-prefix"; readonly detail: string }
| { readonly kind: "ledger"; readonly problem: LedgerProblem }
| { readonly kind: "unknown-replica"; readonly name: string }
| { readonly kind: "capability"; readonly replica: string; readonly missing: readonly Capability[] }
| { readonly kind: "refused"; readonly refusal: PromoteRefusal }
| { readonly kind: "unavailable"; readonly refusal: PlanRefusal };Why a mirror could not be made or did not do what was asked.
ReplicaStatustypeno test imports ittype ReplicaStatus = { readonly replica: ReplicaName; readonly state: ReplicaState; readonly reachable: boolean; readonly detail?: string };A replica as status and settle report it: its state against the primary, as the bridge names the states, and whether it could be reached.
Settledtypeno test imports ittype Settled = ReplicaStatus & { readonly applied: number; readonly failed: number; readonly ledger: "saved" | LedgerProblem };What a convergence of one replica did: the replica's state afterwards, the changes made and failed, and whether its ledger was saved.
Standingtypeno test imports ittype Standing = "converged" | "pending" | "diverged" | "unknown";What a replica is known to hold of a path: what it was last brought to (converged), that and the primary has changed it since (pending), something else (diverged) or nothing is known (unknown).
Answeredtypeno test imports ittype Answered<T> = { readonly from: "primary"; readonly degraded: false; readonly value: T } | { readonly from: ReplicaName; readonly degraded: true; readonly standing: Standing; readonly value: T };A read that says where it was answered: by the primary, or by a replica, which is degraded and says what the replica is known to hold.
Promotedtypeno test imports ittype Promoted = { readonly from: ReplicaName; readonly to: ReplicaName; readonly lost: number; readonly ledgers: "saved" | readonly LedgerProblem[] };What a promotion did.
Rolestypeno test imports ittype Roles = { readonly primary: ReplicaName; readonly replicas: readonly ReplicaName[] };The roles of the stores of a mirror.
CoreOftypetype CoreOf<C extends Capability> = [CoreCapability] extends [C] ? unknown : { readonly "a primary has the capabilities": CoreCapability };What a primary must have, checked by the compiler: the core capabilities, whatever else it has.
Mirrortypetype Mirror<C extends Capability> = {
/** The store: the capabilities of the primary, its reads, its writes, and nothi… (1413 characters)type Mirror<C extends Capability> = {
/** The store: the capabilities of the primary, its reads, its writes, and nothing of the ledgers. */
readonly store: Store<Carried<C>>;
/** Brings the replicas (or the one named) up to the primary, one after the other. */
settle(only?: ReplicaName): Promise<Result<readonly Settled[], MirrorProblem>>;
/** The state of each replica against the primary; nothing is changed. */
status(): Promise<readonly ReplicaStatus[]>;
/** Reads a path: the primary's answer, or, where the policy says so and the primary cannot be reached, a replica's, marked as degraded. */
read(path: Path): Promise<Result<Answered<Read>, Problem>>;
/** Makes a replica the primary: the old primary becomes a replica. Only as the bridge allows, and only where the replica has every capability of the store. */
promote(replica: ReplicaName, options?: Pick<PromoteOptions, "acceptLoss" | "acceptDivergence">): Promise<Result<Promoted, MirrorProblem>>;
roles(): Roles;
/** Calls `listener` for each event; the function it gives stops it. */
subscribe(listener: (event: MirrorEvent) => void): () => void;
/** The events from now on, until the mirror is closed. */
events(): AsyncIterable<MirrorEvent>;
/** Waits for the convergences that were started. */
drain(): Promise<void>;
/** Waits for them, stops starting more and ends the events. */
close(): Promise<void>;
};A mirror: the store, and what is done with the replicas.
openMirrorfunctionfunction openMirror<C extends Capability>(primary: Member<Store<C>> & CoreOf<C>, replicas: readonly Member<Dest>[], policy: MirrorPolicy): Promise<Result<Mirror<C>, MirrorProblem>>Opens a mirror: the ledgers of the replicas are read from the primary (a replica with none is brought to nothing), and the mirror is ready. A ledger that cannot be read is a problem, never an empty ledger.
divergedPathsfunctionno test imports itfunction divergedPaths(state: ReplicaState): readonly Path[]The paths of a state that is diverged, in order; none for any other.