mirror of
https://github.com/anomalyco/hex.git
synced 2026-11-22 21:23:02 +01:00
* 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.
122 lines
6.5 KiB
Markdown
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`.
|