@hyperfrontend/server/manifest

manifest

Writes, reads and checks hf-release.json, the release manifest: an index of every file of one built artifact by path, size and SHA-256, under the artifact's name and version.

A name and a version can be built twice into different bytes, so the SHA-256 of the manifest file is what identifies the content of a release. This entry reads the disk and hashes with node:crypto, so it runs on Node.js only.

import { writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { RELEASE_MANIFEST_FILENAME, createReleaseManifest, serializeReleaseManifest } from '@hyperfrontend/server/manifest'

const root = 'dist/shell'
const manifest = createReleaseManifest({
  root,
  name: '@acme/clock-shell',
  version: '1.4.0',
})

writeFileSync(join(root, RELEASE_MANIFEST_FILENAME), serializeReleaseManifest(manifest))

Usage

createReleaseManifest indexes every regular file below the root, dotfiles included, and leaves out the manifest file at the root, since a manifest never lists itself. It throws when the directory holds a symbolic link or anything else that is neither a regular file nor a directory, naming each one, the manifest file included, and when it holds no file at all. What it returns has passed the validator.

To check a directory against its manifest, parse the file and verify the directory:

import { readFileSync } from 'node:fs'
import { join } from 'node:path'
import { RELEASE_MANIFEST_FILENAME, parseReleaseManifest, releaseManifestDigest, verifyRelease } from '@hyperfrontend/server/manifest'

const root = 'node_modules/@acme/clock-shell'
const source = join(root, RELEASE_MANIFEST_FILENAME)
const bytes = readFileSync(source)

const digest = releaseManifestDigest(bytes)
const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)
const issues = verifyRelease(root, parseReleaseManifest(text, source))
// [] when the directory holds exactly the listed bytes and nothing else

Decode the file strictly, as above: a decoder that replaces a malformed byte or drops a byte order mark gives one text for several byte sequences, and the digest is of the bytes.

A manifest is not a signature. Whoever can replace a file of the directory can replace the manifest beside it, so an empty result says only that the directory agrees with the manifest it carries. To pin a release, compare the digest with one obtained from somewhere you trust: verifyRelease does not check it.

Two parts of the workspace rely on the file. hf build in @hyperfrontend/features writes one into every shell it builds, and lists it in the package's files so it is published with them. runService reads the one beside a built service's main before the service starts: it requires the canonical form, verifies the directory, refuses to boot on any issue, and prints the digest in its started line.

The three file-system operations are replaceable through ReleaseFileSystem, which is how a spec runs either function over a directory that exists only in memory. A replacement for its list answers one ReleaseEntry for each entry below the root that is no directory: the path below the root, written with the separators of the platform, and whether a regular file is there.

Format

{
  "schema": 1,
  "name": "@acme/clock-shell",
  "version": "1.4.0",
  "files": [
    {
      "path": "index.mjs",
      "size": 3,
      "sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
    }
  ]
}
MemberRule
schemaThe number 1. A reader that meets any other value reports that alone, because nothing else can be judged under unknown rules
nameThe artifact's own name, for a shell its package name: non-empty text with no whitespace, control character or U+FFFD
versionA semantic version, 2.0.0 grammar, with no leading v
filesAt least one entry, in ascending order of path compared code point by code point, so no path repeats
files[].pathRelative to the manifest's directory and separated by /, with no empty, . or .. segment, backslash, control character or U+FFFD
files[].sizeThe length in bytes, a whole number from 0 to 9007199254740991
files[].sha256The SHA-256 of the bytes, as 64 lowercase hexadecimal characters

The member sets are exact: a manifest or a file entry that holds any other member is refused. Paths are compared as written, with no case folding and no Unicode normalisation. The path hf-release.json at the root is reserved and never listed. U+FFFD is what a lossy decoder leaves of a malformed byte, so a file whose name on disk is not valid UTF-8 cannot be listed: indexing a directory that holds one fails, and verification reports it as unlisted.

Each file is read whole to be hashed, so a release cannot hold a file of 2 GiB or more, whatever size an entry could state: indexing and verifying such a file both throw.

The file has one canonical form: UTF-8 with no byte order mark, holding exactly what JSON.stringify(manifest, null, 2) writes with the members in the order above, closed by one line feed. serializeReleaseManifest writes it and parseReleaseManifest refuses any other spelling of the same content, such as other spacing, another member order, a repeated key or 3.0 for 3. One content therefore has one byte sequence, and one digest.

