IF Commons GitHub

governance/plan

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-bridge-plans FR-001, 0002-bridge-plans FR-002, 0002-bridge-plans FR-003, 0002-bridge-plans FR-004

The vocabulary of a bridge: the modes of a transfer, the rails that bound it, and the plan that comes before any change. A plan is a value: a list of actions, a closed union, in a fixed order, with what it would lose and a hash of its whole, so that a person can review it and the apply of it can refuse to run when what it was made from has changed.

import { COMPARATORS, describeAction } from "./plan.ts";
COMPARATORS; // ["native-digest", "size-mtime", "content-hash"]

Source: commons/anyfs-bridge/src/governance/plan.ts

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

COMPARATORSconst
const COMPARATORS: readonly ["native-digest", "size-mtime", "content-hash"]

The way a pair of files is compared, cheapest first: the revisions when both are SHA-256 of the bytes, the size and the time, or the bytes themselves hashed.

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

Comparatortypeno test imports it
type Comparator = (typeof COMPARATORS)[number];

One way to compare.

Decidertypeno test imports it
type Decider = "absent" | "size" | "native-digest" | "size-mtime" | "content-hash" | "undecided";

What decided that an action is needed: the comparator, absent where the file is not at the destination, size where the sizes differ, and undecided where no comparator could say, so that the file is copied again.

PlanHashtypeno test imports it
type PlanHash = Brand<string, "anyfs-bridge plan hash">;

The sha-256 of a plan, in hex. Made only by hashPlan.

Modetypeno test imports it
type Mode =
  | { readonly kind: "copy" }
  | { readonly kind: "sync"; readonly deletes: DeletePolicy }
  | { readonly kind: "move" }
  | { readonly kind: "check" };

What a transfer does: copy never deletes; sync makes the destination equal and deletes only within its allowance; move copies, checks, and removes the source; check only compares.

ModeNametypeno test imports it
type ModeName = Mode["kind"];

The name of a mode.

DeletePolicytypeno test imports it
type DeletePolicy = { readonly kind: "forbid" } | { readonly kind: "allow"; readonly max: number };

Whether a plan may delete at the destination, and at most how many files.

forbidDeletesconst
const forbidDeletes: DeletePolicy

No deletes.

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

allowDeletesconst
const allowDeletes: (max: number) => DeletePolicy

Deletes, at most max.

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

CONFLICT_REASONSconstno test imports it
const CONFLICT_REASONS: readonly ["target-collision", "case-collision", "both-changed", "no-time"]

What a conflict is: two files that would become one, or two sides that changed.

ConflictReasontypeno test imports it
type ConflictReason = (typeof CONFLICT_REASONS)[number];

One reason for a conflict.

SKIP_REASONSconstno test imports it
const SKIP_REASONS: readonly ["never-overwrite", "protected", "delete-not-allowed", "too-large"]

Why a file is left as it is.

SkipReasontypeno test imports it
type SkipReason = (typeof SKIP_REASONS)[number];

One reason for a skip.

LOSS_KINDSconstno test imports it
const LOSS_KINDS: readonly ["unportable-name", "too-large", "case-folded"]

What a destination would not keep of a file: a name it refuses, a size it cannot hold, a name it folds to another by case.

LossKindtypeno test imports it
type LossKind = (typeof LOSS_KINDS)[number];

One kind of loss.

Losstypeno test imports it
type Loss = { readonly kind: LossKind; readonly target: Path; readonly detail: string };

What would be lost at a target.

Actiontype
type Action = | { readonly kind: "create"; readonly rel: Path; readonly target: Path; readonly size: number; readonly … (859 characters)
type Action =
  | { readonly kind: "create"; readonly rel: Path; readonly target: Path; readonly size: number; readonly src: Revision; readonly decided: Decider; readonly losses: readonly Loss[] }
  | { readonly kind: "update"; readonly rel: Path; readonly target: Path; readonly size: number; readonly src: Revision; readonly dst: Revision; readonly decided: Decider; readonly losses: readonly Loss[] }
  | { readonly kind: "delete"; readonly target: Path; readonly dst: Revision }
  | { readonly kind: "rename"; readonly from: Path; readonly to: Path; readonly dst: Revision }
  | { readonly kind: "remove-source"; readonly rel: Path; readonly src: Revision }
  | { readonly kind: "skip"; readonly target: Path; readonly reason: SkipReason }
  | { readonly kind: "conflict"; readonly target: Path; readonly reason: ConflictReason; readonly detail: string };

One thing a plan does, a closed union. Paths are relative to the endpoint's prefix; rel is the path at the source and target the path at the destination.

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

ActionKindtypeno test imports it
type ActionKind = Action["kind"];

The name of an action.

ACTION_ORDERconst
const ACTION_ORDER: readonly ("conflict" | "create" | "delete" | "remove-source" | "rename" | "skip" | "update")[]

The kinds of action in the order a plan lists them.

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

Plantype
type Plan = { readonly mode: ModeName; readonly source: string; readonly dest: string; readonly actions: readonl… (455 characters)
type Plan = {
  readonly mode: ModeName;
  readonly source: string;
  readonly dest: string;
  readonly actions: readonly Action[];
  readonly unchanged: number;
  /** What a transfer carries: the bytes of an object. Its other facts (type, time, mode) are the destination's own. */
  readonly carries: readonly ["bytes"];
  /** The bytes that would be written. */
  readonly bytes: number;
  readonly losses: readonly Loss[];
  readonly hash: PlanHash;
};

What a plan is: the mode, where from and where to, the actions in order, what is already equal, what it would lose and its hash.

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

Railstypeno test imports it
type Rails = { /** Only the files matching one of these are transferred; none means every file. */ readonly include?… (724 characters)
type Rails = {
  /** Only the files matching one of these are transferred; none means every file. */
  readonly include?: readonly Glob[];
  /** Files matching one of these are left out. */
  readonly exclude?: readonly Glob[];
  /** Files at the destination matching one of these are never deleted or renamed. */
  readonly protect?: readonly Glob[];
  readonly maxFiles?: number;
  readonly maxBytes?: number;
  /** Files larger than this are left as they are. */
  readonly maxObjectBytes?: number;
  /** Refuse unless the destination holds nothing under its prefix. */
  readonly requireEmptyDestination?: boolean;
  /** Never replace a file that is already at the destination. */
  readonly neverOverwrite?: boolean;
};

The rails that bound a transfer. Every pattern is a glob; the limits count the files and bytes that would be written.

PlanRefusaltypeno test imports it
type PlanRefusal = | { readonly kind: "unavailable"; readonly problem: Problem } | { readonly kind: "delete-budget";… (499 characters)
type PlanRefusal =
  | { readonly kind: "unavailable"; readonly problem: Problem }
  | { readonly kind: "delete-budget"; readonly wanted: number; readonly max: number }
  | { readonly kind: "rails"; readonly reason: "max-files" | "max-bytes" | "destination-not-empty"; readonly detail: string }
  | { readonly kind: "lossy"; readonly losses: readonly Loss[] }
  | { readonly kind: "capability"; readonly detail: string }
  | { readonly kind: "rewrite"; readonly rel: Path; readonly detail: string };

Why a plan was not made.

describeActionfunction
function describeAction(action: Action): string

An action in a few words.

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

describeRefusalfunction
function describeRefusal(refusal: PlanRefusal): string

A refusal in a sentence.

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

describeModefunction
function describeMode(mode: Mode): string

What a mode is called in a sentence.

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

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