nish/release

What the newest release of a project on GitHub is, whether it is newer than the one running, and a small cache so a program asks at most once a day.

import {
  ReleaseCache,
  ReleaseVersion,
  releaseBaseAllowed,
  releaseCacheFresh,
  releaseCacheParse,
  releaseCacheRead,
  releaseCacheWrite,
  releaseCheckCached,
  releaseCompare,
  releaseFetchInstaller,
  releaseFileTrusted,
  releaseIsNewer,
  releaseLatest,
  releaseParseVersion,
  releaseTagFromLocation,
  releaseValidVersion,
} from "nish/release";
import { releaseCheckCached, releaseLatest } from "nish/release"

const latest: string | null = releaseLatest("https://github.com/owner/repo", 2000)
const newer: string | null = releaseCheckCached(
  "https://github.com/owner/repo", "1.2.0", "/home/me/.cache/app/latest", 86400000, 2000)
  • releaseValidVersion(v) — whether v is a version that may go in a URL: it starts with a digit and holds only letters, digits, ., - and +, with no ... The same rule as install.sh's nish_valid_version.
  • releaseParseVersion(v) and releaseCompare(a, b) — semantic versions, major.minor.patch[-pre][+build]. A prerelease sorts below its release and build metadata is ignored.
  • releaseIsNewer(candidate, current) — true only when both parse and the candidate is strictly newer, so a version that does not parse is never newer and nothing here ever proposes a downgrade.
  • releaseTagFromLocation(base, location) — the version a /releases/latest redirect names, or null for anything that is not exactly <base>/releases/tag/v<version>.
  • releaseLatest(base, timeoutMs) — asks <base>/releases/latest once, without following the redirect, and answers its version or null. Every failure is null: a server that is down, slow, refuses, or answers anything but a redirect to a release tag.
  • releaseCacheRead, releaseCacheWrite and releaseCheckCached — the answer kept in a file the program names, believed only when it is a regular file this user owns that no one else can write, and only for maxAgeMs (a check dated in the future counts as stale).
  • releaseFetchInstaller(rawBase, version, path, timeoutMs) — the install.sh of one release tag, written to a file for the caller to run, never piped into a shell.

Nothing here runs under a wasm32 build: it reaches the network and reads file owners. The record of what it defends against is docs/security/release.md.

Functions

releaseBaseAllowed

Whether base is a URL this module will ask: https://, or http:// only to this machine (127.0.0.1, localhost or [::1]), which is what a test server listens on.

const releaseBaseAllowed: (base: string) => boolean
basestringrequired

The URL.

returnsboolean

True when the URL may be fetched.

releaseCacheFresh

Whether a cache checked at checkedMs still answers at nowMs: younger than maxAgeMs, and not dated in the future, which a clock set back or a planted file would give.

const releaseCacheFresh: (
  cache: ReleaseCache,
  nowMs: i64,
  maxAgeMs: i64,
) => boolean
cacheReleaseCacherequired

The cache.

nowMsi64required

The time now, in milliseconds since 1970.

maxAgeMsi64required

How long an answer stays fresh.

returnsboolean

True when the cache need not be refreshed.

releaseCacheParse

The cache's text as a ReleaseCache, or null when it is not exactly the two lines checked <ms> and latest <version> (the version empty or valid), with at most a final newline after them.

const releaseCacheParse: (
  text: string,
) => ReleaseCache | null
textstringrequired

The file's contents.

returnsReleaseCache | null

The parsed cache, or null.

releaseCacheRead

The cache at path, or null when there is none, it cannot be believed (see releaseFileTrusted; its directory, too, must be a directory this user owns that no one else can write, so nobody else can swap the file between the check and the read) or it does not parse. Its format is two lines, checked <ms> and latest <version>, the version empty when the check found none.

const releaseCacheRead: (
  path: string,
) => ReleaseCache | null
pathstringrequired

The cache file.

returnsReleaseCache | null

What the cache holds, or null.

releaseCacheWrite

Writes the cache at path: its directory is created mode 0700 when missing (its parent must exist), the text goes to a new temporary file beside it of mode 0600, and that is renamed over path, so a reader sees the old cache or the new one and a link planted at path is replaced, never followed.

const releaseCacheWrite: (
  path: string,
  latest: string,
  nowMs: i64,
) => boolean
pathstringrequired

The cache file.

lateststringrequired

The version found, or "" for none.

nowMsi64required

When the check ran, in milliseconds since 1970.

returnsboolean

True when the cache was written.

releaseCheckCached

The newest release when it is newer than current, from the cache at cachePath while it is fresh and believed, else from releaseLatest, whose answer (or its failure, as "") is written back so the next call within maxAgeMs asks nothing.

