Ledgertypetype Ledger = { readonly applied: ReadonlyMap<Path, string> };For each path, the SHA-256 in hex of the bytes the replica was last brought to.
A mirror: one store is the primary and the others are replicas of it, and a replica is in one of three states. It is in-sync where it holds what the primary holds; it is behind where the primary has changed and the replica has not been touched; it is diverged where the replica was changed by someone other than the mirror. A ledger records, for each path, the bytes the replica was last brought to, and the states are decided against it. A diverged path is never merged and never overwritten: the mirror leaves it, says which it is, and a person decides. A replica can be made the primary only as an explicit act, which says what would be lost.
import { emptyLedger } from "./mirror.ts";
emptyLedger.applied.size; // 0Ledgertypetype Ledger = { readonly applied: ReadonlyMap<Path, string> };For each path, the SHA-256 in hex of the bytes the replica was last brought to.
emptyLedgerconstconst emptyLedger: LedgerA ledger of a replica that has been brought to nothing.
ReplicaStatetypeno test imports ittype ReplicaState =
| { readonly kind: "in-sync" }
| { readonly kind: "behind"; readonly pending: number }
| { readonly kind: "diverged"; readonly paths: readonly Path[]; readonly pending: number };The state of a replica against its primary.
MirrorOptionstypeno test imports ittype MirrorOptions = { readonly rails?: Pick<Rails, "include" | "exclude">; readonly cache?: DigestCache; readonly pageSize?: number };How a mirror reads its two ends.
pathStatefunctionfunction pathState(primary: string | undefined, replica: string | undefined, ledger: string | undefined): PathStateThe state of one path: same where the two hold the same bytes, diverged where the replica is not what the ledger says, and behind otherwise.
replicaStatusfunctionfunction replicaStatus(primary: Endpoint<Source>, replica: Endpoint<Source>, ledger: Ledger, options?: MirrorOptions): Promise<Result<ReplicaState, PlanRefusal>>The state of a replica: nothing is changed.
Convergencetypeno test imports ittype Convergence = { readonly before: ReplicaState; readonly report: Report; readonly ledger: Ledger };What a convergence did. before is the state it found; ledger is what the replica was brought to.
convergefunctionfunction converge(primary: Endpoint<Source>, replica: Endpoint<Dest>, ledger: Ledger, options: MirrorOptions & { readonly deletes: DeletePolicy; readonly apply?: ApplyOptions | undefined; }): Promise<Result<Convergence, PlanRefusal>>Brings a replica up to its primary: the paths that are behind are copied, deleted, or made; the paths that are diverged are left as they are, and the ledger keeps what it had for them.
PromoteOptionstypeno test imports ittype PromoteOptions = { readonly acceptLoss?: number; readonly acceptDivergence?: boolean } & MirrorOptions;What a person accepts in making a replica the primary.
PromoteRefusaltypeno test imports ittype PromoteRefusal =
| { readonly kind: "behind"; readonly pending: number }
| { readonly kind: "diverged"; readonly paths: readonly Path[] }
| { readonly kind: "unavailable"; readonly refusal: PlanRefusal };Why a replica was not made the primary.
Promotiontypeno test imports ittype Promotion = { readonly primary: Endpoint<Source>; readonly replica: Endpoint<Source>; readonly ledger: Ledger; readonly lost: number };The result of a promotion: the roles swapped, with the ledger the old primary has as a replica of the new, and how many changes of the old primary the new one does not have.
promotefunctionfunction promote(primary: Endpoint<Source>, replica: Endpoint<Source>, ledger: Ledger, options?: PromoteOptions): Promise<Result<Promotion, PromoteRefusal>>Makes the replica the primary, as an explicit act. A replica that is behind is promoted only where the caller accepts to lose that many changes; a replica that is diverged only where the caller accepts the divergence. The old primary becomes a replica of the new, and its ledger holds the paths where the two agree: whatever else it holds is seen as diverged until a person decides.