IF Commons GitHub

mirror/mirror

Written to: 6 requirements: 6 proved, 0 partly, 0 failing, 0 with no test recorded. 0006-bridge-mirrored FR-001, 0006-bridge-mirrored FR-002, 0006-bridge-mirrored FR-003, 0006-bridge-mirrored FR-004, 0006-bridge-mirrored FR-005, 0006-bridge-mirrored FR-008

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();

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

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

ReplicaNametype
type ReplicaName = DocId;

The name of a store in a mirror: an identifier, because the ledger of a replica is a document of that name.

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

parseReplicaNamefunction
function parseReplicaName(text: string): Result<DocId, string>

A name from text, or why it is not one.

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

Membertype
type Member<S> = { readonly name: ReplicaName; readonly store: S };

A store of a mirror, with its name.

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

MirrorPolicytype
type 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.

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

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

Rolestypeno test imports it
type Roles = { readonly primary: ReplicaName; readonly replicas: readonly ReplicaName[] };

The roles of the stores of a mirror.

CoreOftype
type 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.

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

Mirrortype
type 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.

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

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

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

divergedPathsfunctionno test imports it
function divergedPaths(state: ReplicaState): readonly Path[]

The paths of a state that is diverged, in order; none for any other.

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