const releaseCheckCached: (
  base: string,
  current: string,
  cachePath: string,
  maxAgeMs: i64,
  timeoutMs: i32,
) => string | null
basestringrequired

The repository URL, as releaseLatest takes it.

currentstringrequired

The version running now.

cachePathstringrequired

The cache file; its directory's parent must exist.

maxAgeMsi64required

How long an answer stays fresh, e.g. 86400000 for a day.

timeoutMsi32required

The most milliseconds a check may take.

returnsstring | null

The newer version, or null when there is none or none is known.

releaseCompare

Two versions in semantic-version order: the numbers, then the prerelease, where a prerelease sorts below its release; build metadata is ignored. A version that does not parse sorts below every one that does, and two that do not parse compare equal.

const releaseCompare: (a: string, b: string) => i32
astringrequired

The first version, without a leading v.

bstringrequired

The second version, without a leading v.

returnsi32

-1, 0 or 1 as a is older than, the same as, or newer than b.

releaseFetchInstaller

The install.sh of release version, fetched from <rawBase>/v<version>/install.sh and written to path. It is the script of that tag, never of a branch, and it goes to a file so the caller runs it with sh <path> — nothing fetched is ever piped into a shell. path should be in a directory only this user can write.

const releaseFetchInstaller: (
  rawBase: string,
  version: string,
  path: string,
  timeoutMs: i32,
) => boolean
rawBasestringrequired

The raw-content URL, e.g. https://raw.githubusercontent.com/owner/repo: https, or http to this machine.

versionstringrequired

The release to fetch, without a v; refused unless releaseValidVersion.

pathstringrequired

Where to write the script.

timeoutMsi32required

The most milliseconds the whole request may take.

returnsboolean

True when a 200 answer was written to path.

releaseFileTrusted

Whether the file at path may be believed: a regular file (a symbolic link is not followed), owned by this process's effective user, and writable by neither its group nor every user.

const releaseFileTrusted: (path: string) => boolean
pathstringrequired

The file.

returnsboolean

True when the file may be read and believed.

releaseIsNewer

Whether candidate is strictly newer than current. Both must parse: a version that does not is never newer, and neither is the same release or an older one, so the answer never suggests a downgrade.

const releaseIsNewer: (
  candidate: string,
  current: string,
) => boolean
candidatestringrequired

The version that might be newer.

currentstringrequired

The version running now.

returnsboolean

True only when both parse and candidate is the newer.

releaseLatest

The newest release of the repository at base, read from where <base>/releases/latest redirects. The redirect is not followed and needs no token. Null when the server cannot be reached within timeoutMs, answers anything but a 3xx, or redirects anywhere but a release tag of base.

const releaseLatest: (
  base: string,
  timeoutMs: i32,
) => string | null
basestringrequired

The repository URL, e.g. https://github.com/owner/repo: https, or http to this machine.

timeoutMsi32required

The most milliseconds the whole request may take.

returnsstring | null

The newest version, without a v, or null.

releaseParseVersion

v as a semantic version, major.minor.patch with an optional -pre and +build, or null when it is not one. A leading v is not accepted; strip it first.

const releaseParseVersion: (
  v: string,
) => ReleaseVersion | null
vstringrequired

The version text.

returnsReleaseVersion | null

The parsed version, or null.

releaseTagFromLocation

The version a /releases/latest redirect names: location must be exactly <base>/releases/tag/v<version>, and the version must parse. A redirect anywhere else — another repository, a login page, the releases list when there is no release, a query or fragment — names none.

const releaseTagFromLocation: (
  base: string,
  location: string,
) => string | null
basestringrequired

The repository URL, e.g. https://github.com/owner/repo, with no trailing slash.

locationstringrequired

The redirect's Location header.

returnsstring | null

The version, without a v, or null.

releaseValidVersion

Whether v may be put in a URL as a release version: not empty, starting with a digit, holding only ASCII letters, digits, ., - and +, and never ... What it rules out is a version that reaches past the tag in a path — a /, a .., a ?, a #, a %, whitespace.

const releaseValidVersion: (v: string) => boolean
vstringrequired

The version, without a leading v.

returnsboolean

True when the version is safe to put in a release URL.

Classes

ReleaseCache

The cache's contents: when the check ran and what it found.

class ReleaseCache
Member
new ReleaseCache()
checkedMs: i64 When the check ran, in milliseconds since 1970 (Date.now()'s clock).
latest: string The version the check found, or "" when it found none.

ReleaseVersion

A parsed semantic version. pre is the prerelease after the -, empty for a release; build metadata after the + is dropped, as it never orders.

class ReleaseVersion
Member
new ReleaseVersion()
major: i64 The major number.
minor: i64 The minor number.
patch: i64 The patch number.
pre: string The prerelease identifiers, dot-separated, or "" for a release.