bsncubed/haul
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: replan auto-update as a reusable module

Browse Source 
Ben wants this shared across projects rather than living inside haul, so the
plan now describes a standalone module with its own repo.

The consequence that shapes the whole API: it can do no UI of its own.
ShippingTracker called MessageBox directly, but haul is Fyne (widgets only from
the UI thread via fyne.Do) and dial is a Bubble Tea TUI. So the module is pure
logic plus an onProgress callback, and each consumer supplies its own prompts.

Also reorders the work. dial goes first: it is pure Go, already cross-compiles,
and release 0.2.0 already has all five platform binaries and SHA256SUMS
attached — so it can adopt this immediately, whereas haul still can't build its
own release assets. dial using SHA256SUMS where ShippingTracker uses
checksums.txt is why the checksum asset name has to be configurable.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Ben Nicholson
2026-07-30 18:10:10 +10:00
parent 481b998525
commit 0d938f1f64
1 changed files with 138 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/auto-update-plan.md
+138 -100
View File
@@ -1,143 +1,181 @@
# Auto-update for haul — plan
# Auto-update — plan
Status: **planned, not started.** Blocked on four decisions (bottom of this
file). No code has been written.
Status: **planned, not started.** Blocked on decisions at the bottom of this
file. No code written.
The model is the self-updater in
Ben wants this as a **standalone, reusable Go module**, not something buried in
haul — so it can be dropped into dial, haul, and whatever comes next. This doc
lives in haul's repo because that's where the conversation started; the module
gets its own repo and its own README.
The behaviour to copy is the self-updater in
[ShippingTracker](https://gitea.apointless.space/bsncubed/ShippingTracker)
(`HelloWorld/Updater.vb`), which haul should behave like.
(`HelloWorld/Updater.vb`).
## Research already done — don't redo this
Verified 2026-07-29 against the live gitea instance:
Verified 2026-07-29/30 against the live gitea instance:
- `https://gitea.apointless.space/api/v1/repos/bsncubed/ShippingTracker/releases/latest`
returns **HTTP 200 anonymously**. No token needed.
- `.../repos/bsncubed/haul` also returns **200 anonymously**, and
`.../repos/bsncubed/haul/releases` returns `[]`. So haul's repo is public;
the 404 on `releases/latest` is simply "no releases exist yet", not a
permissions problem. The updater will work unauthenticated.
- Release JSON exposes `tag_name`, `draft`, `prerelease`, and an `assets` array
whose entries carry `name` and `browser_download_url`. ShippingTracker's
latest (`1.1.0.2`) attaches exactly two assets: `Shipping Tracker.exe` and
`checksums.txt`.
- The releases API is **readable anonymously** — both
`.../repos/bsncubed/ShippingTracker/releases/latest` and
`.../repos/bsncubed/haul` return 200 with no token. The updater needs no
credentials.
- `.../repos/bsncubed/haul/releases` returns `[]`. haul's repo is public; the
404 on `releases/latest` is just "no releases yet", not permissions.
- **dial already publishes proper releases.** Tag `0.2.0`, `draft: false`,
`prerelease: false`, with six assets: `dial-darwin-amd64`,
`dial-darwin-arm64`, `dial-linux-amd64`, `dial-linux-arm64`,
`dial-windows-amd64.exe`, and `SHA256SUMS`.
- Release JSON exposes `tag_name`, `draft`, `prerelease`, and `assets[]` with
`name` and `browser_download_url`.
- Gitea serves `go-import` meta tags
(`<meta name="go-import" content="gitea.apointless.space/bsncubed/haul git https://…">`),
so `go get gitea.apointless.space/bsncubed/<module>` resolves.
## What ShippingTracker's updater does
1. GET `/api/v1/repos/{owner}/{repo}/releases/latest`; take `tag_name`, match
assets by exact filename.
2. Parse the tag into a version — tolerates a leading `v`, pads missing
components with `0` (an unset `System.Version` component is `-1`, which
sorts wrong).
components with `0`.
3. **Silent vs. loud.** A startup check swallows every failure (offline, DNS,
timeout, non-200, malformed JSON) with no UI at all. A user-clicked check
reports "you're up to date" and surfaces errors.
4. Prompts with current vs. available before doing anything.
5. **Pre-flights write permission** next to the executable, so a read-only
install directory fails early rather than half-applying an update.
6. Streams the download to `<exe>.new` behind a small progress window.
7. Verifies SHA256 against a `checksums.txt` asset in `sha256sum` format
(`<hash> <filename>`). If that asset is absent the update still installs,
unverified.
6. Streams the download to `<exe>.new` behind a progress window.
7. Verifies SHA256 against a checksum asset in `sha256sum` format
(`<hash> <filename>`). Absent checksum asset → installs unverified.
8. **Swaps by rename**: running exe → `.old`, `.new` → exe, rolling back if the
second rename fails. `.old` is deleted on the next launch.
9. On any failure, offers to open the releases page in a browser instead.
## Ports over unchanged
The API shape, the silent/loud split, tag parsing, checksum verification, the
rename-swap with `.old` cleanup, and the manual-download fallback.
second rename fails. `.old` deleted on next launch.
9. On any failure, offers to open the releases page in a browser.
The rename dance exists because Windows won't delete a *running* binary but will
rename one. Linux and macOS also allow renaming a running executable (the inode
stays live), so a single code path covers all three platforms.
stays live), so one code path covers all three.
## Has to change for haul
## The module
1. **haul has no version at all.** ShippingTracker compares against
`AssemblyVersion`; `cmd/haul` has no equivalent, which is why the Makefile
deliberately omits `-X main.version` (a `-X` against a non-existent symbol is
silently a no-op). Adding one is a prerequisite — without it every check
reports "up to date".
2. **One asset becomes many.** ShippingTracker is Windows-only, so its
`AssetName` is a single constant. haul must select an asset by
`runtime.GOOS`/`runtime.GOARCH` (`haul-linux-amd64`, `haul-darwin-arm64`,
`haul-windows-amd64.exe`).
3. **The executable bit.** On Unix the downloaded file needs `chmod 0755`.
Nothing in the VB version corresponds to this.
4. **Fyne threading.** `internal/ui` only touches widgets from the UI thread and
returns from I/O via `fyne.Do`. The updater must follow the same shape as
`session.transfer` and `pane.navigateKeepMarks`.
Its own repo — something like `gitea.apointless.space/bsncubed/selfupdate`
(name is an open decision). Separate module, separately versioned, imported by
each project.
## Blockers — read before starting
### The single most important constraint: no UI
**The release assets can't be built yet.** This gates everything. haul is cgo,
so `make dist` produces the native binary only; there is currently no way to
produce macOS or Windows assets from the Linux box. An updater with nothing to
download is pointless, so **the release pipeline must come first**
(`fyne-cross` over Docker, which is installed, or real machines).
ShippingTracker's updater calls `MessageBox.Show` directly. **A reusable module
cannot do that**, because the three consumers could not be more different:
**Linux binaries don't travel.** haul links dynamically against `libGL`,
`libX11`, `libc` and ten others. A binary built on Ubuntu 24.04 may not start on
a different or older distro — it would download, swap itself in, and then fail
to launch, which is the worst failure mode an updater has. ShippingTracker never
hit this (.NET Framework, stable Windows ABI). Options: build against the oldest
glibc worth supporting, ship Linux without auto-update, or accept it.
| Consumer | UI |
| --- | --- |
| ShippingTracker | WinForms message boxes |
| haul | Fyne GUI, and widgets may only be touched from the UI thread via `fyne.Do` |
| dial | Bubble Tea TUI, an Elm-style message loop |
**`checksums.txt` is not a signature.** It lives on the same server as the
So the module is **pure logic plus callbacks**: it decides, downloads, verifies
and swaps; the host application does every prompt, progress bar and error
dialog. That also makes it trivially testable against `httptest`.
### Sketch
```go
type Config struct {
BaseURL string // https://gitea.apointless.space
Owner, Repo string
Current Version
AssetName func(goos, goarch string) string // default: <bin>-<goos>-<goarch>[.exe]
ChecksumAsset string // "SHA256SUMS" (dial) or "checksums.txt" (ShippingTracker)
HTTPClient *http.Client
UserAgent string
AllowPrerelease bool
}
func Check(ctx, cfg) (*Release, error) // fetch, parse tag, pick this platform's asset
func (r *Release) Newer(v Version) bool
func Download(ctx, r, dst string, onProgress func(done, total int64)) error
func Verify(path, checksumURL, assetName string) error
func Apply(newPath string) error // rename dance, rollback, chmod 0755
func CleanupOld() error // delete <exe>.old; never errors
```
`onProgress` is the seam: haul marshals it through `fyne.Do`, dial turns it into
a Bubble Tea message, ShippingTracker-style apps call it directly.
### Configurable because it genuinely varies
- **Checksum asset name** — dial uses `SHA256SUMS`, ShippingTracker uses
`checksums.txt`. Proof this can't be a constant.
- **Asset naming** — a `func(goos, goarch)` hook, defaulting to dial's existing
`<binary>-<goos>-<goarch>[.exe]` convention, which haul should adopt too.
- **Forge** — gitea's release JSON is GitHub-shaped, so the same client covers
GitHub for free. Worth keeping the fetch behind a small interface.
### Stays with each project
Version stamping, the release pipeline, asset naming, and all UI.
## Consumers, in order
**dial first — it is not blocked.** Pure Go, cross-compiles trivially, and its
`make dist` already produces all five platform binaries and `SHA256SUMS`, which
release `0.2.0` already has attached. dial can ship auto-update as soon as the
module exists, which makes it the honest test of whether the API is actually
reusable.
**haul second, and it needs work first:**
1. **haul has no version at all.** `cmd/haul` has no `version` variable, which
is why the Makefile omits `-X main.version` (a `-X` against a non-existent
symbol is silently a no-op). Without it every check reports "up to date".
2. **haul cannot build its own release assets.** It is cgo, so `make dist`
produces the native binary only — no macOS or Windows assets exist to
download. Needs `fyne-cross` over Docker (installed) or real machines.
3. **Linux binaries don't travel.** haul links dynamically against `libGL`,
`libX11`, `libc` and ten others; a binary built on Ubuntu 24.04 may not start
on another distro. It would download, swap itself in, then fail to launch —
the worst failure mode an updater has. dial, being static, has no such
problem. Options: build against the oldest glibc worth supporting, ship Linux
without auto-update, or accept it.
## Security note
**A checksum is not a signature.** `SHA256SUMS` sits on the same server as the
binary, so it catches corruption and truncation but not a compromised gitea —
anyone who can replace one can replace the other. ShippingTracker accepts this.
Closing the gap means a minisign/ed25519 signature with the public key compiled
into haul, roughly 40 extra lines.
into each consumer, roughly 40 extra lines in the module.
## Proposed shape
## Consuming the module
New package `internal/selfupdate`, UI-free so it can be tested against a fake
HTTP server:
Because the host is self-hosted, dependent projects will likely want:
| Piece | Responsibility |
| --- | --- |
| `Check(ctx) (*Release, error)` | Fetch latest, parse tag, pick this platform's asset |
| `Release.Newer(current)` | Version comparison |
| `Download(ctx, rel, progress)` | Stream to `<exe>.new`, report progress |
| `Verify(path, checksumURL)` | SHA256 against `checksums.txt` |
| `Apply(newPath)` | Rename dance, rollback, `chmod` |
| `CleanupOld()` | Delete `<exe>.old`; never errors |
```sh
go env -w GOPRIVATE=gitea.apointless.space/*
```
Plus a thin `internal/ui/update.go` for dialogs, reusing `confirmDialog` from
`dialogs.go` and a progress dialog modelled on the existing transfer bar.
Integration points, mirroring ShippingTracker's `Form1_Load` and `Form3`:
- `CleanupOld()` and a silent check when the connect window opens
(`newConnectWindow`).
- A manual "Check for updates" button. The connect window is the natural home —
haul has no settings screen.
Release process: a `make release VERSION=x.y.z` target that builds, writes
`checksums.txt`, and prints the tag/upload steps. Tag as `1.2.0` or `v1.2.0`,
and don't mark it pre-release — `/releases/latest` skips drafts and
pre-releases.
so the module is fetched straight from gitea rather than through
`proxy.golang.org` and the checksum database. Worth confirming in practice —
the repo is public, so the proxy path may work unaided.
## Phasing
| Phase | Work |
| --- | --- |
| 0 | Version stamping — `var version` in `cmd/haul`, `-X` in the Makefile, `haul --version` |
| 1 | **Release pipeline** — cross-builds via fyne-cross, checksums, first tagged release |
| 2 | `internal/selfupdate` with tests against a fake HTTP server |
| 3 | UI wiring — startup silent check, manual button, progress and error dialogs |
| 4 | README: how updating works, and how to publish a release |
| 0 | Create the module repo; `Check`/`Newer` plus version parsing, tested against `httptest` |
| 1 | `Download`/`Verify`/`Apply`/`CleanupOld`, tested in a temp dir |
| 2 | **Adopt in dial** — the real proof of reusability, and shippable immediately |
| 3 | haul phase A: version stamping (`var version`, `-X`, `haul --version`) |
| 4 | haul phase B: release pipeline via fyne-cross, first tagged release |
| 5 | haul phase C: wire the module in — silent check on the connect window, a manual "Check for updates" button, progress and error dialogs |
| 6 | READMEs: the module's own, plus a section in each consumer |
Phases 0 and 1 are worth doing regardless — there is currently no way to ship
haul to anyone at all.
## Open decisions
## Open decisions — needed before building
1. **Auto-check on startup, or manual only?** ShippingTracker does both. Silent
startup checks mean haul contacts gitea on every launch.
2. **Which platforms get auto-update?** Suggestion: exclude Linux at first, for
the dynamic-linking reason above.
3. **Checksums only, or add signatures?**
4. **Do phase 1 first, or write the updater against ShippingTracker's existing
releases as a test fixture?**
1. **Module name and path** — `selfupdate`? `gitup`? `bsncubed/selfupdate`?
2. **Auto-check on startup, or manual only?** ShippingTracker does both. Silent
startup checks mean the app contacts gitea on every launch.
3. **Which platforms get auto-update?** Suggestion: exclude haul's Linux build
for the dynamic-linking reason above. dial is fine everywhere.
4. **Checksums only, or real signatures?**
5. **Confirm dial goes first** — it's unblocked and validates the API, whereas
haul can't produce release assets yet.