Mediumtypeno test imports ittype Medium = Store<"read" | "write" | "list">;A store that can be a medium: it reads, writes and lists.
The exchange of replicas through a medium. A medium is any store that can read, write and list, and needs nothing more: not a compare-and-swap, not a transaction. A replica publishes the rows it made as delta files that are written once and never change, takes the files the others published, and is the same as they are when all of them have taken all. Every file is checked before it is taken (its name is its identity, it is the directory's replica that made it), the replica judges it by its own trust, a file that waits for rows it does not hold is kept by the replica until they come, and a file that is not good is put aside and told of, never half taken.
import { memoryCursor, syncThrough } from "./mod.ts";
// const report = await syncThrough({ self, replica, medium, cursor: memoryCursor() });Mediumtypeno test imports ittype Medium = Store<"read" | "write" | "list">;A store that can be a medium: it reads, writes and lists.
PrunableMediumtypeno test imports ittype PrunableMedium = Store<"read" | "write" | "list" | "delete">;A medium that can also have what it holds removed.
Mergeabletypetype Mergeable = Store<"merge">;A replica as the exchange sees it: it has the merge operations.
Checkstypeno test imports ittype Checks = "all" | "none";What the exchange does where checks are concerned: all of them, or (to show that the suite notices) none of its own.
ExchangeOptionstypetype ExchangeOptions = {
/** Who this replica is. */
readonly self: ReplicaId;
readonly replica: Mergeable;
read… (1274 characters)type ExchangeOptions = {
/** Who this replica is. */
readonly self: ReplicaId;
readonly replica: Mergeable;
readonly medium: Medium;
readonly cursor: Cursor;
/** The most rows in one delta file: 5,000 where not given. */
readonly maxRows?: number;
/** The reasons for which a refused file is put aside for good: every one but a trust that may change and a time that will pass. */
readonly quarantine?: ReadonlySet<MergeRefusalKind>;
readonly limits?: Limits;
/** Whether the exchange checks a file's name and origin itself: `all` where not given. */
readonly checks?: Checks;
/** Whether to take the others' files: yes where not given (a replica may only publish). */
readonly pull?: boolean;
/** Whether to publish its own rows: yes where not given. */
readonly publish?: boolean;
/** Whoever signs the files this replica publishes: where given every file it writes carries the signature of this key, and where not the files are unsigned. */
readonly signer?: Signer;
/** A trust the files of the others are judged by before the replica judges them by its own: a file the trust refuses is refused with the kind it names (`trust`, `unsigned`, `bad-signature`, `unknown-key`) and the replica is not asked. */
readonly trust?: Trust;
};How a synchronization goes.
ExchangeProblemtypeno test imports ittype ExchangeProblem = { readonly kind: "medium"; readonly problem: Problem } | { readonly kind: "replica"; readonly problem: Problem } | { readonly kind: "cursor"; readonly detail: string };Why a synchronization could not be made at all: the medium or the replica failed. A file that fails is in the report, not here.
describeExchangeProblemfunctionno test imports itfunction describeExchangeProblem(p: ExchangeProblem): stringOne sentence for a problem.
Publishedtypeno test imports ittype Published = { readonly path: string; readonly versions: number; readonly blobs: number; readonly alreadyThere: boolean };A file published.
Asidetypeno test imports ittype Aside = { readonly path: string; readonly reason: string; readonly kind: "quarantined" | "refused" | "unreadable" };A file put aside or refused, and why.
Pulledtypeno test imports ittype Pulled = {
readonly applied: number;
readonly duplicates: number;
readonly deferred: number;
readonly versions: number;
readonly blobs: number;
readonly aside: readonly Aside[];
readonly findings: readonly MergeFinding[];
};What was done with the files of the others.
SyncReporttypeno test imports ittype SyncReport = { readonly published: readonly Published[]; readonly pulled: Pulled; readonly vector: VersionVector };What a synchronization did.
publishOwnfunctionfunction publishOwn(options: ExchangeOptions, state: CursorState): Promise<Result<{ readonly published: readonly Published[]; readonly cursor: CursorState; }, ExchangeProblem>>Publishes the rows this replica made since the cursor, as delta files: one or more, of at most maxRows rows each, in the order of their numbers, each written once with the expectation that nothing is there (a file that is already there is the same file, since its name is its identity). The cursor moves only after the files are written.
pullOthersfunctionno test imports itfunction pullOthers(options: ExchangeOptions, state: CursorState): Promise<Result<{ readonly pulled: Pulled; readonly cursor: CursorState; }, ExchangeProblem>>Takes the delta files the others published and this replica has not taken: each is checked, judged by the replica and either taken whole, kept by the replica until it holds what the file waits for, or put aside.
syncThroughfunctionfunction syncThrough(options: ExchangeOptions): Promise<Result<SyncReport, ExchangeProblem>>Brings a replica and a medium together: publishes the rows the replica made, takes the files of the others, and keeps the cursor. A second synchronization when nothing changed publishes nothing and takes nothing.
SyncPlantypeno test imports ittype SyncPlan = { readonly toPublish: number; readonly toTake: readonly string[]; readonly vector: VersionVector };What a synchronization would do, found without changing the replica or the medium.
planSyncfunctionno test imports itfunction planSync(options: ExchangeOptions): Promise<Result<SyncPlan, ExchangeProblem>>What a synchronization would do: how many of the replica's own rows are not published yet, and which delta files of the others it has not taken.
readVectorsfunctionfunction readVectors(medium: Pick<Medium, "list" | "read">): Promise<Result<Readonly<Record<string, VersionVector>>, ExchangeProblem>>The vectors the replicas published: for each replica, what it held when it last said so.
publishVectorfunctionfunction publishVector(options: Pick<ExchangeOptions, "medium" | "replica" | "self">): Promise<Result<VersionVector, ExchangeProblem>>Publishes the vector this replica holds, as the file of its own: the file is written again each time, and a replica only ever says what it holds.
Prunedtypeno test imports ittype Pruned = { readonly removed: readonly string[]; readonly horizon: VersionVector };What pruning did.
pruneDeltasfunctionfunction pruneDeltas(medium: PrunableMedium, roster: readonly ReplicaId[]): Promise<Result<Pruned, { readonly kind: "roster"; readonly detail: string; } | ExchangeProblem>>Removes the delta files that every replica of a roster has taken. Only where every replica of the roster has published its vector (the horizon of a roster is refused otherwise), and only the files whose rows are all within the horizon: what a replica that is not on the roster has not taken is lost to it, so it must be given a new copy and not the old files.