Houmeres/LLeMbas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

A version somebody can read, instead of a sha nobody can

Browse Source 
Updates follow a channel now. `stable` is the newest vX.Y.Z tag; `edge` is the
branch tip, which is what this did before. Stable is the default, because a
branch tip is not a release -- following one means deploying whatever was pushed
five minutes ago, possibly mid-feature, which is right for whoever builds this
and wrong for whoever runs it. The page can now say "running 1.0.0, 1.1.0
available" rather than showing two shas and leaving somebody to guess.

Read with git plumbing and never a forge API, for three reasons in the order
they bite. It would need a token on the deployment host -- a credential that can
reach the repository, sitting on a box, to answer a read-only question about
version numbers. It would tie this to one forge, so a fork on GitHub gets
nothing. And it breaks: checked against the Gitea this is developed on, `tea
whoami` works and `tea releases list` returns a 500 from a server-side panic
about token scopes, so a page resting on that endpoint would have shipped
already broken.

Release notes still travel, inside the annotated tag object, which
`git for-each-ref` reads with no API anywhere.

Two details that are only obvious after getting them wrong. A tag with a suffix
is not a release: git's version sort puts v1.1.0-rc1 *above* v1.1.0, so
accepting one would step a stable host onto a candidate on the strength of a
hyphen. And `--sort=-v:refname` rather than a lexical sort, which puts v1.9.0
above v1.10.0 and does it silently the first time a project reaches ten of
anything -- there is a test.

What is running is `git describe --tags --always`, so it reads "1.0.0" at a tag,
"1.0.0-7-gd4f56d" seven commits past one, and a bare sha before the first
release ever exists. That last case is what `--always` is for. When it lands
exactly on a tag whose name disagrees with __version__, the page says so: a tag
cut before the version bump names a release nobody can identify afterwards, and
the check costs no subprocess because both facts are already in hand.

