Cherry.Upgrade (cherry v0.1.0-rc.3)

Copy Markdown View Source

Self-update for the standalone binary (ADR 0007), rustup/deno style: resolve a release from the GitHub Releases API, download this platform's asset, verify it against the release's SHA256SUMS, and swap the running executable in place.

Only the Burrito binary can swap itself — it knows its own path via __BURRITO_BIN_PATH. Everything up to the swap (the check/1 plan) works anywhere, so mix users can still ask "am I current?".

Options

  • :version — a tag like "v0.1.0-rc.1"; defaults to the latest stable release (releases/latest never returns prereleases).
  • :api_base — GitHub API base URL, for tests and mirrors.

  • :fetch — url -> {:ok, body} | {:error, reason} fetcher; defaults to Cherry.Upgrade.HTTP.fetch/1.

  • :bin_path — the executable to replace; defaults to __BURRITO_BIN_PATH (set by the Burrito wrapper).

Summary

Types

failure()

Why a check or upgrade could not proceed.

option()

Functions

asset_name()

The release asset this platform installs (cherry-linux-x86_64, …).

asset_name(arg, arch)

Pure mapping from OS/arch to the release asset name.

check(opts \\ [])

Resolves the target release and says whether an upgrade is due.

run(opts \\ [])

Runs the full upgrade: plan, download, verify, swap.

Types

failure()

@type failure() ::
  :not_binary
  | :no_stable_release
  | {:release_not_found, String.t()}
  | {:asset_missing, String.t(), String.t()}
  | {:checksum_missing, String.t()}
  | {:checksum_mismatch, String.t()}
  | {:http, String.t(), term()}

Why a check or upgrade could not proceed.

option()

@type option() ::
  {:version, String.t() | nil}
  | {:api_base, String.t()}
  | {:fetch, (String.t() -> {:ok, binary()} | {:error, term()})}
  | {:bin_path, Path.t() | nil}

Functions

asset_name()

@spec asset_name() :: String.t()

The release asset this platform installs (cherry-linux-x86_64, …).

asset_name(arg, arch)

@spec asset_name(
  {:win32 | :unix, atom()},
  String.t()
) :: String.t()

Pure mapping from OS/arch to the release asset name.

check(opts \\ [])

@spec check([option()]) :: {:ok, Cherry.Upgrade.Plan.t()} | {:error, failure()}

Resolves the target release and says whether an upgrade is due.

run(opts \\ [])

@spec run([option()]) ::
  {:ok,
   %{
     plan: Cherry.Upgrade.Plan.t(),
     swapped?: boolean(),
     retired: Path.t() | nil,
     path: Path.t()
   }}
  | {:error, failure()}

Runs the full upgrade: plan, download, verify, swap.

Returns the plan plus :swapped? (false when already up to date) and :retired — the path of the previous executable when it could not be deleted (Windows keeps the running image locked; the leftover is harmless and reused by the next upgrade).