hex/docs/plans/release-service.md
Dax 8201a4ce1c
ci: read release secrets from aws secrets manager (#1606)
* ci: read release secrets from aws secrets manager

* ci: read the linux signing key from hex/release/RELEASE_SIGNING_KEY

* ci: hex's own aur and homebrew keys; the signing cert has no password

* ci: the signing certificate has no password

* ci: use the shared aur and homebrew keys

* docs: the shared homebrew deploy key is anomaly-release

* docs: the shared homebrew deploy key is anomaly-release

* site: own /hex/files, drop the r2 write credential (#1611)

* site: own /hex/files for installers, appcast, and dev notes

The site build now copies install-linux.sh, install-windows.ps1, and
packaging/macos/legacy-appcast.xml into its Worker assets, so the same
Worker serves them at /hex/files with the Content-Type and Cache-Control
the bucket objects had. The Installers and Legacy appcast workflows,
r2-put.sh, and their R2 write credential are gone.

The dev notes move to the one-commit dev-notes branch, published by
Release's dev-notes job with GITHUB_TOKEN only; the Worker proxies that
file at /hex/files/dev-notes.json (falling back to the bucket copy until
the first dev release creates the branch) and renders /hex/dev from it.

Both site Workers now bind hex-production-files, read-only in code, for
the frozen 2.3.1 feeds and artifacts, which lets hex-dev-files go. The
Site build runs the installer test and appcast check the removed
workflows ran, and the verify job compares the served bytes.

* docs: the site owns /hex/files and needs no R2 write credential

Hosting, secrets, old clients, and Linux packages describe the built
installers and appcast, the dev-notes branch, and the read-only bucket.
2026-11-09 15:18:26 -05:00

122 lines
6.5 KiB
Markdown

# Hex on the Anomaly release service
Contract between Hex's release workflow (publishing) and Hex's in-app updater
(client). The service and its rules are `anomalyco/release`
(`docs/protocol.md`, `docs/publishing.md`); this file pins Hex's names.
## Names
```ts
https://anoma.ly/release/hex/ the service (its dev stage, dev.anoma.ly/release, only tests the service)
├─ index.json download page and installers
└─ desktop/<channel>.json the manifest the app polls; channels stable, beta, dev
└─ release.targets
├─ macos-arm64 Hex.zip ditto zip, root Hex.app (updater)
├─ macos-arm64-dmg Hex.dmg notarized DMG (download page)
├─ windows-x64 hex.exe bare executable (updater)
├─ windows-x64-cli hex.com console entry point beside hex.exe (updater)
├─ windows-x64-setup HexSetup.exe Inno Setup installer (download page)
├─ windows-arm64 hex.exe
├─ windows-arm64-cli hex.com
├─ windows-arm64-setup HexSetup.exe
├─ linux-x64 hex bare executable (updater, installer, AUR)
├─ linux-x64-deb hex.deb Debian/Ubuntu package (package manager updates it)
├─ linux-x64-rpm hex.rpm Fedora/openSUSE package
├─ linux-arm64 hex
├─ linux-arm64-deb hex.deb
└─ linux-arm64-rpm hex.rpm
```
Published names carry no version or target: each file lives at
`/release/hex/files/<sha256>/<name>`, which tells them apart, and the service
serves it with `Content-Disposition: attachment; filename="<name>"`, so a
download is saved as `hex`, `Hex.dmg`, and so on. The builds and the GitHub
release mirror keep versioned names (`hex-<v>-macos-arm64.dmg`, …), which
must be unique there; `.github/release/release-service.sh` maps them.
(`HexSetup.exe`, not `Hex Setup.exe`: the service's file names allow no
spaces.)
- App `hex`, artifact `desktop`. `stable` is the public channel; every push
to `dev` publishes `0.0.0-dev-<run number>` on the `dev` channel. `beta` is
registered for later use.
- Every executable and archive is signed before upload (Developer ID +
notarization on macOS, Authenticode on Windows); the service stores bytes and
their size and SHA-256, and manifests are not signed. Linux executables
carry an ed25519 signature over their SHA-256 as the `linux-<arch>-sig`
target (`hex.sig`), which the updater and installer require.
- Versions are `X.Y.Z` on stable. The service refuses an equal or lower
version unless the current one is revoked.
## Distributions
Recorded in every release; package-manager entries gain `version` only after
that job succeeds (the `distribution` action):
| Kind | Fields | Command |
| --- | --- | --- |
| `direct` | | (updates itself) |
| `aur` | `package: hex-bin` | `yay -Syu hex-bin` |
| `brew` | `cask: anomalyco/tap/hex` | `brew upgrade --cask anomalyco/tap/hex` |
| `nix` | `attribute: github:anomalyco/hex` | `nix profile upgrade hex` |
## Direct-install receipt
The installers write `install.json`
(`{"app":"hex","artifact":"desktop","channel":"stable","method":"direct","root":"<root>"}`)
at the root of the user-owned install, and the client self-updates only when
it is present and the root is writable by this user alone:
- Linux: `~/.local/share/hex/install.json` (`install-linux.sh`;
`scripts/install-linux.sh` source builds write none and keep their
`source-build` marker).
- Windows: `%APPDATA%\hex\install.json` (`install-windows.ps1` and
the Setup.exe).
- macOS: the client decides from the bundle's location (a writable,
non-translocated `Hex.app` is direct).
`HEX_RELEASE_BASE_URL` (HTTPS only) points a build at another service origin
for local tests against a fixture service; nothing defaults to another
origin.
## Old clients (2.3.1 and earlier)
`https://anoma.ly/hex/files/{linux-update.json,windows-update.json}` stay
frozen at 2.3.1 in the `hex-production-files` bucket. `appcast.xml` is
`packaging/macos/legacy-appcast.xml`, served by the site build: one
informational item pointing at https://anoma.ly/hex (see `docs/releasing.md`).
## Client
`src/updater.rs` (all three OSes) polls `<origin>/hex/desktop/<channel>.json`
10 seconds after launch, hourly (the Dev channel every 10 minutes and when the window gains focus, at most once a minute), and on Check now, with `If-None-Match` and
`User-Agent: hex/<channel>/<version>` (the build's own channel and version,
e.g. `hex/dev/0.0.0-dev-171`, `hex/stable/2.3.1`), which the service counts as
a running install; failed checks back off but never past hourly. It
decides with the protocol's client rules (`updater/protocol.rs`, which passes
the service's `test-vectors/` copied to `tests/fixtures/release-protocol`).
Versions are never compared: Hex takes the channel's current release whenever
it is not the running build, identified on Linux and Windows by the
executable's SHA-256 (the target file itself) and on macOS by its exact
version. `required` releases skip the rollout. The checked channel is the
Update channel setting, else the channel the build was published on
(`HEX_BUILD_CHANNEL`, stamped by Release; older builds: `dev` for a dev
version, else the receipt's). A setting other than the build's channel is a
switch: Settings, the Windows tray, and the macOS menu offer "Switch to
Stable 2.3.1", and nothing downloads until the user confirms.
```ts
install method distribution channel acts on install
macOS writable Hex.app direct stable unzip beside it, codesign -R app/update-requirement.txt, swap at restart/quit
macOS read-only/translocated direct stable Download update → macos-arm64-dmg URL
Linux versions/ + receipt direct receipt's copy into versions/<v>, switch current
Linux pacman / Nix aur / nix stable show the distribution's command
Windows versions/ + receipt direct receipt's Authenticode (AUTHENTICODE_SIGNER), versions\<v>, current-version
source and test builds (never check)
anything else unknown stable Download update → notes_url
```
Target URLs are absolute-path references (`/release/hex/files/<sha256>/<name>`)
resolved against the manifest URL (RFC 3986), so they keep the manifest's
host (`anoma.ly` or `dev.anoma.ly`). Downloads resume into `<support>/updates/<sha256>/` and are
checked against `size` and `sha256` before any other use. The rollout bucket
is `<support>/update-bucket`.