IF Commons GitHub

physical/store

Written to: 8 requirements: 8 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-anyfs-githost-store FR-006, 0002-anyfs-githost-store FR-007, 0002-anyfs-githost-store FR-013, 0002-anyfs-githost-store FR-009, 0002-anyfs-githost-store FR-010, 0002-anyfs-githost-store FR-011 and 2 more

A branch of a repository on a Git host as a store, over the REST API of the host (HostApi). A file is an object; its revision is sha256: and the digest of its bytes (the same text as in memory, on a disk and in a bucket, so a bridge compares across stores), and the host's names for the blob and the commit are given beside it. A write is checked against the commit it was read at and made as a commit on it: a write expecting no object conflicts where there is one, one expecting a revision conflicts where the file is at another, and where the host refuses the commit because the branch or a file moved under it the change is read again and checked again, so that writers of different files both win and two writers who expect the same file cannot both. A batch is one commit, a rename is one commit, a change that changes nothing is no commit, and a branch that does not exist is made only where the store was told which branch to start it from. It holds regular files: a link or another repository in the tree is refused when it is named and left out of a list.

What the store was found to be at open decides what it is: a token that may not push, or a branch it may not push to, gives a store of read, list, stat and history alone, in its type. A branch the host protects is said in the facts, and a push the host refuses for that is refused with the host's words. Writers of one store queue; writers of other stores, or of other computers, meet at the host. A call is not retried here, and the layer retrying does it for the problems that say they are worth one.

Source: commons/anyfs-githost/src/physical/store.ts

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

CommitOptionstypeno test imports it
type CommitOptions = {
  readonly author: Identity;
  /** Where it differs from the author. */
  readonly committer?: Identity;
  /** The first line of the message, from what the commit changes. */
  readonly subject?: Subject;
  /** Lines after the message. */
  readonly trailers?: readonly Trailer[];
  /** The clock that dates a commit, in milliseconds. */
  readonly clock?: () => number;
};

Who a commit is by and what it says: set by the program, never read from the configuration of a computer.

HOST_CAPABILITIESconst
const HOST_CAPABILITIES: readonly ["read", "write", "list", "stat", "delete", "cas", "batch", "rename", "history"]

The capabilities of the store of a branch the token may push to.

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

HOST_READ_CAPABILITIESconst
const HOST_READ_CAPABILITIES: readonly ["read", "list", "stat", "history"]

The capabilities of the store of a branch the token may only read.

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

HostFactstypeno test imports it
type HostFacts = { readonly host: "github" | "gitlab"; readonly describe: string; readonly defaultBranch: string |… (522 characters)
type HostFacts = {
  readonly host: "github" | "gitlab";
  readonly describe: string;
  readonly defaultBranch: string | undefined;
  readonly branch: string;
  /** Whether the branch exists. */
  readonly exists: boolean;
  /** The commit at its tip when it was opened. */
  readonly tip: string | undefined;
  /** Whether the host protects the branch. */
  readonly protected: boolean;
  /** Whether the token may push, as far as the host says: `unknown` where it does not. */
  readonly canPush: boolean | "unknown";
};

What the host said of the repository and the branch when the store was opened.

HostReadStoretypeno test imports it
type HostReadStore = Store<(typeof HOST_READ_CAPABILITIES)[number]>;

The type of the store of a branch that may only be read.

HostReftypeno test imports it
type HostRef = { readonly branch: string; readonly facts: HostFacts; /** The commit at the tip of the branch now, … (481 characters)
type HostRef = {
  readonly branch: string;
  readonly facts: HostFacts;
  /** The commit at the tip of the branch now, or nothing where there is none. */
  tip(): Promise<Result<string | undefined, Problem>>;
  /** The blob, mode and newest commit of a file. */
  info(path: Path): Promise<Result<ObjectInfo, Problem>>;
  /** The commits that changed a file, newest first, with who made them. */
  log(path: Path, limit?: number): Promise<Result<readonly LogEntry[], Problem>>;
};

The parts of a store of a branch that do not depend on whether it may be written.

HostStoretypeno test imports it
type HostStore = Store<(typeof HOST_CAPABILITIES)[number]>;

The type of the store of a branch that may be pushed to.

HostStoreOptionstypeno test imports it
type HostStoreOptions = { readonly api: HostApi; readonly place: Place; readonly branch: string; /** The branch … (988 characters)
type HostStoreOptions = {
  readonly api: HostApi;
  readonly place: Place;
  readonly branch: string;
  /** The branch a branch that does not exist is started from: without it, a branch that does not exist is read as empty and is not written. */
  readonly createFrom?: string;
  /** The folder of the branch the store is of (the top where none). */
  readonly prefix?: Prefix;
  readonly commit: CommitOptions;
  /** The largest object, in bytes (25 MiB where none). */
  readonly maxObjectBytes?: number;
  /** Refuse a path another file system could not hold (the default). */
  readonly portable?: boolean;
  /** How many times to read a branch that moved and try again (8 where none). */
  readonly attempts?: number;
  /** How many blobs a listing or a history asks about at once (8 where none). */
  readonly listConcurrency?: number;
  /** Take every sentence through this before it leaves the store: the redactor of the token. */
  readonly redact?: (text: string) => string;
};

What the store of a branch is made with.

LogEntrytypeno test imports it
type LogEntry = LogItem & {
  /** The revision the file had after it, or nothing where it removed the file. */
  readonly rev: Revision | undefined;
};

One commit that changed a file.

ObjectInfotypeno test imports it
type ObjectInfo = {
  readonly path: Path;
  /** The name of the blob in Git. */
  readonly blob: string;
  /** The mode of the file in Git: `100644` or `100755`. */
  readonly mode: string;
  readonly size: number;
  readonly rev: Revision;
  /** The newest commit that changed the file. */
  readonly commit: string | undefined;
};

What the host knows of a file beyond what a store says.

OpenedHosttypeno test imports it
type OpenedHost =
  | (HostRef & { readonly mode: "writable"; readonly store: HostStore })
  | (HostRef & { readonly mode: "read-only"; readonly store: HostReadStore });

A store of a branch that may be pushed to, and what the host adds.

openHostStorefunctionno test imports it
function openHostStore(options: HostStoreOptions): Promise<Result<OpenedHost, string>>

The store of a branch on a host, or why there is none.

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