v0.235.0: freeze the version, keep the fixes flowing (operator ruling 2026-09-06)
gates / gates (push) Successful in 12s
gates / gates (push) Successful in 12s
Slice 3. R-447 was BLOCKED because R-438 established that RestartStack's use of up -d to pick up template changes was CHOSEN and written down in its own comment. The operator ruled Option 1, and this implements it. The rule: while the catalog offers the same version you run, its fixes flow to you; the moment it moves to a newer version you are frozen until you update. NOTHING was added to any of the thirteen compose up -d call sites. Most of them are repairs - the boot reconciler, the drive-return gate, the app-stop guard - and a repair path that refuses to repair leaves a customer's app down, which is worse than the problem. They are made safe by removing the reason. app.yaml gains pinned_images: what the app is SUPPOSED to run. It is NOT installed_images, which is an observation; letting a reading become a deployment is the R-166 category error one field over. Four writers, each also storing the exact definition as applied-compose.yml. UpdateStack advances the pin and re-renders BEFORE the pull, because pull and up -d act on the file on disk, and a pin set afterwards would pull the frozen version and report success. The syncer renders instead of copying, through one nil-safe seam. Catalog images equal the pin -> verbatim, so fixes and self-healing both survive; they differ -> the WHOLE stored definition, never a substitution of refs into a newer template (wger 2.6 needs a DB config the older template cannot supply). This is deliberately not 'skip deployed apps', which was option B and was rejected. AdoptPins runs once at boot after the backfill, files only, and skips loudly rather than inventing a pin. syncer.Start() moved to after it: the initial sync would otherwise run while every app was unpinned and overwrite a deployed app's version once per boot. THE BADGE HAD TO CHANGE OR SLICE 2 WOULD HAVE INVERTED SILENTLY. TemplateImages reads the LIVE compose file, which is now the frozen one, so the comparison would have answered Naprakesz on exactly the apps that are behind - with every test green, because the new field has the same type. It now reads CatalogImages. +16 tests (1729 -> 1745), 28 packages green. Three red-proofs run and reverted. A test also caught the syncer writing an empty compose file over a live app.
This commit is contained in:
@@ -138,6 +138,21 @@ type AppConfig struct {
|
||||
// WRITTEN BY: Manager.recordInstalledImages ONLY, from StartStack / RestartStack / UpdateStack
|
||||
// and the deploy path. READ BY: web.updateBadge (v0.233.0). Nothing takes a DECISION from it.
|
||||
InstalledImages map[string]InstalledImage `yaml:"installed_images,omitempty" json:"installed_images,omitempty"`
|
||||
// PinnedImages is what this app is SUPPOSED to run, per compose service — the customer's
|
||||
// INTENT, and the input the catalog render obeys (v0.235.0, operator ruling 2026-09-06:
|
||||
// "freeze the version, keep the fixes flowing").
|
||||
//
|
||||
// IT IS NOT InstalledImages. That field is an OBSERVATION ("what is running"), written by
|
||||
// looking at containers. This one is a DECISION ("what should run"), written only by an act
|
||||
// that is entitled to move a version: a deploy, a deliberate update, a restore, or the
|
||||
// one-time adoption pass. Letting an observation feed a decision would make a bad reading
|
||||
// become a bad deployment — the same category error the desired_state field exists to avoid
|
||||
// (R-166). They will normally agree; when they disagree that is a signal, not a bug to
|
||||
// paper over.
|
||||
//
|
||||
// ABSENT MEANS UNPINNED, and unpinned means the app behaves exactly as it did before
|
||||
// v0.235.0. It never means "pin to whatever the catalog says now".
|
||||
PinnedImages map[string]string `yaml:"pinned_images,omitempty" json:"pinned_images,omitempty"`
|
||||
}
|
||||
|
||||
// InstalledImage is one compose service's observed image. See AppConfig.InstalledImages.
|
||||
@@ -482,6 +497,16 @@ func (m *Manager) runComposeDeploy(name, stackDir string, env map[string]string,
|
||||
deployEnv := m.stackEnv(stackDir)
|
||||
m.recordInstalledImages(name, stackDir, deployEnv)
|
||||
|
||||
// Pin what we just deployed FROM (v0.235.0). The stack dir's compose file IS what the deploy
|
||||
// used, so it is both the pin's source and the definition stored beside it. A failure here is
|
||||
// logged and never fails the deploy — the app is up, and an unpinned app simply keeps
|
||||
// pre-v0.235.0 behaviour.
|
||||
if pin, data, err := PinFromCompose(ComposePathIn(stackDir)); err != nil {
|
||||
m.logger.Printf("[WARN] [stacks] pin %s: cannot pin from the deployed compose file: %v", name, err)
|
||||
} else if err := m.SetPin(name, stackDir, pin, data); err != nil {
|
||||
m.logger.Printf("[ERROR] [stacks] pin %s: %v", name, err)
|
||||
}
|
||||
|
||||
// Post-deploy container state check (async, non-blocking)
|
||||
m.logPostStartStatus(name, stackDir, deployEnv)
|
||||
|
||||
|
||||
@@ -150,13 +150,26 @@ type Stack struct {
|
||||
// forgetting costs at most one threshold window, whereas persisting could carry a stale
|
||||
// "this app is crash-looping" verdict across the restart that fixed it.
|
||||
RestartingSince time.Time `json:"restarting_since,omitempty"`
|
||||
// TemplateImages is what the stack's CURRENT docker-compose.yml pins, per compose service —
|
||||
// i.e. what the catalog says this app should be running right now. Refreshed by ScanStacks for
|
||||
// deployed, non-protected apps only; nil for everything else and nil when the file cannot be
|
||||
// parsed. Nil means CANNOT-TELL and never means "matches": web.updateBadge renders nothing.
|
||||
// Not persisted — it is a read of a file the syncer owns, and re-reading is cheaper than a
|
||||
// second copy that can go stale.
|
||||
// TemplateImages is what the stack's LIVE docker-compose.yml pins, per compose service.
|
||||
//
|
||||
// ⚠ SINCE v0.235.0 THIS IS NOT "WHAT THE CATALOG OFFERS". The live file is RENDERED: for a
|
||||
// pinned app whose version the catalog has moved past, it is the app's own frozen definition.
|
||||
// So TemplateImages answers "what will the next `compose up -d` bring this app to" — which is
|
||||
// exactly what a debugger wants and exactly the WRONG input for the update badge, because a
|
||||
// frozen app's live file names the OLD version and the comparison would read „Naprakész".
|
||||
// THE BADGE USES CatalogImages. See web.compareInstalledToTemplate.
|
||||
//
|
||||
// Refreshed by ScanStacks for deployed, non-protected apps only; nil otherwise and nil when the
|
||||
// file cannot be parsed. Not persisted.
|
||||
TemplateImages map[string]string `json:"template_images,omitempty"`
|
||||
// CatalogImages is what the CATALOG currently offers for this app, read from the syncer's git
|
||||
// clone (`<DataDir>/catalog-cache/templates/<app>/docker-compose.yml`) rather than from the
|
||||
// stack dir. Added in v0.235.0 because the render made the live file unusable for the question
|
||||
// "is this app behind?".
|
||||
//
|
||||
// Nil means CANNOT-TELL — the cache is missing, unreadable, or the app is not in the catalog —
|
||||
// and the badge then renders NOTHING. Absent is unknown; it is never „Naprakész".
|
||||
CatalogImages map[string]string `json:"catalog_images,omitempty"`
|
||||
}
|
||||
|
||||
// Manager handles all docker compose stack operations.
|
||||
@@ -527,6 +540,19 @@ func (m *Manager) ScanStacks() error {
|
||||
}
|
||||
}
|
||||
|
||||
// What the CATALOG offers — the badge's input, and deliberately a different file from the
|
||||
// one above (v0.235.0). A missing catalog entry is silent at INFO: an orphaned app has no
|
||||
// catalog template by definition, and warning once per app per scan would be noise.
|
||||
var catImages map[string]string
|
||||
if deployed && !m.cfg.IsProtectedStack(name) {
|
||||
catPath := m.CatalogTemplatePath(name, "docker-compose.yml")
|
||||
if imgs, cerr := ParseComposeImages(catPath); cerr == nil {
|
||||
catImages = imgs
|
||||
} else if m.isDebug() {
|
||||
m.logger.Printf("[DEBUG] [stacks] ScanStacks: no readable catalog template for %s (%v) — the update badge will render nothing", name, cerr)
|
||||
}
|
||||
}
|
||||
|
||||
if existing, ok := m.stacks[name]; ok {
|
||||
existing.ComposePath = composePath
|
||||
existing.Meta = meta
|
||||
@@ -537,6 +563,7 @@ func (m *Manager) ScanStacks() error {
|
||||
existing.Deployed = deployed
|
||||
existing.AppConfig = appCfg
|
||||
existing.TemplateImages = tplImages
|
||||
existing.CatalogImages = catImages
|
||||
}
|
||||
} else {
|
||||
m.stacks[name] = &Stack{
|
||||
@@ -548,6 +575,7 @@ func (m *Manager) ScanStacks() error {
|
||||
Protected: m.cfg.IsProtectedStack(name),
|
||||
AppConfig: appCfg,
|
||||
TemplateImages: tplImages,
|
||||
CatalogImages: catImages,
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1205,6 +1233,24 @@ func (m *Manager) UpdateStack(name string) error {
|
||||
m.logger.Printf("[INFO] [stacks] Updating stack: %s", name)
|
||||
start := time.Now()
|
||||
dir := filepath.Dir(stack.ComposePath)
|
||||
|
||||
// v0.235.0 — ADVANCE THE PIN FIRST, AND RE-RENDER BEFORE THE PULL.
|
||||
//
|
||||
// This is the ONE act entitled to move a version; the freeze exists so that nothing else can.
|
||||
// The ordering is load-bearing, not stylistic: `compose pull` and `up -d` act on the file on
|
||||
// disk, so the catalog's current definition has to BE that file before either runs. Setting the
|
||||
// pin afterwards would pull the frozen version and change nothing, while reporting success — and
|
||||
// a button that lies is worse than a button that refuses.
|
||||
//
|
||||
// A FAILED PIN WRITE REFUSES THE UPDATE, deliberately the opposite of recordInstalledImages.
|
||||
// That field is an observation and a failed write is a bookkeeping gap; this one is INTENT, and
|
||||
// an update whose intent could not be recorded leaves the box running a version it has no record
|
||||
// of choosing — the exact ambiguity R-166 closed for desired_state, one field over.
|
||||
if err := m.advancePinToCatalog(name, dir); err != nil {
|
||||
m.logger.Printf("[ERROR] [stacks] Stack %s update refused: %v", name, err)
|
||||
return fmt.Errorf("updating stack %s: %w", name, err)
|
||||
}
|
||||
|
||||
env := m.stackEnv(dir)
|
||||
|
||||
if m.isDebug() {
|
||||
|
||||
@@ -0,0 +1,358 @@
|
||||
package stacks
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// AppliedComposeFile is the stored copy of the docker-compose.yml an app was last brought up FROM.
|
||||
//
|
||||
// WHY IT LIVES IN THE STACK DIRECTORY, and why this exact name: `Syncer.copyTemplates` copies
|
||||
// EXACTLY `docker-compose.yml` and `.felhom.yml` and nothing else, so any other name in that
|
||||
// directory is safe from the catalog. Keeping it beside the app means it travels through every path
|
||||
// that already moves a stack dir, and anyone debugging the box can see it without a tool.
|
||||
//
|
||||
// It is the FROZEN definition: when the catalog has moved past an app's pin, this whole file is
|
||||
// written to docker-compose.yml. Never a substitution of pinned refs into a newer template — a
|
||||
// template's env and volumes can belong to its version (`wger 2.6` needs a full DB config the older
|
||||
// template cannot supply), and an old image under a new template is a third broken state nobody
|
||||
// chose.
|
||||
const AppliedComposeFile = "applied-compose.yml"
|
||||
|
||||
// AppliedComposePath is the single definition of where the stored definition lives.
|
||||
func AppliedComposePath(stackDir string) string {
|
||||
return filepath.Join(stackDir, AppliedComposeFile)
|
||||
}
|
||||
|
||||
// StoreAppliedDefinition writes the compose definition this app is pinned to, atomically.
|
||||
//
|
||||
// Atomic tmp+rename for the same reason SaveAppConfig is: the syncer may read this file at any
|
||||
// moment, and a half-written compose file rendered over a live app is a broken app.
|
||||
func StoreAppliedDefinition(stackDir string, data []byte) error {
|
||||
if len(data) == 0 {
|
||||
// NEVER store an empty definition. An empty applied file would later be rendered over the
|
||||
// live compose file and take the app down — see the render table's "unreadable or empty"
|
||||
// row, which treats it as absent precisely so this cannot happen.
|
||||
return fmt.Errorf("refusing to store an empty applied definition for %s", filepath.Base(stackDir))
|
||||
}
|
||||
path := AppliedComposePath(stackDir)
|
||||
tmp := path + ".tmp"
|
||||
if err := os.WriteFile(tmp, data, 0o644); err != nil {
|
||||
return fmt.Errorf("writing %s: %w", tmp, err)
|
||||
}
|
||||
if err := os.Rename(tmp, path); err != nil {
|
||||
_ = os.Remove(tmp)
|
||||
return fmt.Errorf("renaming %s to %s: %w", tmp, path, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// LoadAppliedDefinition returns the stored definition, or an error when there is none or it is
|
||||
// unusable. An empty file is an ERROR, not empty content — see the render table.
|
||||
func LoadAppliedDefinition(stackDir string) ([]byte, error) {
|
||||
data, err := os.ReadFile(AppliedComposePath(stackDir))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if len(strings.TrimSpace(string(data))) == 0 {
|
||||
return nil, fmt.Errorf("stored applied definition for %s is empty", filepath.Base(stackDir))
|
||||
}
|
||||
return data, nil
|
||||
}
|
||||
|
||||
// SetPin records what an app is SUPPOSED to run and stores the definition that pin came from.
|
||||
//
|
||||
// PIN FIRST, THEN STORE, and the degradation is deliberate: if the pin lands and the store fails,
|
||||
// the app is pinned with no stored definition, and the render table's own row for that case copies
|
||||
// the catalog verbatim and WARNs. That is today's behaviour plus a loud line — the same outcome as
|
||||
// being unpinned, never a silent freeze onto a definition we do not have.
|
||||
//
|
||||
// `composeSrc` MUST be the exact bytes the pin was derived from. Passing a different file is how a
|
||||
// stack ends up frozen onto something it never ran.
|
||||
func (m *Manager) SetPin(name, stackDir string, pin map[string]string, composeSrc []byte) error {
|
||||
if len(pin) == 0 {
|
||||
return fmt.Errorf("refusing to pin %s to an empty image set", name)
|
||||
}
|
||||
cfg := LoadAppConfig(stackDir)
|
||||
if cfg == nil {
|
||||
// No app.yaml means nothing is deployed here. Not an error — the same no-op
|
||||
// SetDesiredState makes for the same reason.
|
||||
m.logger.Printf("[DEBUG] [stacks] pin %s: no app.yaml — nothing deployed here, nothing to pin", name)
|
||||
return nil
|
||||
}
|
||||
|
||||
if !samePin(cfg.PinnedImages, pin) {
|
||||
cfg.PinnedImages = pin
|
||||
meta := LoadMetadata(stackDir)
|
||||
if err := SaveAppConfig(stackDir, cfg, m.encKey, SensitiveEnvVars(&meta)); err != nil {
|
||||
return fmt.Errorf("recording pin for %s: %w", name, err)
|
||||
}
|
||||
m.logger.Printf("[INFO] [stacks] pin %s: %s", name, summarisePin(pin))
|
||||
|
||||
m.mu.Lock()
|
||||
if st, ok := m.stacks[name]; ok && st.AppConfig != nil {
|
||||
st.AppConfig.PinnedImages = pin
|
||||
}
|
||||
m.mu.Unlock()
|
||||
}
|
||||
|
||||
if err := StoreAppliedDefinition(stackDir, composeSrc); err != nil {
|
||||
// Loud, and NOT fatal to the pin — see the comment above.
|
||||
m.logger.Printf("[ERROR] [stacks] pin %s: the pin is recorded but its definition could not be stored (the app is unaffected; the catalog will be copied verbatim until this is fixed): %v", name, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// samePin compares two pins by content so an unchanged pin does not rewrite app.yaml — that file
|
||||
// holds encrypted secrets and rewriting it for no new information is pure risk (the SetDesiredState
|
||||
// rule).
|
||||
func samePin(a, b map[string]string) bool {
|
||||
if len(a) != len(b) {
|
||||
return false
|
||||
}
|
||||
for k, va := range a {
|
||||
if vb, ok := b[k]; !ok || va != vb {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
// summarisePin renders a pin for ONE log line. Image refs only — this file never logs anything out
|
||||
// of app.yaml's env map, which holds encrypted secrets.
|
||||
func summarisePin(pin map[string]string) string {
|
||||
svcs := make([]string, 0, len(pin))
|
||||
for svc := range pin {
|
||||
svcs = append(svcs, svc)
|
||||
}
|
||||
sort.Strings(svcs)
|
||||
parts := make([]string, 0, len(svcs))
|
||||
for _, svc := range svcs {
|
||||
parts = append(parts, svc+"="+pin[svc])
|
||||
}
|
||||
return strings.Join(parts, ", ")
|
||||
}
|
||||
|
||||
// ComposePathIn resolves a stack directory's compose file, honouring the .yml/.yaml pair exactly as
|
||||
// ScanStacks does. One rule, so a caller cannot pin from a file the scanner would not have read.
|
||||
func ComposePathIn(stackDir string) string {
|
||||
p := filepath.Join(stackDir, "docker-compose.yml")
|
||||
if _, err := os.Stat(p); err == nil {
|
||||
return p
|
||||
}
|
||||
alt := filepath.Join(stackDir, "docker-compose.yaml")
|
||||
if _, err := os.Stat(alt); err == nil {
|
||||
return alt
|
||||
}
|
||||
return p // the canonical name; the caller's read will report the real error
|
||||
}
|
||||
|
||||
// PinFromCompose reads a compose file and returns both the pin it implies and its exact bytes, so a
|
||||
// caller cannot accidentally pin from one file and store another.
|
||||
func PinFromCompose(composePath string) (map[string]string, []byte, error) {
|
||||
images, err := ParseComposeImages(composePath)
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
if len(images) == 0 {
|
||||
return nil, nil, fmt.Errorf("%s declares no images", composePath)
|
||||
}
|
||||
data, err := os.ReadFile(composePath)
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
return images, data, nil
|
||||
}
|
||||
|
||||
// --- what the syncer is told ---
|
||||
|
||||
// RenderPlan is the per-app answer the stack manager gives the catalog syncer.
|
||||
//
|
||||
// It carries FACTS, not a decision: the render table lives in the syncer, which is the thing doing
|
||||
// the writing. The syncer must never read app.yaml itself — that file is the manager's and carries
|
||||
// encrypted values — so everything it needs to apply the table comes through here.
|
||||
type RenderPlan struct {
|
||||
Deployed bool
|
||||
Deploying bool
|
||||
Protected bool
|
||||
Pinned map[string]string // service -> image ref; nil/empty means UNPINNED
|
||||
AppliedPath string // the stored definition; "" when none is stored
|
||||
}
|
||||
|
||||
// RenderPlanFor answers for one app by name. Unknown apps come back as an empty plan, which the
|
||||
// syncer reads as "not deployed" — i.e. copy verbatim, exactly the pre-v0.235.0 behaviour.
|
||||
func (m *Manager) RenderPlanFor(name string) RenderPlan {
|
||||
s, ok := m.GetStack(name)
|
||||
if !ok {
|
||||
return RenderPlan{}
|
||||
}
|
||||
plan := RenderPlan{
|
||||
Deployed: s.Deployed,
|
||||
Deploying: s.Deploying,
|
||||
Protected: s.Protected,
|
||||
}
|
||||
if s.AppConfig != nil && len(s.AppConfig.PinnedImages) > 0 {
|
||||
plan.Pinned = s.AppConfig.PinnedImages
|
||||
}
|
||||
stackDir := filepath.Dir(s.ComposePath)
|
||||
if _, err := LoadAppliedDefinition(stackDir); err == nil {
|
||||
plan.AppliedPath = AppliedComposePath(stackDir)
|
||||
}
|
||||
return plan
|
||||
}
|
||||
|
||||
// --- adoption ---
|
||||
|
||||
// AdoptPins gives a pin to every deployed app that has none, and stores the definition it is
|
||||
// running. Call ONCE at startup, immediately AFTER BackfillInstalledImages so an app the backfill
|
||||
// has just observed can be pinned in the same boot.
|
||||
//
|
||||
// ── IT NEVER GUESSES, AND THAT IS MOST OF THE CODE ───────────────────────────────────────────
|
||||
//
|
||||
// Two skips, each with a reason that is not interchangeable:
|
||||
//
|
||||
// 1. The observation is INCOMPLETE (stopped, crash-looping, mid-anything). We do not know what the
|
||||
// app runs, so we cannot say what it should run. Reuses observationCoversTemplate — the SAME
|
||||
// completeness rule the backfill uses, deliberately not a second one.
|
||||
// 2. The observation is complete but DIFFERS from the current template. The app is already running
|
||||
// something the catalog no longer offers, and we have no stored definition for it. Pinning here
|
||||
// would be right, but the FREEZE would then render a definition we do not possess — and the only
|
||||
// way to manufacture one is to substitute the running refs into the newer template, which is
|
||||
// exactly the third-broken-state this design refuses (see AppliedComposeFile).
|
||||
//
|
||||
// In both cases the app keeps behaving exactly as it did before v0.235.0, loudly. Absent means
|
||||
// unknown; unknown is never resolved by inventing an answer.
|
||||
//
|
||||
// It reads and writes FILES only. It starts, stops and touches no container.
|
||||
func (m *Manager) AdoptPins() int {
|
||||
pinned, alreadyPinned, skippedIncomplete, skippedMismatch := 0, 0, 0, 0
|
||||
|
||||
for _, s := range m.GetStacks() {
|
||||
if !s.Deployed || s.Protected || s.Deploying {
|
||||
continue
|
||||
}
|
||||
if s.AppConfig != nil && len(s.AppConfig.PinnedImages) > 0 {
|
||||
alreadyPinned++
|
||||
continue
|
||||
}
|
||||
stackDir := filepath.Dir(s.ComposePath)
|
||||
|
||||
tpl, err := ParseComposeImages(s.ComposePath)
|
||||
if err != nil || len(tpl) == 0 {
|
||||
m.logger.Printf("[WARN] [stacks] pin adoption: %s left UNPINNED — its compose file declares no readable images (%v). It keeps pre-v0.235.0 behaviour.", s.Name, err)
|
||||
skippedIncomplete++
|
||||
continue
|
||||
}
|
||||
|
||||
var observed map[string]InstalledImage
|
||||
if s.AppConfig != nil {
|
||||
observed = s.AppConfig.InstalledImages
|
||||
}
|
||||
if !observationCoversTemplate(observed, tpl) {
|
||||
m.logger.Printf("[WARN] [stacks] pin adoption: %s left UNPINNED — no complete record of what it is running (%d of %d service(s) observed). It keeps pre-v0.235.0 behaviour.",
|
||||
s.Name, len(observed), len(tpl))
|
||||
skippedIncomplete++
|
||||
continue
|
||||
}
|
||||
|
||||
if diff := pinMismatch(observed, tpl); diff != "" {
|
||||
m.logger.Printf("[WARN] [stacks] pin adoption: %s left UNPINNED — it is running something the current template no longer offers, and there is no stored definition for it: %s. It keeps pre-v0.235.0 behaviour.",
|
||||
s.Name, diff)
|
||||
skippedMismatch++
|
||||
continue
|
||||
}
|
||||
|
||||
_, data, err := PinFromCompose(s.ComposePath)
|
||||
if err != nil {
|
||||
m.logger.Printf("[WARN] [stacks] pin adoption: %s: %v", s.Name, err)
|
||||
skippedIncomplete++
|
||||
continue
|
||||
}
|
||||
if err := m.SetPin(s.Name, stackDir, tpl, data); err != nil {
|
||||
m.logger.Printf("[ERROR] [stacks] pin adoption: %s: %v", s.Name, err)
|
||||
continue
|
||||
}
|
||||
pinned++
|
||||
}
|
||||
|
||||
// A POSITIVE OBSERVABLE EITHER WAY (standing rule 3): "0 pinned" and "the pass never ran" must
|
||||
// not look the same in a log.
|
||||
m.logger.Printf("[INFO] [stacks] pin adoption: %d pinned, %d already pinned, %d left unpinned (%d not completely observed, %d running something the template no longer offers)",
|
||||
pinned, alreadyPinned, skippedIncomplete+skippedMismatch, skippedIncomplete, skippedMismatch)
|
||||
return pinned
|
||||
}
|
||||
|
||||
// pinMismatch returns a human description of the first service whose RUNNING reference differs from
|
||||
// what the template pins, or "" when they agree everywhere. Deterministic order so two runs produce
|
||||
// the same line.
|
||||
func pinMismatch(observed map[string]InstalledImage, tpl map[string]string) string {
|
||||
svcs := make([]string, 0, len(tpl))
|
||||
for svc := range tpl {
|
||||
svcs = append(svcs, svc)
|
||||
}
|
||||
sort.Strings(svcs)
|
||||
var diffs []string
|
||||
for _, svc := range svcs {
|
||||
got, ok := observed[svc]
|
||||
if !ok {
|
||||
continue // completeness was already checked
|
||||
}
|
||||
if got.Ref != tpl[svc] {
|
||||
diffs = append(diffs, fmt.Sprintf("%s runs %s, template offers %s", svc, got.Ref, tpl[svc]))
|
||||
}
|
||||
}
|
||||
return strings.Join(diffs, "; ")
|
||||
}
|
||||
|
||||
// CatalogTemplatePath is where the syncer's git clone keeps one app's template. It is the ONLY
|
||||
// definition of that layout outside the syncer, and the badge and the update path both use it.
|
||||
func (m *Manager) CatalogTemplatePath(appName, filename string) string {
|
||||
return filepath.Join(m.cfg.Paths.DataDir, "catalog-cache", "templates", appName, filename)
|
||||
}
|
||||
|
||||
// advancePinToCatalog moves a PINNED app onto the catalog's current definition: it writes the
|
||||
// catalog template over the live compose file, records the new pin, and stores that definition as
|
||||
// the applied one. Called by UpdateStack BEFORE the pull — see the comment at that call site.
|
||||
//
|
||||
// AN UNPINNED APP IS LEFT ALONE AND THIS RETURNS NIL. It behaves exactly as it did before v0.235.0:
|
||||
// the syncer has already copied the catalog verbatim into its stack dir, so `pull` + `up -d` do
|
||||
// today's job with no help from here.
|
||||
func (m *Manager) advancePinToCatalog(name, stackDir string) error {
|
||||
cfg := LoadAppConfig(stackDir)
|
||||
if cfg == nil || len(cfg.PinnedImages) == 0 {
|
||||
return nil // unpinned — today's behaviour, unchanged
|
||||
}
|
||||
|
||||
src := m.CatalogTemplatePath(name, "docker-compose.yml")
|
||||
pin, data, err := PinFromCompose(src)
|
||||
if err != nil {
|
||||
// REFUSE rather than silently update to the frozen definition (which would be a no-op
|
||||
// reported as success). Names the cause so the operator is not left guessing.
|
||||
return fmt.Errorf("cannot read the catalog's current definition for %s (%s): %w", name, src, err)
|
||||
}
|
||||
|
||||
live := ComposePathIn(stackDir)
|
||||
if err := StoreAppliedDefinition(stackDir, data); err != nil {
|
||||
return fmt.Errorf("storing the new applied definition for %s: %w", name, err)
|
||||
}
|
||||
if err := os.WriteFile(live, data, 0o644); err != nil {
|
||||
return fmt.Errorf("rendering the catalog definition for %s: %w", name, err)
|
||||
}
|
||||
|
||||
cfg.PinnedImages = pin
|
||||
meta := LoadMetadata(stackDir)
|
||||
if err := SaveAppConfig(stackDir, cfg, m.encKey, SensitiveEnvVars(&meta)); err != nil {
|
||||
return fmt.Errorf("recording the advanced pin for %s: %w", name, err)
|
||||
}
|
||||
m.mu.Lock()
|
||||
if st, ok := m.stacks[name]; ok && st.AppConfig != nil {
|
||||
st.AppConfig.PinnedImages = pin
|
||||
}
|
||||
m.mu.Unlock()
|
||||
|
||||
m.logger.Printf("[INFO] [stacks] update %s: pin advanced to the catalog's current definition (%s)", name, summarisePin(pin))
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,334 @@
|
||||
package stacks
|
||||
|
||||
import (
|
||||
"context"
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"io"
|
||||
"log"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"gitea.dooplex.hu/admin/felhom-controller/internal/config"
|
||||
"gopkg.in/yaml.v3"
|
||||
)
|
||||
|
||||
// Slice 3 (v0.235.0) — the pin, the stored definition, and adoption.
|
||||
|
||||
const pinTplOld = "services:\n web:\n image: nextcloud:31.0.14-apache\n"
|
||||
const pinTplNew = "services:\n web:\n image: nextcloud:34.0.1-apache\n"
|
||||
|
||||
// newPinManager builds a Manager with one deployed stack and a catalog cache.
|
||||
func newPinManager(t *testing.T, liveCompose, catalogCompose, appYAML string) (*Manager, string) {
|
||||
t.Helper()
|
||||
root := t.TempDir()
|
||||
cfg := &config.Config{}
|
||||
cfg.Paths.StacksDir = filepath.Join(root, "stacks")
|
||||
cfg.Paths.DataDir = filepath.Join(root, "data")
|
||||
stackDir := filepath.Join(cfg.Paths.StacksDir, "nextcloud")
|
||||
catDir := filepath.Join(cfg.Paths.DataDir, "catalog-cache", "templates", "nextcloud")
|
||||
for _, d := range []string{stackDir, catDir} {
|
||||
if err := os.MkdirAll(d, 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
mustWrite(t, filepath.Join(stackDir, "docker-compose.yml"), liveCompose)
|
||||
if catalogCompose != "" {
|
||||
mustWrite(t, filepath.Join(catDir, "docker-compose.yml"), catalogCompose)
|
||||
}
|
||||
mustWrite(t, filepath.Join(stackDir, "app.yaml"), appYAML)
|
||||
|
||||
m := &Manager{
|
||||
cfg: cfg, logger: log.New(io.Discard, "", 0), composeCmd: "docker compose",
|
||||
encKey: []byte("0123456789abcdef0123456789abcdef"),
|
||||
stacks: map[string]*Stack{},
|
||||
}
|
||||
m.stacks["nextcloud"] = &Stack{
|
||||
Name: "nextcloud", Deployed: true,
|
||||
ComposePath: filepath.Join(stackDir, "docker-compose.yml"),
|
||||
AppConfig: LoadAppConfig(stackDir),
|
||||
}
|
||||
return m, stackDir
|
||||
}
|
||||
|
||||
func mustWrite(t *testing.T, path, body string) {
|
||||
t.Helper()
|
||||
if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func readPin(t *testing.T, dir string) *AppConfig {
|
||||
t.Helper()
|
||||
b, err := os.ReadFile(filepath.Join(dir, "app.yaml"))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
cfg := &AppConfig{}
|
||||
if err := yaml.Unmarshal(b, cfg); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return cfg
|
||||
}
|
||||
|
||||
// --- GROUP D: the Update button advances the pin, BEFORE the pull ---
|
||||
|
||||
// TestGroupD_UpdateAdvancesThePinAndRendersTheNewDefinition.
|
||||
//
|
||||
// The ordering is the assertion that matters: `compose pull` and `up -d` act on the file on disk, so
|
||||
// the catalog's definition has to BE that file before either runs. A pin set afterwards would pull
|
||||
// the frozen version and report success — a button that lies.
|
||||
func TestGroupD_UpdateAdvancesThePinAndRendersTheNewDefinition(t *testing.T) {
|
||||
m, stackDir := newPinManager(t, pinTplOld, pinTplNew,
|
||||
"deployed: true\nenv: {}\npinned_images:\n web: nextcloud:31.0.14-apache\n")
|
||||
mustWrite(t, AppliedComposePath(stackDir), pinTplOld)
|
||||
|
||||
if err := m.advancePinToCatalog("nextcloud", stackDir); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got := readPin(t, stackDir).PinnedImages["web"]; got != "nextcloud:34.0.1-apache" {
|
||||
t.Fatalf("pin = %q, want the catalog's current ref", got)
|
||||
}
|
||||
live, _ := os.ReadFile(filepath.Join(stackDir, "docker-compose.yml"))
|
||||
if !strings.Contains(string(live), "34.0.1-apache") {
|
||||
t.Fatalf("the LIVE compose file must carry the new definition BEFORE the pull:\n%s", live)
|
||||
}
|
||||
applied, _ := os.ReadFile(AppliedComposePath(stackDir))
|
||||
if !strings.Contains(string(applied), "34.0.1-apache") {
|
||||
t.Fatalf("the new definition must be stored as the applied one:\n%s", applied)
|
||||
}
|
||||
}
|
||||
|
||||
// TestGroupD_UpdateRefusesWhenTheCatalogCannotBeRead — a no-op reported as success is worse than a
|
||||
// refusal. An UNPINNED app is untouched and returns nil: that is pre-v0.235.0 behaviour.
|
||||
func TestGroupD_UpdateRefusesWhenTheCatalogCannotBeRead(t *testing.T) {
|
||||
m, stackDir := newPinManager(t, pinTplOld, "", // no catalog template at all
|
||||
"deployed: true\nenv: {}\npinned_images:\n web: nextcloud:31.0.14-apache\n")
|
||||
err := m.advancePinToCatalog("nextcloud", stackDir)
|
||||
if err == nil {
|
||||
t.Fatal("a pinned app whose catalog definition cannot be read must REFUSE, not silently no-op")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "catalog") {
|
||||
t.Errorf("the refusal must name the cause, got: %v", err)
|
||||
}
|
||||
|
||||
m2, dir2 := newPinManager(t, pinTplOld, "", "deployed: true\nenv: {}\n") // unpinned
|
||||
if err := m2.advancePinToCatalog("nextcloud", dir2); err != nil {
|
||||
t.Fatalf("an UNPINNED app must be left alone and succeed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// --- GROUP E: adoption never guesses ---
|
||||
|
||||
// TestGroupE_AdoptionSkipsWhatItCannotPinConfidently.
|
||||
//
|
||||
// COMPANION RED-PROOF 2 (run 2026-09-06): delete the observationCoversTemplate guard from AdoptPins
|
||||
// so it pins from whatever it observed. The "incomplete observation" sub-test then fails with a pin
|
||||
// written from a partial reading. Reverted.
|
||||
func TestGroupE_AdoptionSkipsWhatItCannotPinConfidently(t *testing.T) {
|
||||
twoSvc := "services:\n web:\n image: nextcloud:31.0.14-apache\n db:\n image: postgres:16-alpine\n"
|
||||
|
||||
t.Run("incomplete observation", func(t *testing.T) {
|
||||
m, stackDir := newPinManager(t, twoSvc, twoSvc, `deployed: true
|
||||
env: {}
|
||||
installed_images:
|
||||
web:
|
||||
ref: nextcloud:31.0.14-apache
|
||||
digest: sha256:a
|
||||
at: "2026-09-01T00:00:00Z"
|
||||
`)
|
||||
m.stacks["nextcloud"].AppConfig = LoadAppConfig(stackDir)
|
||||
if n := m.AdoptPins(); n != 0 {
|
||||
t.Fatalf("pinned %d, want 0 — only 1 of 2 services was observed", n)
|
||||
}
|
||||
if got := readPin(t, stackDir).PinnedImages; len(got) != 0 {
|
||||
t.Fatalf("no pin may be synthesised from a partial observation, got %+v", got)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("complete but running something the template no longer offers", func(t *testing.T) {
|
||||
m, stackDir := newPinManager(t, pinTplNew, pinTplNew, `deployed: true
|
||||
env: {}
|
||||
installed_images:
|
||||
web:
|
||||
ref: nextcloud:31.0.14-apache
|
||||
digest: sha256:a
|
||||
at: "2026-09-01T00:00:00Z"
|
||||
`)
|
||||
m.stacks["nextcloud"].AppConfig = LoadAppConfig(stackDir)
|
||||
if n := m.AdoptPins(); n != 0 {
|
||||
t.Fatalf("pinned %d, want 0 — we have no stored definition for what it runs", n)
|
||||
}
|
||||
if got := readPin(t, stackDir).PinnedImages; len(got) != 0 {
|
||||
t.Fatalf("no pin may be invented here, got %+v", got)
|
||||
}
|
||||
if _, err := os.Stat(AppliedComposePath(stackDir)); err == nil {
|
||||
t.Fatal("no applied definition may be manufactured by substituting refs into a newer template")
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("complete and matching — pinned, with the definition stored", func(t *testing.T) {
|
||||
m, stackDir := newPinManager(t, pinTplOld, pinTplOld, `deployed: true
|
||||
env: {}
|
||||
installed_images:
|
||||
web:
|
||||
ref: nextcloud:31.0.14-apache
|
||||
digest: sha256:a
|
||||
at: "2026-09-01T00:00:00Z"
|
||||
`)
|
||||
m.stacks["nextcloud"].AppConfig = LoadAppConfig(stackDir)
|
||||
if n := m.AdoptPins(); n != 1 {
|
||||
t.Fatalf("pinned %d, want 1", n)
|
||||
}
|
||||
if got := readPin(t, stackDir).PinnedImages["web"]; got != "nextcloud:31.0.14-apache" {
|
||||
t.Fatalf("pin = %q", got)
|
||||
}
|
||||
stored, err := LoadAppliedDefinition(stackDir)
|
||||
if err != nil || !strings.Contains(string(stored), "31.0.14-apache") {
|
||||
t.Fatalf("the running definition must be stored: %v %s", err, stored)
|
||||
}
|
||||
// Idempotent: a second pass must not re-pin.
|
||||
if n := m.AdoptPins(); n != 0 {
|
||||
t.Errorf("a second adoption pass pinned %d, want 0", n)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
// TestGroupE_AdoptionTouchesNoContainer — it reads and writes files only.
|
||||
func TestGroupE_AdoptionTouchesNoContainer(t *testing.T) {
|
||||
m, stackDir := newPinManager(t, pinTplOld, pinTplOld, `deployed: true
|
||||
env: {}
|
||||
installed_images:
|
||||
web:
|
||||
ref: nextcloud:31.0.14-apache
|
||||
digest: sha256:a
|
||||
at: "2026-09-01T00:00:00Z"
|
||||
`)
|
||||
m.stacks["nextcloud"].AppConfig = LoadAppConfig(stackDir)
|
||||
m.installedExecFn = func(context.Context, string, []string, string, ...string) (string, error) {
|
||||
t.Fatal("adoption must not run any docker command")
|
||||
return "", nil
|
||||
}
|
||||
m.execFn = func(string, ...string) (string, error) {
|
||||
t.Fatal("adoption must not run any docker command")
|
||||
return "", nil
|
||||
}
|
||||
m.AdoptPins()
|
||||
}
|
||||
|
||||
// --- GROUP F: a restore's pin survives, and RenderPlanFor reports it ---
|
||||
|
||||
// TestGroupF_RestorePinIsReportedToTheSyncer is the unit half of R-441. The live half is the
|
||||
// measurement in the report; this pins the contract the syncer relies on.
|
||||
func TestGroupF_RestorePinIsReportedToTheSyncer(t *testing.T) {
|
||||
m, stackDir := newPinManager(t, pinTplOld, pinTplNew, "deployed: true\nenv: {}\n")
|
||||
|
||||
// What RecreateStackDefinitionFromUnit does: the unit's compose is already in the stack dir.
|
||||
pin, data, err := PinFromCompose(ComposePathIn(stackDir))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := m.SetPin("nextcloud", stackDir, pin, data); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
plan := m.RenderPlanFor("nextcloud")
|
||||
if !plan.Deployed || len(plan.Pinned) == 0 {
|
||||
t.Fatalf("the syncer must be told the app is deployed and pinned: %+v", plan)
|
||||
}
|
||||
if plan.Pinned["web"] != "nextcloud:31.0.14-apache" {
|
||||
t.Errorf("pin = %q, want the unit's captured image", plan.Pinned["web"])
|
||||
}
|
||||
if plan.AppliedPath == "" {
|
||||
t.Fatal("the stored definition must be reported, or the syncer cannot freeze and the catalog wins in 15 minutes (R-441)")
|
||||
}
|
||||
}
|
||||
|
||||
// TestSetPin_EmptyPinAndMissingAppYAMLAreRefusedOrNoOps.
|
||||
func TestSetPin_EmptyPinAndMissingAppYAMLAreRefusedOrNoOps(t *testing.T) {
|
||||
m, stackDir := newPinManager(t, pinTplOld, pinTplOld, "deployed: true\nenv: {}\n")
|
||||
if err := m.SetPin("nextcloud", stackDir, map[string]string{}, []byte(pinTplOld)); err == nil {
|
||||
t.Error("an empty pin must be refused — it would read as UNPINNED and silently unfreeze the app")
|
||||
}
|
||||
if err := StoreAppliedDefinition(stackDir, nil); err == nil {
|
||||
t.Error("an empty applied definition must be refused")
|
||||
}
|
||||
}
|
||||
|
||||
// TestSetPin_UnchangedPinDoesNotRewriteAppYAML — app.yaml holds encrypted secrets.
|
||||
func TestSetPin_UnchangedPinDoesNotRewriteAppYAML(t *testing.T) {
|
||||
m, stackDir := newPinManager(t, pinTplOld, pinTplOld,
|
||||
"deployed: true\nenv: {}\npinned_images:\n web: nextcloud:31.0.14-apache\n")
|
||||
p := filepath.Join(stackDir, "app.yaml")
|
||||
st0, _ := os.Stat(p)
|
||||
if err := m.SetPin("nextcloud", stackDir, map[string]string{"web": "nextcloud:31.0.14-apache"}, []byte(pinTplOld)); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
st1, _ := os.Stat(p)
|
||||
if !st0.ModTime().Equal(st1.ModTime()) || st0.Size() != st1.Size() {
|
||||
t.Error("an unchanged pin must not rewrite app.yaml")
|
||||
}
|
||||
}
|
||||
|
||||
// --- GROUP H: the wiring ---
|
||||
|
||||
// TestGroupH_RenderSeamAndAdoptionAreWiredAtStartup.
|
||||
//
|
||||
// The render is INERT unless main.go passes the function, and adoption is inert unless it is called.
|
||||
// An AST walk, NOT a strings.Contains: a commented-out call still contains the string, which is the
|
||||
// exact shape of the seam-built-but-never-wired class this project has shipped four times.
|
||||
//
|
||||
// It also asserts the ORDER, which is load-bearing: syncer.Start() fires an immediate sync, and if
|
||||
// that runs before adoption every app is still unpinned, so the first sync of every boot would copy
|
||||
// the catalog verbatim over a deployed app — the behaviour this release removes, once per boot.
|
||||
func TestGroupH_RenderSeamAndAdoptionAreWiredAtStartup(t *testing.T) {
|
||||
src := filepath.Join("..", "..", "cmd", "controller", "main.go")
|
||||
fset := token.NewFileSet()
|
||||
f, err := parser.ParseFile(fset, src, nil, 0)
|
||||
if err != nil {
|
||||
t.Skipf("cmd/controller is gitignored in some checkouts: %v", err)
|
||||
}
|
||||
var seamLine, adoptLine, startLine, backfillLine int
|
||||
ast.Inspect(f, func(n ast.Node) bool {
|
||||
call, ok := n.(*ast.CallExpr)
|
||||
if !ok {
|
||||
return true
|
||||
}
|
||||
sel, ok := call.Fun.(*ast.SelectorExpr)
|
||||
if !ok {
|
||||
return true
|
||||
}
|
||||
line := fset.Position(call.Pos()).Line
|
||||
switch sel.Sel.Name {
|
||||
case "SetRenderPlanFn":
|
||||
seamLine = line
|
||||
case "AdoptPins":
|
||||
adoptLine = line
|
||||
case "BackfillInstalledImages":
|
||||
backfillLine = line
|
||||
case "Start":
|
||||
if id, ok := sel.X.(*ast.Ident); ok && id.Name == "syncer" {
|
||||
startLine = line
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
if seamLine == 0 {
|
||||
t.Fatal("SetRenderPlanFn is never called from cmd/controller — the render is INERT and the syncer copies verbatim")
|
||||
}
|
||||
if adoptLine == 0 {
|
||||
t.Fatal("AdoptPins is never called from cmd/controller — nothing would ever be pinned")
|
||||
}
|
||||
if backfillLine != 0 && adoptLine < backfillLine {
|
||||
t.Errorf("adoption (line %d) must run AFTER the installed-images backfill (line %d) — it needs that observation", adoptLine, backfillLine)
|
||||
}
|
||||
if startLine == 0 {
|
||||
t.Fatal("syncer.Start() is never called")
|
||||
}
|
||||
if startLine < adoptLine {
|
||||
t.Errorf("syncer.Start() (line %d) must come AFTER AdoptPins (line %d): the initial sync would otherwise run while every app is unpinned and overwrite a deployed app's version once per boot", startLine, adoptLine)
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user