update.sh resolves the channel the same way and detaches at the tag rather than
resetting -- a `reset --hard <tag>` while on main would move the local branch to
it, which is a rewrite of a ref nobody asked to rewrite. A host with no tags
falls back to the branch and says so, which is every host until the release.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jaroslav Beneš
2026-08-06 20:42:03 +02:00
parent ddad585e4b
commit 5612bf2acd
9 changed files with 527 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/lembas/services/updates.py
+226 -54
View File
@@ -1,4 +1,4 @@
"""What is running here, what is available, and how to get from one to the other.
"""What is running here, what is released, and how to get from one to the other.
## Why this exists
@@ -7,8 +7,34 @@ for everybody else: an instance somebody installed from `deploy/install.sh` and
handed over has an administrator who can configure every part of it and cannot
tell whether it is three releases behind.
So this answers three questions — what is running, what is on the branch, and
what changed between — and offers a button for the fourth.
## Two channels, because a branch tip is not a release
- **stable** — the newest version tag. "Running 1.0.0, 1.1.0 available."
- **edge** — the branch tip, whatever was pushed five minutes ago.
That distinction is the whole reason this is not just a commit comparison. A
commit sha tells nobody anything, and following `main` means deploying work that
may be half finished — the right default for whoever is building it and the wrong
one for whoever is running it. Both channels are the same machinery asking one
different question: *which ref am I comparing against*.
## Git plumbing, never a forge API
Tags are read with `git`, over the transport the checkout already has. Not the
Gitea (or GitHub, or GitLab) API, for three reasons in the order they bite:
- **It needs a token on the deployment host.** A credential that can reach the
repository, sitting on a box, to answer a read-only question about version
numbers. That is a bad trade.
- **It is forge-specific.** A fork on GitHub, or a bare repository on a NAS,
would get nothing.
- **It breaks.** Checked against the Gitea this is developed on: `tea whoami`
works and `tea releases list` returns a 500 from a server-side panic about
token scopes. An update page resting on that endpoint would have shipped
broken.
Release notes still travel: an **annotated** tag carries its message in the tag
object, and `git for-each-ref` reads it with no API anywhere.
## The button cannot do the work, and that is the design
@@ -17,21 +43,18 @@ write outside its own prefix, and it should not be able to: a web application
that can restart its own service is one whose worst day is much worse.
So the button **writes a file**, and an opt-in systemd `.path` unit watching that
file runs `deploy/update.sh` as root. Three things follow, and all three are
deliberate:
file runs `deploy/update.sh` as root. Three things follow, all deliberate:
- **The request file carries nothing.** No branch, no ref, no arguments. The
helper runs the update script with the branch *it* was configured with, so an
administrator of the web UI cannot choose what gets deployed — only *that* the
configured branch gets deployed.
- **The request file carries nothing.** No ref, no channel, no arguments. The
helper runs the update script with the channel and branch *it* was configured
with, so an administrator of the web UI cannot choose what gets deployed —
only *that* the configured channel gets deployed.
- **It is opt-in.** Without the helper the page says so and shows the command,
which is the honest degradation and the same shape the SSH and search extras
already have. Installing it is a decision with a consequence worth stating:
anybody who can administer the web UI can then deploy whatever is on that
branch.
already have.
- **Nothing here runs a shell.** Every subprocess is a fixed argv with
`shell=False`, and the only variable in any of them is the branch, which comes
from the environment rather than from a request.
`shell=False`, and the only variables in any of them are the branch and the
channel, which come from the environment rather than from a request.
## On "nothing executes on this machine"
@@ -44,6 +67,7 @@ leaving somebody to notice the tension.
from __future__ import annotations
import logging
import re
import subprocess
from dataclasses import dataclass, field
from pathlib import Path
@@ -58,6 +82,17 @@ log = logging.getLogger(__name__)
# saying so is more use than waiting.
GIT_TIMEOUT = 30.0
CHANNEL_STABLE = "stable"
CHANNEL_EDGE = "edge"
CHANNELS = (CHANNEL_STABLE, CHANNEL_EDGE)
# What counts as a release tag on the stable channel. `v1.2.3` or `1.2.3`, and
# **nothing with a suffix**: `v1.1.0-rc1` sorts above `v1.1.0` under git's
# version sort, so accepting it would step a stable instance onto a release
# candidate on the strength of a hyphen. A prerelease is something somebody opts
# into by name, not something a channel drifts onto.
RELEASE_TAG = re.compile(r"^v?\d+\.\d+\.\d+$")
# The file the button writes. Inside the data directory, which is the one place
# the service account can write, and named so that finding it in a backup says
# what it was.
@@ -68,6 +103,11 @@ REQUEST_NAME = "update-requested"
# page render to answer a question that changes once.
MARKER_NAME = ".update-helper"
# `%H` sha, `%s` subject, `%cI` date, split on a unit separator rather than a
# space: a commit subject contains spaces, and every other separator anybody
# reaches for is one a subject may also contain.
FORMAT = "--format=%H\x1f%s\x1f%cI"
@dataclass(frozen=True)
class Commit:
@@ -80,17 +120,44 @@ class Commit:
return self.sha[:7]
@dataclass(frozen=True)
class Target:
"""A thing this instance could be at: a release, or a branch tip."""
ref: str = ""
# What to call it to a person. A tag name on stable, a short sha on edge --
# which is why this is stored rather than derived: the two channels answer
# "what version is this?" with different kinds of thing.
label: str = ""
sha: str = ""
subject: str = ""
notes: str = ""
@property
def short(self) -> str:
return self.sha[:7]
@dataclass(frozen=True)
class State:
"""Everything the page shows, resolved in one go."""
version: str = __version__
checkout: str = ""
channel: str = CHANNEL_STABLE
branch: str = "main"
checkout: str = ""
# What is running: `git describe`, so "1.0.0" at a tag and "1.0.0-7-gd4f56d"
# seven commits past one. A bare sha only when there is no tag anywhere.
running: str = ""
head: Commit | None = None
remote: Commit | None = None
available: Target | None = None
behind: list[Commit] = field(default_factory=list)
dirty: bool = False
# `git describe` said we are exactly at a tag whose name disagrees with
# `__version__`. Cheap to check -- no subprocess, both are already in hand --
# and it is the one thing about a release that is worth catching: a tag cut
# before the version bump names a release nobody can identify afterwards.
version_mismatch: str = ""
helper: bool = False
requested: bool = False
error: str = ""
@@ -101,16 +168,24 @@ class State:
@property
def up_to_date(self) -> bool:
return bool(self.head and self.remote and self.head.sha == self.remote.sha)
return bool(self.head and self.available and self.head.sha == self.available.sha)
@property
def no_releases(self) -> bool:
"""Stable, and nothing tagged yet. Worth its own answer: the page has to
say "nothing has been released" rather than "up to date", which would be
true of an empty repository and useless."""
return self.channel == CHANNEL_STABLE and self.available is None
def checkout_dir() -> Path | None:
"""The git checkout this is running from, or None.
`src/lembas/__init__.py` upwards twice is the repository root for an editable
install, which is what every deployment here is. A wheel installed into
`src/lembas/services/updates.py` upwards three times is the repository root
for an editable install, which is what every deployment here is. A wheel in
site-packages has no `.git` above it and answers None, which the page reads
as "this was not installed from a checkout" rather than as an error.
as "this was not installed from a checkout" rather than as an error -- and is
what a container correctly reports, since `.dockerignore` excludes `.git`.
"""
root = Path(__file__).resolve().parents[3]
return root if (root / ".git").exists() else None
@@ -144,19 +219,16 @@ def _git(args: list[str], *, cwd: Path, timeout: float = GIT_TIMEOUT) -> tuple[i
def _commit(line: str) -> Commit | None:
"""One line of `--format=%H\\x1f%s\\x1f%cI`.
Split on a unit separator rather than a space: a commit subject contains
spaces, and every other separator anybody reaches for is one a subject may
also contain.
"""
parts = line.split("\x1f")
if len(parts) < 2 or not parts[0]:
return None
return Commit(sha=parts[0], subject=parts[1], when=parts[2] if len(parts) > 2 else "")
FORMAT = "--format=%H\x1f%s\x1f%cI"
# --- Configuration ---------------------------------------------------------------
def channel_name() -> str:
wanted = (settings.update_channel or CHANNEL_STABLE).strip().lower()
return wanted if wanted in CHANNELS else CHANNEL_STABLE
def branch_name() -> str:
@@ -175,6 +247,81 @@ def pending() -> bool:
return request_path().exists()
# --- Resolving what is available ---------------------------------------------------
def release_tags(root: Path) -> list[str]:
"""Every release tag, newest first.
`--sort=-v:refname` is git's own version sort, so `v1.10.0` comes above
`v1.9.0` -- which a lexical sort gets wrong, and gets wrong silently the
first time a project reaches ten of anything.
"""
code, output = _git(["tag", "--list", "--sort=-v:refname"], cwd=root)
if code != 0:
return []
return [line.strip() for line in output.splitlines() if RELEASE_TAG.match(line.strip())]
def _notes_for(root: Path, tag: str) -> str:
"""An annotated tag's message: the release notes, travelling inside git.
Empty for a lightweight tag, which is the honest answer -- there is nothing
attached to one. `%(contents)` includes the signature block for a signed tag,
so it is cut at the PGP header rather than shown.
"""
code, output = _git(
["for-each-ref", "--format=%(contents)", f"refs/tags/{tag}"], cwd=root
)
if code != 0:
return ""
return output.split("-----BEGIN PGP SIGNATURE-----")[0].strip()
def resolve_target(root: Path, channel: str, branch: str) -> Target | None:
"""What this channel says the instance should be at.
Reads **local refs only**. On stable that is the tags the last fetch brought
down; on edge it is `origin/<branch>`, a file under `.git/refs/remotes/`.
Neither touches the network -- `read(fetch=True)` is what refreshes them, and
keeping that split is why opening the page costs nothing.
"""
if channel == CHANNEL_STABLE:
tags = release_tags(root)
if not tags:
return None
tag = tags[0]
code, line = _git(["log", "-1", FORMAT, f"refs/tags/{tag}"], cwd=root)
commit = _commit(line) if code == 0 else None
if commit is None:
return None
return Target(
ref=tag,
label=tag.lstrip("v"),
sha=commit.sha,
subject=commit.subject,
notes=_notes_for(root, tag),
)
code, line = _git(["log", "-1", FORMAT, f"origin/{branch}"], cwd=root)
commit = _commit(line) if code == 0 else None
if commit is None:
return None
return Target(
ref=f"origin/{branch}", label=commit.sha[:7], sha=commit.sha, subject=commit.subject
)
def _describe(root: Path) -> str:
"""What is running, in the most human terms git can manage.
`1.0.0` exactly at a tag, `1.0.0-7-gd4f56d` seven commits past one, and a
bare short sha when nothing has ever been tagged. That last case is why
`--always` is there: without it this fails outright on a repository with no
tags, which is every repository before its first release.
"""
code, output = _git(["describe", "--tags", "--always", "--dirty="], cwd=root)
return output if code == 0 else ""
def read(*, fetch: bool = False) -> State:
"""What is running and what is available.
@@ -182,56 +329,73 @@ def read(*, fetch: bool = False) -> State:
page, and a page that made a network request on every load would be one
somebody stops opening. The Check button passes it.
"""
branch = branch_name()
channel, branch = channel_name(), branch_name()
root = checkout_dir()
base = State(branch=branch, helper=helper_installed(), requested=pending())
base = {
"channel": channel,
"branch": branch,
"helper": helper_installed(),
"requested": pending(),
}
if root is None:
return base
return State(**base)
code, head_line = _git(["log", "-1", FORMAT], cwd=root)
if code != 0:
return State(**{**base.__dict__, "checkout": str(root), "error": head_line})
return State(**base, checkout=str(root), error=head_line)
error = ""
if fetch:
# `--tags` and `--force`: without the first, stable never learns about a
# release; without the second, a tag that was moved (which happens to a
# release that was cut wrong) is refused rather than updated, and the
# instance sits on the old one with no sign of why.
code, output = _git(
["fetch", "--quiet", "--tags", "--force", "origin", branch], cwd=root
)
if code != 0:
error = f"Could not reach the remote: {output}"
head = _commit(head_line)
target = resolve_target(root, channel, branch)
running = _describe(root)
behind: list[Commit] = []
if target is not None and head is not None and target.sha != head.sha:
code, output = _git(["log", FORMAT, f"HEAD..{target.sha}"], cwd=root)
if code == 0 and output:
behind = [c for line in output.splitlines() if (c := _commit(line))]
code, status = _git(["status", "--porcelain"], cwd=root)
dirty = bool(status.strip()) if code == 0 else False
error = ""
if fetch:
code, output = _git(["fetch", "--quiet", "origin", branch], cwd=root)
if code != 0:
error = f"Could not reach the remote: {output}"
remote_line = ""
code, output = _git(["log", "-1", FORMAT, f"origin/{branch}"], cwd=root)
if code == 0:
remote_line = output
behind: list[Commit] = []
if remote_line:
code, output = _git(["log", FORMAT, f"HEAD..origin/{branch}"], cwd=root)
if code == 0 and output:
behind = [c for line in output.splitlines() if (c := _commit(line))]
# Exactly at a tag whose name disagrees with the version this process
# reports. No subprocess: `running` and `__version__` are both already here.
mismatch = ""
if RELEASE_TAG.match(running) and running.lstrip("v") != __version__:
mismatch = running.lstrip("v")
return State(
**base,
checkout=str(root),
branch=branch,
head=_commit(head_line),
remote=_commit(remote_line) if remote_line else None,
running=running,
head=head,
available=target,
behind=behind,
dirty=dirty,
helper=helper_installed(),
requested=pending(),
version_mismatch=mismatch,
error=error,
)
# --- Asking for it -----------------------------------------------------------------
def request_update(who: str = "") -> str:
"""Ask the helper to update. Returns a message fit to show.
The file is written with the requester's email in it **for the log**, and
that is all it carries. Nothing in it reaches the helper's command line: the
helper runs the update script with its own configured branch, so being able
to press this button is not being able to choose what is deployed.
helper runs the update script with its own configured channel and branch, so
being able to press this button is not being able to choose what is deployed.
"""
path = request_path()
try:
@@ -256,18 +420,26 @@ def manual_command() -> str:
__all__ = [
"CHANNELS",
"CHANNEL_EDGE",
"CHANNEL_STABLE",
"GIT_TIMEOUT",
"MARKER_NAME",
"RELEASE_TAG",
"REQUEST_NAME",
"Commit",
"State",
"Target",
"branch_name",
"channel_name",
"checkout_dir",
"clear_request",
"helper_installed",
"manual_command",
"pending",
"read",
"release_tags",
"request_path",
"request_update",
"resolve_target",
]