IF Commons GitHub

pin

Written to: 5 requirements: 5 proved, 0 partly, 0 failing, 0 with no test recorded. 0005-native-pinned-pin FR-001, 0005-native-pinned-pin FR-002, 0005-native-pinned-pin FR-003, 0005-native-pinned-pin FR-004, 0005-native-pinned-pin FR-005

The pin tool: from the addresses a publisher gives for a version of a program, it fetches each artifact, takes its SHA-256 itself, checks it against the checksum the publisher publishes where the request names one, proves the artifact unpacks safely with the program where it is said to be, and writes a proposal for a person to review. It writes no pin: a pin is written in the packaging ontology by its owner, and nothing a tool proposed becomes one unreviewed.

import { readPinRequest } from "./pin.ts";
readPinRequest("{}").kind; // "err"

Source: commons/archon-dialect-native-pinned/src/pin.ts

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

ChecksumSourcetypeno test imports it
type ChecksumSource = { readonly url: string; readonly name?: string };

Where a publisher gives the checksum of an artifact: the address of a file, and the name the artifact has in it where the file lists several.

PlatformRequesttypeno test imports it
type PlatformRequest = { readonly downloadUrl: string; readonly archiveFormat: "zip" | "tar" | "file"; readonly binPath: string; readonly checksum?: ChecksumSource };

What is asked of one platform.

PinRequesttype
type PinRequest = { readonly name: string; readonly version: string; readonly program: string; readonly platforms: Readonly<Record<string, PlatformRequest>> };

What is asked: a program at a version, and its artifact on each platform.

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

PublisherChecktypeno test imports it
type PublisherCheck = "verified" | "mismatch" | "absent" | "unreadable";

How the checksum the publisher gives compares with the one taken: verified where equal, mismatch where not, absent where no source was named, unreadable where the file or the line could not be read.

PlatformProposaltypeno test imports it
type PlatformProposal = { readonly platform: string; readonly downloadUrl: string; readonly archiveFormat: "zip" |… (637 characters)
type PlatformProposal = {
  readonly platform: string;
  readonly downloadUrl: string;
  readonly archiveFormat: "zip" | "tar" | "file";
  readonly binPath: string;
  /** The SHA-256 of the bytes this tool fetched, or nothing where none could be fetched. */
  readonly sha256: string | null;
  readonly bytes: number;
  readonly publisher: PublisherCheck;
  readonly publisherSays: string | null;
  /** Whether the artifact unpacked safely with the program where it is said to be, or why not. */
  readonly program: "found" | string;
  /** Everything a reviewer should know before taking it. */
  readonly concerns: readonly string[];
};

What was found of one platform.

PinProposaltypeno test imports it
type PinProposal = { readonly format: "native-pinned-pin-proposal/1"; readonly name: string; readonly version: string; readonly program: string; readonly ready: boolean; readonly platforms: readonly PlatformProposal[] };

A proposal: ready for review only where every platform is verified by the publisher and has its program.

FetchBytestypeno test imports it
type FetchBytes = (url: string) => Promise<Result<Uint8Array, string>>;

Fetches the bytes at an address, or says why not.

osOfPlatformfunctionno test imports it
function osOfPlatform(platform: string): Os

The platform's system, from its name (windows-x64, macos-arm64, linux-x64).

readPinRequestfunction
function readPinRequest(text: string): Result<PinRequest, string>

A request from its text, or why it is not one: https addresses only, with no credentials, and a name, a version and a program of the usual form.

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

checksumFromfunction
function checksumFrom(text: string, name: string | undefined): string | undefined

The checksum a publisher's file gives for an artifact: the line that names it (<hex> <name> or <hex> *<name>), or the one hash a file of one hash holds.

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

proposePinfunction
function proposePin(req: PinRequest, get: FetchBytes): Promise<PinProposal>

The proposal for a request: every platform fetched, hashed, checked against the publisher and unpacked; the platforms in the order of their names.

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

proposalTextfunction
function proposalText(p: PinProposal): string

The text of a proposal: JSON in a fixed order, with the note that it is a proposal and no pin.

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

fetchBytesfunction
function fetchBytes(retries: Retries): FetchBytes

The real fetch: the bytes at an address, through the retries of the net library, held in a temporary folder that is removed.

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

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