Problems

checkReleaseManifest returns every problem of a value at once, each with a stable code, the place it was found and a full sentence. validateReleaseManifest and parseReleaseManifest throw them as one error: the path of the source file, then a line per problem.

No message repeats a value or a key of the file, since both are text the author of an untrusted file chose. A member the schema does not define is reported by the object that holds it, once, however many such members there are.

CodeReported when
manifest-not-jsonThe text is not JSON; reported alone, by parseReleaseManifest only
manifest-not-objectThe value is no object; reported alone
schema-missingThe schema member is absent; reported alone
schema-unsupportedThe schema number is anything but 1; reported alone
member-unknownThe manifest or a file entry holds a member schema 1 does not define
name-invalidThe name breaks its rule or is absent
version-invalidThe version breaks its rule or is absent
files-not-arrayThe file list is no array or is absent
files-emptyThe file list is empty
file-not-objectAn entry of the file list is no object
file-path-invalidA path breaks its rule or is absent
file-path-reservedA path names the manifest itself
file-path-orderA path does not sort after the well-formed path before it
file-size-invalidA size breaks its rule or is absent
file-sha256-invalidA digest breaks its rule or is absent
manifest-not-canonicalThe content is sound and the text is not its canonical form; by parsing only

After a malformed path the order comparison starts again, so one bad path is reported once and not again for the entry that follows it.

Verification

verifyRelease has no lenient mode. It reports a manifest file at the root that is no regular file, checks each listed file in manifest order and reports it at most once, then reports every other entry below the root, in code point order.

CodeReported when
manifest-not-fileThe entry hf-release.json at the root is a symbolic link or anything else that is no regular file
file-missingNo regular file is at a listed path: nothing, a directory, or a symbolic link, which is not followed
file-size-mismatchThe file's size differs from the listed one; the file is not read
file-sha256-mismatchThe size agrees and the bytes hash to another digest
file-unlistedAn entry below the root is not listed; the manifest file at the root is the one entry that is not counted

The message of an unlisted entry opens with its path as it is when a manifest could list that path, and otherwise with the path as a quoted string in which every control character is escaped, so a name from disk never starts a line of its own. The path member holds the name unchanged.

A failure to read the disk is thrown, never turned into a verdict, and so is a manifest that does not pass the validator, before the disk is touched. A symbolic link to a directory is an entry of its own and is reported as unlisted, whatever lies behind it. A directory that holds nothing is not an entry, so an empty directory beside the listed files changes no result.

API Reference§

ƒ Functions

§function

checkReleaseManifest(value: unknown): unknown

Collects every problem of an unknown value as a ReleaseManifest, where validateReleaseManifest throws them. A value that is no object, a missing schema and a schema other than 1 are each reported alone, because nothing else can be judged under unknown rules. Otherwise every problem is reported, in the order the schema lists the members. No message repeats a value or a key of the document.
Parameters
NameTypeDescription
§value
unknownThe parsed content of a manifest file.
Returns
unknown
The problems, each with a stable code, a path and a full sentence; empty when the manifest is sound.
Example

Listing what a tool should report about a manifest

checkReleaseManifest({ schema: 1, name: 'clock-shell', version: 'v1.0.0', files: [] }).map((issue) => issue.message)
// => ['version must be a semantic version such as 1.2.3, with no leading "v".', 'files must list at least one file.']
§function

createReleaseManifest(input: CreateReleaseManifestInput, fileSystem?: ReleaseFileSystem): ReleaseManifest

Indexes a directory as a release: every regular file below it, dotfiles included, with its size and SHA-256.
The manifest file at the root is left out, since a manifest never lists itself. Each file is read once and whole, so a file of 2 GiB or more cannot be indexed, and its size is the length of the bytes read. The result has passed validateReleaseManifest, so it is ready for serializeReleaseManifest.
Parameters
NameTypeDescription
§input
CreateReleaseManifestInputThe directory to index and the identity to stamp on the manifest.
§fileSystem?
ReleaseFileSystemReplacements for the listing and the read; the disk when left out.
Returns
ReleaseManifest
The manifest, its files in ascending code point order of their paths.
Example

Writing the manifest of a built package

import { writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { RELEASE_MANIFEST_FILENAME, createReleaseManifest, serializeReleaseManifest } from '@hyperfrontend/server/manifest'

const manifest = createReleaseManifest({ root: 'dist/shell', name: '@acme/clock-shell', version: '1.4.0' })
writeFileSync(join('dist/shell', RELEASE_MANIFEST_FILENAME), serializeReleaseManifest(manifest))
§function

parseReleaseManifest(text: string, sourcePath: string): ReleaseManifest

Parses the text of an hf-release.json file into a validated ReleaseManifest. A file is valid only in canonical form, so one content has one byte sequence: text that parses to a sound manifest but differs from serializeReleaseManifest of that manifest is refused. That covers other spacing, another member order, a repeated key and another spelling of a number.
Parameters
NameTypeDescription
§text
stringThe content of the file, decoded as UTF-8 by a decoder that refuses a malformed sequence and keeps a byte order mark, so that no two byte sequences give one text.
§sourcePath
stringThe file the text came from, used to open the error message.
Returns
ReleaseManifest
The validated content of the file.
Example

Reading a manifest from disk

import { readFileSync } from 'node:fs'

const strict = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
const manifest = parseReleaseManifest(strict.decode(readFileSync('shell/hf-release.json')), 'shell/hf-release.json')
§function

releaseManifestDigest(serialized: string | Uint8Array<ArrayBufferLike>): string

Computes the digest that identifies a release manifest: the SHA-256 of the bytes of its file.
A manifest file is valid only in canonical form, so the digest of a file equals the digest of the serialisation of its content, and one manifest content has one digest. Name and version do not identify the bytes of an artifact; this digest does.
Parameters
NameTypeDescription
§serialized
string | Uint8Array<ArrayBufferLike>The bytes of an hf-release.json file, or its text, which is hashed as UTF-8.
Returns
string
The digest as 64 lowercase hexadecimal characters.
Example

Pinning a release by the digest of its manifest

import { createReleaseManifest, releaseManifestDigest, serializeReleaseManifest } from '@hyperfrontend/server/manifest'

const manifest = createReleaseManifest({ root: 'dist/shell', name: '@acme/clock-shell', version: '1.4.0' })
const digest = releaseManifestDigest(serializeReleaseManifest(manifest))
§function

serializeReleaseManifest(manifest: ReleaseManifest): string

Writes a manifest in its one canonical form: two-space JSON with the members in schema order, closed by one line feed. The UTF-8 encoding of the result is what hf-release.json holds. A member the schema does not define is left out.
Parameters
NameTypeDescription
§manifest
ReleaseManifestThe manifest to write.
Returns
string
The text of the manifest file.
Example

Writing the text of a manifest file

const files = [{ path: 'package.json', size: 505, sha256: 'c21e68ff1da3dac9ce83d330899a9513b1c8f52670bd880af3c00d23877a5889' }]
serializeReleaseManifest({ schema: 1, name: 'clock-shell', version: '0.3.0', files })
// => '{\n  "schema": 1,\n  "name": "clock-shell",\n ... }\n'
§function

validateReleaseManifest(value: unknown, sourcePath: string): ReleaseManifest

Validates an unknown value as a ReleaseManifest.
Parameters
NameTypeDescription
§value
unknownThe parsed content of a manifest file.
§sourcePath
stringThe file the content came from, used to open the error message.
Returns
ReleaseManifest
The same value, typed as a manifest.
Example

Validating a manifest built in memory

const files = [{ path: 'package.json', size: 505, sha256: 'c21e68ff1da3dac9ce83d330899a9513b1c8f52670bd880af3c00d23877a5889' }]
validateReleaseManifest({ schema: 1, name: 'clock-shell', version: '0.3.0', files }, 'shell/hf-release.json')
§function

verifyRelease(root: string, manifest: ReleaseManifest, fileSystem?: ReleaseFileSystem): unknown

Compares a directory with a release manifest, exactly: an empty result means the directory holds the listed bytes and nothing else.
A manifest file at the root that is no regular file is reported first. Each listed file is then checked in manifest order, and reported at most once: as missing when no regular file is at its path, by size without being read, or by its SHA-256. A symbolic link at a listed path is not followed: it is a missing file. Every other entry below the root, the manifest file at the root excepted, is then reported as unlisted, in code point order; a symbolic link to a directory is such an entry, whatever lies behind it. A name that is not valid UTF-8 is never a listed one. A file whose size matches is read whole, so a release cannot hold a file of 2 GiB or more.
The digest of the manifest itself is not checked: a caller that pins a release compares releaseManifestDigest of the file with the digest it trusts before relying on this result.
Parameters
NameTypeDescription
§root
stringThe directory the manifest describes.
§manifest
ReleaseManifestThe manifest to hold the directory to.
§fileSystem?
ReleaseFileSystemReplacements for the listing, the read and the size lookup; the disk when left out.
Returns
unknown
The differences found; empty when there are none.
Example

Verifying an installed package against its manifest

import { readFileSync } from 'node:fs'
import { join } from 'node:path'
import { RELEASE_MANIFEST_FILENAME, parseReleaseManifest, verifyRelease } from '@hyperfrontend/server/manifest'

const root = 'node_modules/@acme/clock-shell'
const source = join(root, RELEASE_MANIFEST_FILENAME)
const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(readFileSync(source))
const issues = verifyRelease(root, parseReleaseManifest(text, source))
// => [] when the package holds exactly the listed bytes

◈ Interfaces

§interface

CreateReleaseManifestInput

What a release manifest is made from.
Properties
§readonly root:stringThe directory to index, which is the directory the manifest file belongs in.
§readonly name:stringThe artifact's own name; for a shell, its package name.
§readonly version:stringThe artifact's version, canonical semver 2.0.0, no leading "v".
§interface

ReleaseEntry

One entry found below the root of a release.
Properties
§readonly path:stringPath relative to the root, with the separators of the platform.
§readonly kind:"file" | "other"file for a regular file; other for anything else that is no directory, a symbolic link included.
§interface

ReleaseFile

One file of a release.
Properties
§readonly path:stringPath relative to the manifest's directory, "/" separated.
§readonly size:numberLength in bytes.
§readonly sha256:stringSHA-256 of the bytes: 64 lowercase hexadecimal characters.
§interface

ReleaseFileSystem

The file system a release is read through. A function left out is the one that reads the disk, so a spec replaces only what it observes.
Properties
§readonly list?:(root: string) => unknownLists every entry below a root that is no directory, descending into directories and following no symbolic link.
§readonly read?:(path: string) => Uint8ArrayReads the bytes of the file at a path, which is the root joined with an entry's path by the platform's separator.
§readonly size?:(path: string) => numberAnswers the size in bytes of the regular file at such a path, following no symbolic link, or null when no regular file is there.
§interface

ReleaseManifest

Schema 1 of hf-release.json: an index of the bytes of one artifact.
Properties
§readonly schema:1The number of the schema the manifest is written in.
§readonly name:stringThe artifact's own name; for a shell, its package name.
§readonly version:stringThe artifact's version, canonical semver 2.0.0, no leading "v".
§readonly files:unknownEvery regular file under the manifest's directory except the manifest.
§interface

ReleaseManifestIssue

One problem found in a release manifest, located and worded without repeating any value or key of the file.
Properties
§readonly code:ReleaseManifestIssueCodeThe kind of problem.
§readonly path:stringWhere the problem sits, such as files[2].path; empty when the manifest as a whole is at fault.
§readonly message:stringThe whole sentence a tool prints, which names the place itself.
§interface

ReleaseVerificationIssue

One difference between a directory and the manifest that describes it.
Properties
§readonly code:"manifest-not-file" | "file-missing" | "file-size-mismatch" | "file-sha256-mismatch" | "file-unlisted"The kind of difference, stable across releases so a tool can branch on it.
§readonly path:stringThe path of the file below the root, "/" separated, as the disk gave it: unlike the message, it is not quoted.
§readonly message:stringThe whole sentence a tool prints, which opens with the path, quoted when it is one no manifest can list.

◆ Types

§type

ReleaseManifestIssueCode

What kind of problem a ReleaseManifestIssue reports, stable across releases so a tool can branch on it.
type ReleaseManifestIssueCode = "manifest-not-json" | "manifest-not-object" | "schema-missing" | "schema-unsupported" | "member-unknown" | "name-invalid" | "version-invalid" | "files-not-array" | "files-empty" | "file-not-object" | "file-path-invalid" | "file-path-reserved" | "file-path-order" | "file-size-invalid" | "file-sha256-invalid" | "manifest-not-canonical"

● Variables

§type

RELEASE_MANIFEST_FILENAME

File name of a release manifest, at the root of the artifact it describes.