admin/felhom-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.260.0 — a box ahead of the catalog reads „Naprakész", and the pin never moves backwards (R-524)
gates / gates (push) Successful in 24s
Details

Browse Source 
MEASURED 2026-09-15 (BIGNIGHT Phase 6): privatebin updated 2.0.5 -> 2.0.6, catalog
reverted to 2.0.5, and the box read „Frissítés elérhető — ma" over an Update that
would have moved the pin BACKWARDS onto a possibly-migrated datadir.

- stacks.CatalogOrder: the comparison gains a fourth answer (Ahead) and moves out of
  web, so the badge and UpdatePreflight cannot drift apart.
- The badge: ahead reads „Naprakész"/"Up to date", tag-ok, with a title saying why.
- The refusal: UpdatePreflight returns `downgrade` (409), born as a bundle key; the
  API now renders update refusals through errText so it reaches English households.
- Ahead is narrow: every differing service must be orderable AND newer, else Behind.
- Ordering is util.Version.Compare behind a tag normaliser — no second comparator.
- Three red-proofs, each seen to fail.

R-589 was already fixed in v0.258.0; only its register row was stale.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
This commit is contained in:
authentik Default Admin
2026-09-21 12:48:55 +02:00
parent 19ef0329ab
commit 8f8a64cad7
14 changed files with 597 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
controller/internal/stacks/update.go
+19
View File
@@ -10,6 +10,7 @@ import (
"time"
"gitea.dooplex.hu/admin/felhom-controller/internal/system"
"gitea.dooplex.hu/admin/felhom-controller/internal/util"
)
// ── The guarded update (update arc slice 4, controller v0.237.0) ─────────────────────────────────
@@ -322,6 +323,24 @@ func (m *Manager) UpdatePreflight(name string) *UpdateRefusal {
if m.IsMigrating() {
return m.refuseUpdate(name, "migrating", MsgUpdateMigrating, "a data migration is running")
}
// R-524 — THE PIN NEVER MOVES BACKWARDS WITHOUT THE OPERATOR. MEASURED 2026-09-15 (BIGNIGHT
// Phase 6): privatebin was updated 2.0.5 → 2.0.6, the catalog was reverted to 2.0.5, and the
// „Frissítés" button behind the badge would have advanced the pin to the OLDER image — on a
// datadir the newer version may already have migrated, with §4's ruling saying that cannot be
// undone. A catalog revert is an operator act on our side; it must never become a data event on
// the customer's side by itself.
//
// It refuses ONLY the provable case (stacks.CatalogOrder's Ahead arm: every differing service
// orderable and newer). Anything unorderable, mixed or equal falls through to the behaviour that
// shipped in v0.237.0 — this gate can block an update, so it errs towards letting one run.
//
// COMPANION RED-PROOF (REPORT.md): make CatalogOrder's Ahead arm return Behind.
// TestR524_PreflightRefusesDowngrade then fails — the update is allowed to move the pin back.
if CatalogOrder(*st) == UpdateOrderAhead {
return m.refuseUpdateErr(name, "downgrade", util.MsgError("err.stacks.update_downgrade"),
fmt.Sprintf("installed is provably NEWER than the catalog on every differing service (installed=%v catalog=%v)",
st.AppConfig.InstalledImages, st.CatalogImages))
}
// R-475: any tier counts, and an app with no copy at all is backed up first by the job. So the only
// refusal left here is Scenario L — no copy on any tier AND no way to make one now. (With a copy
// but no way to back up, the job still applies the age rule and refuses then if the copy is stale.)
controller/internal/stacks/updateorder.go
+180
View File
@@ -0,0 +1,180 @@
package stacks
import (
"strings"
"gitea.dooplex.hu/admin/felhom-controller/internal/util"
)
// ── Is this app behind the catalog, level with it, or AHEAD of it? (R-524, v0.260.0) ─────────────
//
// Slice 2 (v0.233.0) asked only "does the installed reference DIFFER from the catalog's?" and called
// every difference „Frissítés elérhető". MEASURED 2026-09-15 (BIGNIGHT Phase 6): privatebin was
// updated 2.0.5 → 2.0.6 and the catalog was then reverted to 2.0.5. The box read
// „Frissítés elérhető — ma", and the guarded Update behind that badge would have advanced the pin
// 2.0.6 → 2.0.5 — a DOWNGRADE offered to a household as an update, with a migrated datadir behind it
// and §4's ruling saying it cannot be undone.
//
// So the comparison gains a fourth answer. It lives HERE, in stacks, and not in web, because two
// callers must reach the SAME verdict: the badge (web.compareInstalledToTemplate) and the guarded
// update's refusal (Manager.UpdatePreflight). A comparison implemented twice is a comparison that
// drifts — the same lesson localisation learned when the badge's two language paths were written
// apart (R-589).
//
// IT QUERIES NO REGISTRY, exactly as before (09-update-architecture.md §8.1). Ordering is decided
// from the TAG TEXT alone, and only when the tag text can carry an order at all.
// UpdateOrder is the four-way answer to "how does what this app RUNS stand against what the catalog
// OFFERS?".
//
// ABSENT STILL MEANS UNKNOWN, AND NEVER „NAPRAKÉSZ" — the R-166 property slice 2 was built around,
// carried over verbatim. The new value is Ahead, and it is deliberately NOT folded into Current:
// the badge shows the same word for both, but the UPDATE must refuse only one of them, and a caller
// that cannot tell them apart cannot refuse correctly.
type UpdateOrder int
const (
UpdateOrderUnknown UpdateOrder = iota // nothing recorded, or nothing to compare against
UpdateOrderCurrent // every service runs exactly what the catalog pins
UpdateOrderBehind // at least one service differs and is not provably newer
UpdateOrderAhead // every differing service is provably NEWER than the catalog
)
// CatalogOrder compares an app's recorded installed images against what the catalog offers.
//
// The Ahead arm is deliberately the narrow one: EVERY differing service must be orderable and newer.
// One service that is older, or one tag that cannot carry an order, and the answer falls back to
// Behind — i.e. to exactly the behaviour of v0.233.0..v0.259.0. A half-ahead app is not a downgrade
// the box may refuse on its own; it is a mixed state a human should look at, and „Frissítés elérhető"
// is the honest label for it.
func CatalogOrder(s Stack) UpdateOrder {
if !s.Deployed || s.Protected || s.Orphaned {
// Not deployed: nothing is running. Protected: infra is ours, not the customer's to update.
// Orphaned: the template is gone from the catalog, so there is nothing to be current WITH.
return UpdateOrderUnknown
}
if s.AppConfig == nil || len(s.AppConfig.InstalledImages) == 0 {
return UpdateOrderUnknown // legacy app.yaml — no record was ever written
}
if len(s.CatalogImages) == 0 {
return UpdateOrderUnknown // no readable catalog template — cannot tell, so say nothing
}
if len(s.AppConfig.InstalledImages) != len(s.CatalogImages) {
// A service was added or removed by the template. That IS a change the customer's running
// stack has not taken up, and it is not a version order.
return UpdateOrderBehind
}
differing := 0
for svc, want := range s.CatalogImages {
got, ok := s.AppConfig.InstalledImages[svc]
if !ok {
return UpdateOrderBehind // the catalog names a service the record does not cover
}
if got.Ref == want {
continue
}
differing++
if cmp, ok := CompareImageRefs(got.Ref, want); !ok || cmp <= 0 {
return UpdateOrderBehind
}
}
if differing == 0 {
return UpdateOrderCurrent
}
return UpdateOrderAhead
}
// CompareImageRefs orders two image references the way a human reads them: -1 when a is older than
// b, 0 when they are the same version, 1 when a is newer. The second return is the whole point —
// FALSE means "these two cannot be ordered", and every caller must treat that as "do not know"
// rather than as "equal".
//
// It answers false, on purpose, for far more than it answers true:
// - a digest-pinned reference (`…@sha256:…`) — the digest carries no order;
// - a reference with no tag — the implicit `latest` is a moving target, not a position;
// - two references to DIFFERENT images (`alpine:3.20` against `…/bookstack:26.05.2`) — the numbers
// are comparable and the comparison is meaningless, which is the worst kind of false positive;
// - any tag that is not plain digits and dots: `16-alpine`, `latest`, `26.05.2-ls310`, `stable`,
// a date stamp, a git sha. 23 of the catalog's 66 pins float exactly like this (§8.1).
//
// THE ORDER ITSELF IS util.Version.Compare AND NOTHING ELSE. The house rule is one comparator in
// this repo; this function is a tag NORMALISER in front of it, never a second implementation.
func CompareImageRefs(a, b string) (int, bool) {
repoA, tagA := splitImageRef(a)
repoB, tagB := splitImageRef(b)
if repoA == "" || repoA != repoB {
return 0, false
}
va, sufA, okA := parseImageTag(tagA)
vb, sufB, okB := parseImageTag(tagB)
if !okA || !okB {
return 0, false
}
// THE SUFFIXES MUST BE IDENTICAL, and this is not pedantry. `nextcloud:31.0.14-apache` and
// `nextcloud:31.0.15-apache` are the same flavour of the same image and order cleanly; but
// `26.05.2-ls310` against `26.05.2-ls311` differs only in a build number this function has no
// rule for, and `…:2.4.0-alpine` against `…:2.4.0` is a different image content under one repo
// name. Equal-or-nothing keeps every one of those out of the Ahead arm.
if sufA != sufB {
return 0, false
}
return va.Compare(vb), true
}
// splitImageRef separates `repo` from `tag`, and returns two empty strings whenever the reference
// carries no plain tag to compare.
//
// The `/` test after the last colon is what keeps a registry PORT from being read as a tag:
// `gitea.dooplex.hu:3000/admin/app` has a colon in it and no tag at all.
func splitImageRef(ref string) (repo, tag string) {
if strings.Contains(ref, "@") {
return "", "" // digest-pinned
}
i := strings.LastIndex(ref, ":")
if i < 0 {
return "", "" // no tag — the implicit `latest`
}
if strings.Contains(ref[i+1:], "/") {
return "", "" // that colon was a registry port
}
return ref[:i], ref[i+1:]
}
// parseImageTag splits a tag into the version at its FRONT and whatever follows, and refuses
// anything whose front is not `X.Y` or `X.Y.Z` (an optional leading `v` is allowed).
//
// "2.0.6" → 2.0.6, ""
// "31.0.14-apache" → 31.0.14, "-apache" ← real: the catalog's nextcloud pin
// "11.6" → 11.6.0, "" ← real: the catalog's mariadb pins
// "16-alpine" → refused: one component is not a version, it is a major line
// "apache-2.57.0" → refused: the version is not at the front (real: the catalog's kimai pin)
// "20260915" → refused: a date stamp is one component
//
// A two-part tag is padded with `.0` before it reaches the comparator. The padding is safe in the
// one direction that matters: it only ever adds the smallest possible patch number, and it is
// applied to whichever side is short, so it can never make an older tag look newer.
func parseImageTag(tag string) (util.Version, string, bool) {
t := strings.TrimPrefix(tag, "v")
end := 0
for end < len(t) && ((t[end] >= '0' && t[end] <= '9') || t[end] == '.') {
end++
}
head, suffix := t[:end], t[end:]
parts := strings.Split(head, ".")
if len(parts) < 2 || len(parts) > 3 {
return util.Version{}, "", false
}
for _, p := range parts {
if p == "" {
return util.Version{}, "", false
}
}
for len(parts) < 3 {
parts = append(parts, "0")
}
v, err := util.ParseVersion(strings.Join(parts, "."))
if err != nil {
return util.Version{}, "", false
}
return v, suffix, true
}
controller/internal/stacks/updateorder_test.go
+239
View File
@@ -0,0 +1,239 @@
package stacks
import (
"strings"
"testing"
)
// R-524 (v0.260.0) — the order, and the refusal to move a pin backwards.
//
// The defect this pins was MEASURED, not imagined: BIGNIGHT Phase 6, 2026-09-15, privatebin
// installed 2.0.6 against a catalog reverted to 2.0.5, badge „Frissítés elérhető — ma", and the
// button behind it offering the downgrade.
func oi(ref string) InstalledImage {
return InstalledImage{Ref: ref, Digest: "sha256:x", At: "2026-09-01T00:00:00Z"}
}
// coStack builds a deployed app with its record and its CATALOG images stated explicitly.
func coStack(installed map[string]InstalledImage, catalog map[string]string) Stack {
return Stack{
Name: "privatebin",
Deployed: true,
State: StateRunning,
AppConfig: &AppConfig{Deployed: true, InstalledImages: installed},
CatalogImages: catalog,
}
}
// TestR524_CatalogOrder is the whole verdict table, including every arm that must NOT be Ahead.
//
// COMPANION RED-PROOF (run 2026-09-21): in CatalogOrder, change the Ahead arm's guard
// `if cmp, ok := CompareImageRefs(...); !ok || cmp <= 0` to `if cmp, ok := ...; cmp < 0` — i.e. the
// plausible-looking implementation that treats an UNORDERABLE pair as ahead. The three floating-tag
// sub-tests below („a floating tag …", „a different image entirely", „a digest pin") then fail with
// Ahead, which is the verdict that would suppress a real „Frissítés elérhető" on 23 of the catalog's
// 66 pins. Reverted.
func TestR524_CatalogOrder(t *testing.T) {
cases := []struct {
name string
stack Stack
want UpdateOrder
}{
{
name: "level — every service matches",
stack: coStack(map[string]InstalledImage{"web": oi("privatebin/pdo:2.0.5")}, map[string]string{"web": "privatebin/pdo:2.0.5"}),
want: UpdateOrderCurrent,
},
{
name: "behind — the catalog is newer",
stack: coStack(map[string]InstalledImage{"web": oi("privatebin/pdo:2.0.5")}, map[string]string{"web": "privatebin/pdo:2.0.6"}),
want: UpdateOrderBehind,
},
{
name: "AHEAD — THE BIGNIGHT CASE: the box updated, the catalog was reverted",
stack: coStack(map[string]InstalledImage{"web": oi("privatebin/pdo:2.0.6")}, map[string]string{"web": "privatebin/pdo:2.0.5"}),
want: UpdateOrderAhead,
},
{
name: "ahead across a major — still ahead, still no downgrade",
stack: coStack(map[string]InstalledImage{"web": oi("privatebin/pdo:3.0.0")}, map[string]string{"web": "privatebin/pdo:2.0.5"}),
want: UpdateOrderAhead,
},
{
name: "ahead on a TWO-PART tag (mariadb:11.6 style)",
stack: coStack(map[string]InstalledImage{"db": oi("mariadb:11.7")}, map[string]string{"db": "mariadb:11.6"}),
want: UpdateOrderAhead,
},
{
name: "MIXED — one newer, one older — is BEHIND, never ahead",
stack: coStack(
map[string]InstalledImage{"web": oi("privatebin/pdo:2.0.6"), "db": oi("mariadb:11.4")},
map[string]string{"web": "privatebin/pdo:2.0.5", "db": "mariadb:11.6"}),
want: UpdateOrderBehind,
},
{
name: "a floating tag cannot be ordered — behind, as before",
stack: coStack(map[string]InstalledImage{"db": oi("postgres:16-alpine")}, map[string]string{"db": "postgres:15-alpine"}),
want: UpdateOrderBehind,
},
{
name: "a different image entirely — the numbers compare, the comparison is meaningless",
stack: coStack(map[string]InstalledImage{"web": oi("privatebin/pdo:2.0.6")}, map[string]string{"web": "alpine:3.20"}),
want: UpdateOrderBehind,
},
{
name: "a digest pin carries no order",
stack: coStack(map[string]InstalledImage{"web": oi("privatebin/pdo@sha256:aaaa")}, map[string]string{"web": "privatebin/pdo:2.0.5"}),
want: UpdateOrderBehind,
},
{
name: "a service was ADDED by the template — behind, not an order at all",
stack: coStack(map[string]InstalledImage{"web": oi("privatebin/pdo:2.0.6")}, map[string]string{"web": "privatebin/pdo:2.0.5", "db": "mariadb:11.6"}),
want: UpdateOrderBehind,
},
{
name: "NO RECORD AT ALL — unknown, and never current",
stack: coStack(nil, map[string]string{"web": "privatebin/pdo:2.0.5"}),
want: UpdateOrderUnknown,
},
{
name: "no readable catalog template — unknown",
stack: coStack(map[string]InstalledImage{"web": oi("privatebin/pdo:2.0.6")}, nil),
want: UpdateOrderUnknown,
},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
if got := CatalogOrder(c.stack); got != c.want {
t.Errorf("CatalogOrder = %v, want %v", got, c.want)
}
})
}
}
// TestR524_ProtectedAndUndeployedAreUnknown keeps the three carried-over guards honest: they were in
// web.compareInstalledToTemplate before the move and a move is exactly when a guard gets dropped.
func TestR524_ProtectedAndUndeployedAreUnknown(t *testing.T) {
base := coStack(map[string]InstalledImage{"web": oi("privatebin/pdo:2.0.6")}, map[string]string{"web": "privatebin/pdo:2.0.5"})
if CatalogOrder(base) != UpdateOrderAhead {
t.Fatalf("the base case must be Ahead, or this test proves nothing")
}
for _, c := range []struct {
name string
mut func(*Stack)
}{
{"not deployed", func(s *Stack) { s.Deployed = false }},
{"protected infra", func(s *Stack) { s.Protected = true }},
{"orphaned", func(s *Stack) { s.Orphaned = true }},
} {
t.Run(c.name, func(t *testing.T) {
st := base
c.mut(&st)
if got := CatalogOrder(st); got != UpdateOrderUnknown {
t.Errorf("CatalogOrder = %v, want Unknown", got)
}
})
}
}
// TestR524_CompareImageRefs pins the normaliser in front of util.Version.Compare, where the traps
// live: a registry port that looks like a tag, a two-part tag, a leading v, a zero-padded component.
func TestR524_CompareImageRefs(t *testing.T) {
cases := []struct {
a, b string
wantCmp int
wantOK bool
}{
{"privatebin/pdo:2.0.6", "privatebin/pdo:2.0.5", 1, true},
{"privatebin/pdo:2.0.5", "privatebin/pdo:2.0.6", -1, true},
{"privatebin/pdo:2.0.5", "privatebin/pdo:2.0.5", 0, true},
{"lscr.io/linuxserver/bookstack:v26.05.2", "lscr.io/linuxserver/bookstack:25.02.2", 1, true},
// 26.05.2 must beat 26.5.1 and NOT lose to it on the zero: Atoi("05") is 5.
{"x/y:26.05.2", "x/y:26.5.1", 1, true},
{"mariadb:11.7", "mariadb:11.6", 1, true},
// A two-part tag pads to .0, so 11.6 is older than 11.6.1 and level with itself.
{"mariadb:11.6", "mariadb:11.6.1", -1, true},
// A registry PORT is not a tag.
{"gitea.dooplex.hu:3000/admin/app", "gitea.dooplex.hu:3000/admin/app", 0, false},
{"postgres:16-alpine", "postgres:15-alpine", 0, false},
{"redis:7-alpine", "redis:7-alpine", 0, false},
{"app:latest", "app:2.0.0", 0, false},
{"app:20260915", "app:20260914", 0, false},
{"app@sha256:aa", "app:2.0.0", 0, false},
{"alpine:3.20", "privatebin/pdo:2.0.5", 0, false},
{"app", "app:2.0.0", 0, false},
// Real catalog shapes. The suffix must be IDENTICAL for the numbers to be compared.
{"nextcloud:31.0.15-apache", "nextcloud:31.0.14-apache", 1, true},
{"nextcloud:31.0.14-apache", "nextcloud:31.0.14", 0, false},
{"x/y:26.05.2-ls311", "x/y:26.05.2-ls310", 0, false},
{"postgis/postgis:16-3.5-alpine", "postgis/postgis:15-3.5-alpine", 0, false},
{"kimai/kimai2:apache-2.57.0", "kimai/kimai2:apache-2.56.0", 0, false},
}
for _, c := range cases {
t.Run(c.a+" vs "+c.b, func(t *testing.T) {
cmp, ok := CompareImageRefs(c.a, c.b)
if ok != c.wantOK {
t.Fatalf("orderable = %v, want %v", ok, c.wantOK)
}
if ok && cmp != c.wantCmp {
t.Errorf("cmp = %d, want %d", cmp, c.wantCmp)
}
})
}
}
// ── The refusal: the guarded Update never moves a pin backwards (R-524) ──────────────────────────
// TestR524_PreflightRefusesDowngrade is the CONSEQUENCE test, not the mechanism test: the question
// is not "does CatalogOrder say Ahead" (TestR524_CatalogOrder asks that) but "does the button
// refuse". R-97b's Scenario F is the reason the two are separate — the mechanism was proven and the
// consequence was still broken.
//
// COMPANION RED-PROOF (run 2026-09-21): delete the `CatalogOrder(*st) == UpdateOrderAhead` block from
// UpdatePreflight. The `ahead` sub-test then fails with `ref = <nil>` — the update is allowed, and
// the next thing it does is advance the pin to the older image. Reverted.
func TestR524_PreflightRefusesDowngrade(t *testing.T) {
cases := []struct {
name string
installed string
catalog string
wantReason string // "" = must be allowed
}{
{"ahead — the downgrade is refused", "nextcloud:31.0.15-apache", "nextcloud:31.0.14-apache", "downgrade"},
{"behind — the ordinary update is allowed", "nextcloud:31.0.13-apache", "nextcloud:31.0.14-apache", ""},
{"level — allowed (a same-version update is the repair path)", "nextcloud:31.0.14-apache", "nextcloud:31.0.14-apache", ""},
{"unorderable — allowed, exactly as before v0.260.0", "nextcloud:31-apache", "nextcloud:30-apache", ""},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
m, _, _, _ := newSlice4Manager(t)
st := m.stacks["nextcloud"]
st.AppConfig.InstalledImages = map[string]InstalledImage{"web": oi(c.installed)}
st.CatalogImages = map[string]string{"web": c.catalog}
ref := m.UpdatePreflight("nextcloud")
if c.wantReason == "" {
if ref != nil {
t.Fatalf("this update must be allowed, got refusal %q: %s", ref.Reason, ref.Message)
}
return
}
if ref == nil {
t.Fatalf("this update must be REFUSED with reason %q, got nil", c.wantReason)
}
if ref.Reason != c.wantReason {
t.Fatalf("reason = %q, want %q (message %q)", ref.Reason, c.wantReason, ref.Message)
}
// The refusal carries its bundle key, so api.Router.errText renders it in the
// household's language. Without the Cause it would be Hungarian on an English page —
// the R-589 failure in a new place.
if ref.Cause == nil {
t.Error("the downgrade refusal must carry its key as a Cause, not only a Hungarian literal")
}
if !strings.Contains(ref.Message, "katal") {
t.Errorf("the Hungarian fallback must name the catalog, got %q", ref.Message)
}
})
}
}