Files
felhom-controller/controller/internal/backup/offbox_ended.go
T
admin f628cb5082
gates / gates (push) Successful in 41s
The off-site copies of a removed app end 30 days after „delete backup data” — the box's half (felhom.eu R-1374 part 1; D72, D84)
Built, not released; no box has run it. felhom.eu `07-backup-architecture.md` §8.2f.
It does nothing without a hub that knows it: an older hub agrees to no id.

- The record: settings `offsite_ends` {app, removed_at, ends_at}. One writer
  (backup.StartOffsiteEnd), called by a removal only with „delete backup data”
  and by „Törlés 30 nap múlva” on the restore page. A second press changes
  nothing. No record, no deletion. Only on the hub-provisioned tier.
- The date is on the remove dialog before the press; the restore page shows
  „Törlésre kijelölve …” with „Mégis megtartom”, and one history line per
  carried-out end. An install of the same app deletes the record.
- The weekly window: after the guard has passed the policy's plan under the cap
  as before, it adds the snapshots whose app tags are ALL due records, that the
  hub agreed to and the box named in the same request; the result names them
  apart (removed_for_ended_apps). `_shares`, the box's own stacks and an
  installed app are never due.
- The report carries the pending records; the household gets one mail per
  press (offsite_end_scheduled), in both languages.

MinAgent unchanged (0.158.1). 143 parity fixtures gained the dialog's one new
script line (patched, not regenerated); one new parity case.
Tests TestD72_*, TestD84_*; 56 mutations seen red
(felhom.eu documentation/audits/build-release-4-2026-11-15/A/redproof-ctrl-*.txt).

Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
2026-11-15 14:09:47 +01:00

258 lines
11 KiB
Go

