IF Commons GitHub

logical/mirror

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-bridge-twoway FR-005, 0004-bridge-twoway FR-006, 0004-bridge-twoway FR-007, 0004-bridge-twoway FR-008

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; // 0

Source: commons/anyfs-bridge/src/logical/mirror.ts

6 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.

Ledgertype
type Ledger = { readonly applied: ReadonlyMap<Path, string> };

For each path, the SHA-256 in hex of the bytes the replica was last brought to.

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

emptyLedgerconst
const emptyLedger: Ledger

A ledger of a replica that has been brought to nothing.

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

ReplicaStatetypeno test imports it
type 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 it
type MirrorOptions = { readonly rails?: Pick<Rails, "include" | "exclude">; readonly cache?: DigestCache; readonly pageSize?: number };

How a mirror reads its two ends.

pathStatefunction
function pathState(primary: string | undefined, replica: string | undefined, ledger: string | undefined): PathState

The 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.

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

replicaStatusfunction
function replicaStatus(primary: Endpoint<Source>, replica: Endpoint<Source>, ledger: Ledger, options?: MirrorOptions): Promise<Result<ReplicaState, PlanRefusal>>

The state of a replica: nothing is changed.

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

Convergencetypeno test imports it
type 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.

convergefunction
function 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.

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

PromoteOptionstypeno test imports it
type PromoteOptions = { readonly acceptLoss?: number; readonly acceptDivergence?: boolean } & MirrorOptions;

What a person accepts in making a replica the primary.

PromoteRefusaltypeno test imports it
type 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 it
type 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.

promotefunction
function 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.

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

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