IF Commons GitHub

logical/apply

Written to: 5 requirements: 5 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-bridge-transfer FR-008, 0003-bridge-transfer FR-009, 0003-bridge-transfer FR-010, 0003-bridge-transfer FR-011, 0003-bridge-transfer FR-012

The apply of a plan: the only place a bridge changes anything. It refuses a plan that is not the one a person approved or that the stores no longer make; it runs the actions with a bounded number at once; it writes only what the plan says, each write expecting what the plan saw (so that a change made since is a conflict and not an overwrite); it uses the batch of the destination where it has one and the caller asks for it; it checks what it wrote; and it tells what it did as events and ends with a report of every action. Nothing is thrown: a store that fails makes a failed outcome.

import { apply } from "./apply.ts";
// const report = await apply(prepared, { verify: "auto" });

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

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

VerifyModetypeno test imports it
type VerifyMode = "auto" | "read-back" | "none";

How what was written is checked: auto by the revision where it is the hash of the bytes and by reading it back where it is not, read-back always by reading, none not at all.

Journaltypeno test imports it
type Journal = { isDone(key: string): Promise<boolean>; markDone(key: string): Promise<void> };

A record of what is done, so that an apply that stopped can go on: a key is marked when its action is finished.

memoryJournalfunction
function memoryJournal(done?: Iterable<string>): Journal & { readonly keys: () => readonly string[]; }

A journal in memory.

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

ApplyOptionstypeno test imports it
type ApplyOptions = { /** At most this many actions at once. Default 4. */ readonly concurrency?: number; readonly… (800 characters)
type ApplyOptions = {
  /** At most this many actions at once. Default 4. */
  readonly concurrency?: number;
  readonly verify?: VerifyMode;
  /** Make the writes, updates and deletes as one batch where the destination has one. Default false. */
  readonly atomic?: boolean;
  /** Make the plan again first and refuse if it is not the same plan. Default true. */
  readonly recheck?: boolean;
  /** Go on with a plan that was applied in part: do not make the plan again, and skip what the journal says is done. */
  readonly resume?: boolean;
  readonly journal?: Journal;
  /** The hash of the plan a person approved. */
  readonly approved?: PlanHash;
  /** Leave the conflicts of the plan and do the rest. Default false: a plan with conflicts is refused. */
  readonly skipConflicts?: boolean;
};

How an apply runs.

Verifiedtypeno test imports it
type Verified = "verified" | "unverifiable";

Whether what was written is what the plan meant.

Failuretypeno test imports it
type Failure =
  | { readonly kind: "problem"; readonly problem: Problem }
  | { readonly kind: "stale-source"; readonly detail: string }
  | { readonly kind: "mismatch"; readonly detail: string }
  | { readonly kind: "not-run"; readonly detail: string };

Why an action did not happen.

Outcometypeno test imports it
type Outcome = { readonly action: Action; readonly status: "done" | "failed" | "skipped"; readonly verified?: Verified; readonly failure?: Failure; readonly guarded: boolean };

What one action came to. guarded says whether its write expected a revision.

Reporttypeno test imports it
type Report = {
  readonly hash: PlanHash;
  readonly outcomes: readonly Outcome[];
  readonly done: number;
  readonly failed: number;
  readonly skipped: number;
  readonly bytes: number;
  /** The writes that expected no revision, because the destination cannot. */
  readonly unguarded: number;
};

What an apply did.

ApplyEventtype
type ApplyEvent =
  | { readonly kind: "planned"; readonly actions: number }
  | { readonly kind: "started"; readonly action: Action }
  | { readonly kind: "outcome"; readonly outcome: Outcome }
  | { readonly kind: "finished"; readonly report: Report };

What an apply tells as it goes.

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

ApplyRefusaltypeno test imports it
type ApplyRefusal =
  | { readonly kind: "stale"; readonly approved: PlanHash; readonly found: PlanHash }
  | { readonly kind: "not-applicable"; readonly detail: string }
  | { readonly kind: "replan"; readonly refusal: PlanRefusal }
  | { readonly kind: "lossy"; readonly losses: readonly Loss[] }
  | { readonly kind: "conflicts"; readonly count: number };

Why an apply did not start.

applyStreamfunction
function applyStream(prepared: Prepared, options?: ApplyOptions): Promise<Result<AsyncIterable<ApplyEvent>, ApplyRefusal>>

Runs a prepared plan, telling what it does as events: the last is finished with the report. A refusal is the value of the first step.

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

applyfunction
function apply(prepared: Prepared, options?: ApplyOptions): Promise<Result<Report, ApplyRefusal>>

Runs a prepared plan and ends with the report.

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

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