package backup
import (
"errors"
"sort"
"time"
"gitea.dooplex.hu/admin/felhom-controller/internal/settings"
)
// D72 / D84 (`09` §3 decisions 292 and 309; `07-backup-architecture.md` §8.2f, parts 3 and 4) — THE OFF-SITE COPIES OF
// A REMOVED APP END 30 DAYS AFTER „DELETE BACKUP DATA”, IN THE WEEKLY WINDOW AND NOWHERE ELSE.
//
// What this file adds to the clean-up window (offbox_window.go) and what it must never do:
//
// - NO RECORD, NO DELETION. Only an off-site end record (settings.OffsiteEnd, written by the household's press)
// that is DUE makes a snapshot a candidate. A removal that kept the backups, a rebuilt guest, an app removed
// before this existed: there is no record, so there is no candidate.
// - A LIVING APP'S COPY IS NEVER REMOVED BY ANOTHER APP'S END. A snapshot is a candidate only when EVERY app tag
// it carries belongs to a due record — a snapshot with two apps' tags stays until both have ended. The shares
// pseudo-app (`_shares`), the infrastructure stacks and an app that is installed right now are never due.
// - THE HUB AGREES FIRST. The candidates go to the hub with the window request; the box removes ONLY the ids the
// hub sends back (OffsiteWindow.EndedAllowed) — and of those, only ids it named itself in this same window.
// A hub that does not know this (an older hub) sends none, and then nothing of an ended app is removed.
// - ONE GUARD, NO SECOND PATH. The fake-snapshot guard runs first, on the whole repository and on the policy's own
// plan under the window's cap, exactly as before. If it refuses, the ended apps wait with everything else.
// The ended ids are OUTSIDE the cap (D84) and are named apart in the result (removed_for_ended_apps), so the
// hub's 07:10 audit can explain them.
// OffsiteEndedClaim is one due end record as the box sends it with the window request: the app, the record's own
// dates (the hub does not decide by them) and the snapshot ids the box would remove.
type OffsiteEndedClaim struct {
App string `json:"app"`
RemovedAt string `json:"removed_at"`
EndsAt string `json:"ends_at"`
SnapshotIDs []string `json:"snapshot_ids"`
}
// OffsiteEndedRefusal is one refusal the hub sent back, in its own words (logged).
type OffsiteEndedRefusal struct {
App string `json:"app"`
Reason string `json:"reason"`
}
// OffsiteEndedApp is one pending end record on the hub report (`offsite.ended_apps`): it lets the hub start its own
// clock for an app it never saw installed (`07` §8.2f part 4). The dates are the box's; the hub decides by its own.
type OffsiteEndedApp struct {
App string `json:"app"`
RemovedAt string `json:"removed_at"`
EndsAt string `json:"ends_at"`
}
// SetOffsiteEndLiving wires "is this app installed on this box right now, or one of the box's own protected stacks".
// An app for which it answers true is never due. NOT WIRED (nil) = NOTHING IS DUE: a box that cannot tell what it
// runs must not delete any app's history. Wired in cmd/controller/main.go; pinned by TestD72_MainWiresTheLivingCheck.
func (m *Manager) SetOffsiteEndLiving(fn func(app string) bool) { m.offsiteEndLiving = fn }
// appTags returns a snapshot's app tags: every tag but the tier's marker.
func appTags(s guardSnap) []string {
var out []string
for _, t := range s.Tags {
if t != "" && t != OffboxMarkerTag {
out = append(out, t)
}
}
return out
}
// dueOffsiteEnds is the PURE first half: the records that may be claimed now. living == nil → none.
func dueOffsiteEnds(ends []settings.OffsiteEnd, now time.Time, living func(string) bool) map[string]settings.OffsiteEnd {
due := map[string]settings.OffsiteEnd{}
if living == nil {
return due
}
for _, e := range ends {
if !settings.ValidOffsiteEndApp(e.App) || e.App == SharesPseudoStack || !e.Due(now) || living(e.App) {
continue
}
due[e.App] = e
}
return due
}
// endedCandidates is the PURE second half: from the repository's snapshots and the due records, the claims to send
// (sorted by app; an app with no candidate is not claimed) and the set of candidate ids.
//
// A snapshot is a candidate only when it carries at least one app tag, EVERY app tag it carries is a due record,
// and it is not younger than any of those records' removal (a snapshot made under that tag AFTER the removal is not
// the removed app's copy — a later install's, or a planted one).
func endedCandidates(snaps []guardSnap, due map[string]settings.OffsiteEnd) (claims []OffsiteEndedClaim, candidate map[string]bool) {
candidate = map[string]bool{}
byApp := map[string][]string{}
for _, s := range snaps {
apps := appTags(s)
if len(apps) == 0 || s.ID == "" {
continue
}
ok := true
for _, a := range apps {
e, isDue := due[a]
if !isDue || s.Time.After(e.Removed().Add(offsiteGuardSkew)) {
ok = false
break
}
}
if !ok {
continue
}
candidate[s.ID] = true
for _, a := range apps {
byApp[a] = append(byApp[a], s.ID)
}
}
for app, ids := range byApp {
sort.Strings(ids)
e := due[app]
claims = append(claims, OffsiteEndedClaim{App: app, RemovedAt: e.RemovedAt, EndsAt: e.EndsAt, SnapshotIDs: ids})
}
sort.Slice(claims, func(i, j int) bool { return claims[i].App < claims[j].App })
return claims, candidate
}
// endedToRemove is the PURE third half: of the ids the hub agreed to, those the box itself named as candidates in
// this window and that the policy's own plan does not already remove (those stay under the cap). Sorted.
func endedToRemove(allowed []string, candidate map[string]bool, policyIDs []string) []string {
inPolicy := make(map[string]bool, len(policyIDs))
for _, id := range policyIDs {
inPolicy[id] = true
}
seen := map[string]bool{}
var out []string
for _, id := range allowed {
if candidate[id] && !inPolicy[id] && !seen[id] {
seen[id] = true
out = append(out, id)
}
}
sort.Strings(out)
return out
}
// appStillInStore reports whether any snapshot still carries app's tag.
func appStillInStore(snaps []guardSnap, app string) bool {
for _, s := range snaps {
for _, t := range s.Tags {
if t == app {
return true
}
}
}
return false
}
// dropEndsWithNoCopies deletes the due records of apps that have NO snapshot in the repository at all: there is
// nothing to end, and a record that can never complete would be asked of the hub every week for ever. It writes no
// history line (nothing was deleted). Called only after a listing that succeeded.
func (m *Manager) dropEndsWithNoCopies(snaps []guardSnap, due map[string]settings.OffsiteEnd) {
for app, e := range due {
if appStillInStore(snaps, app) {
continue
}
if done, err := m.settings.CompleteOffsiteEnd(app, e.RemovedAt, m.now(), 0); err != nil {
m.logger.Printf("[WARN] [offbox] ended app %s: the store holds no copy of it, but its end record could not be closed: %v", app, err)
} else if done {
m.logger.Printf("[INFO] [offbox] ended app %s: the off-site store holds no copy of it — its end record is closed, nothing was deleted", app)
}
delete(due, app)
}
}
// completeOffsiteEnds closes the record of every app whose copies this window removed: at least one of its claimed
// ids is gone and no snapshot carries its tag any more. An app that still has a snapshot (one shared with a living
// app, or one the hub did not agree to) keeps its record and is asked again at the next window.
func (m *Manager) completeOffsiteEnds(claims []OffsiteEndedClaim, removed []string, after []guardSnap) {
gone := make(map[string]bool, len(removed))
for _, id := range removed {
gone[id] = true
}
for _, c := range claims {
n := 0
for _, id := range c.SnapshotIDs {
if gone[id] {
n++
}
}
if n == 0 || appStillInStore(after, c.App) {
continue
}
if _, err := m.settings.CompleteOffsiteEnd(c.App, c.RemovedAt, m.now(), n); err != nil {
m.logger.Printf("[WARN] [offbox] ended app %s: its %d off-site snapshot(s) are removed, but the end record could not be closed: %v", c.App, n, err)
}
}
}
// OffsiteEndedAppsForReport returns the pending end records for the hub report.
func (m *Manager) OffsiteEndedAppsForReport() []OffsiteEndedApp {
var out []OffsiteEndedApp
for _, e := range m.settings.GetOffsiteEnds() {
out = append(out, OffsiteEndedApp{App: e.App, RemovedAt: e.RemovedAt, EndsAt: e.EndsAt})
}
return out
}
// ── The household's side: the press, the take-back, the date ────────────────────────────────────────────────────────
// ErrOffsiteEndNotOffered: this box has no hub-provisioned off-site tier, so there is no weekly window that could
// carry the deletion out — and no record is written. (The household's own NAS target is pruned by the box itself and
// keeps a removed app's copies, as before: `07` §8.2f.)
var ErrOffsiteEndNotOffered = errors.New("no hub-provisioned off-site tier on this box")
// ErrOffsiteEndLiving: the app is installed right now, is one of the box's own stacks, or the box cannot tell.
var ErrOffsiteEndLiving = errors.New("the app is installed or is not an app a household removes")
// OffsiteEndOffered reports whether a press can start the 30 days here: the box has the hub-provisioned tier
// (switched on or not — a tier that is off only makes the deletion wait).
func (m *Manager) OffsiteEndOffered() bool {
return m != nil && m.settings != nil && m.settings.GetOffboxTarget().Pinned()
}
// SetOffsiteEndNotify wires the household's one mail per press (D84).
func (m *Manager) SetOffsiteEndNotify(fn func(rec settings.OffsiteEnd)) { m.offsiteEndNotify = fn }
// OffsiteEndDateIfPressedNow is the date the remove dialog shows BEFORE the press.
func (m *Manager) OffsiteEndDateIfPressedNow() time.Time {
return m.now().Add(settings.OffsiteEndAfter)
}
// StartOffsiteEnd is THE press: „delete backup data” at a removal, or „delete in 30 days” on the Backups page. It
// writes the end record and tells the household once. A second press for the same app changes nothing and tells
// nobody (created == false). The ONLY writer of an end record.
func (m *Manager) StartOffsiteEnd(app string) (rec settings.OffsiteEnd, created bool, err error) {
if !m.OffsiteEndOffered() {
return settings.OffsiteEnd{}, false, ErrOffsiteEndNotOffered
}
if !settings.ValidOffsiteEndApp(app) || app == SharesPseudoStack || m.offsiteEndLiving == nil || m.offsiteEndLiving(app) {
return settings.OffsiteEnd{}, false, ErrOffsiteEndLiving
}
rec, created, err = m.settings.StartOffsiteEnd(app, m.now())
if err != nil || !created {
return rec, false, err
}
if m.offsiteEndNotify != nil {
m.offsiteEndNotify(rec)
}
return rec, true, nil
}
// KeepOffsiteCopies is „keep it after all”: it deletes the end record. Returns whether there was one.
func (m *Manager) KeepOffsiteCopies(app string) (bool, error) {
return m.settings.CancelOffsiteEnd(app, "the household keeps the copies")
}
// PendingOffsiteEnds and OffsiteEndsHistory are what the Backups page shows.
func (m *Manager) PendingOffsiteEnds() []settings.OffsiteEnd { return m.settings.GetOffsiteEnds() }
func (m *Manager) OffsiteEndsHistory() []settings.OffsiteEndDone {
return m.settings.GetOffsiteEndsDone()
}