Files
felhom-controller/controller/internal/settings/offsite_ends.go
T
admin c5acb91a44
gates / gates (push) Successful in 32s
Review fix 5: the box sends its end records only to a hub that says it reads them (version skew)
A new box with an older hub sent `ended` in the window request; that hub reads
4 KiB of it, decided the window on a wrong count, and the weekly clean-up
stalled.

- The box sends `ended` only when the hub's last window answer said
  accepts_ended (kept in settings, re-read from every answer, so a rolled-back
  hub stops getting them after one answer). Otherwise the request is the one
  every hub always got, and the ordinary clean-up runs.
- One request carries at most 5000 snapshot ids.

Tests seen red before the fix; 6 mutations seen red (felhom.eu
documentation/audits/build-release-4-2026-11-15/A/redproof-review-5.txt).

Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
2026-11-15 15:05:38 +01:00

191 lines
7.3 KiB
Go

package settings
import (
"fmt"
"sort"
"strings"
"time"
)
// D72 / D84 (`09` §3 decisions 292 and 309; `07-backup-architecture.md` §8.2f, part 1) — THE OFF-SITE END RECORD.
//
// When the household removes an app and presses „delete backup data”, the local backups go at once and the app's
// OFF-SITE copies end 30 days later. This record is the whole of that promise on the box:
//
// NO RECORD = NO DELETION, EVER.
//
// It is written only by StartOffsiteEnd (the household's press), deleted by CancelOffsiteEnd („keep it after all”,
// and every install of the same app), and moved to the short history by CompleteOffsiteEnd when a clean-up window
// has removed the copies. Nothing else starts, moves or shortens the clock. It lives in settings.json, so it
// survives a controller restart; a rebuilt guest has none, and then the copies stay (the safe direction).
// OffsiteEndAfter is how long the off-site copies of a removed app stay (D72: the number of a restore copy, D62).
const OffsiteEndAfter = 30 * 24 * time.Hour
// OffsiteEnd is one pending end record.
type OffsiteEnd struct {
App string `json:"app"`
RemovedAt string `json:"removed_at"` // RFC3339, the moment of the press
EndsAt string `json:"ends_at"` // RFC3339, RemovedAt + OffsiteEndAfter
}
// Removed and Ends parse the record's dates; a date that cannot be read is the zero time, and a record with a zero
// date is never due (OffsiteEndDue).
func (e OffsiteEnd) Removed() time.Time { t, _ := time.Parse(time.RFC3339, e.RemovedAt); return t }
func (e OffsiteEnd) Ends() time.Time { t, _ := time.Parse(time.RFC3339, e.EndsAt); return t }
// Due reports whether the record's day has come by this box's clock. The HUB decides by its own clock whether it
// agrees (`07` §8.2f part 4); this is only when the box starts to ask. The end is never earlier than
// RemovedAt + OffsiteEndAfter, whatever EndsAt says (a hand-edited or damaged record cannot shorten the wait).
func (e OffsiteEnd) Due(now time.Time) bool {
removed, ends := e.Removed(), e.Ends()
if removed.IsZero() || ends.IsZero() {
return false
}
if min := removed.Add(OffsiteEndAfter); ends.Before(min) {
ends = min
}
return !now.Before(ends)
}
// OffsiteEndDone is one line of history: the off-site copies of App were removed by a clean-up window.
type OffsiteEndDone struct {
App string `json:"app"`
RemovedAt string `json:"removed_at"`
DeletedAt string `json:"deleted_at"` // RFC3339
Snapshots int `json:"snapshots"`
}
// maxOffsiteEndsDone bounds the history list.
const maxOffsiteEndsDone = 20
// ValidOffsiteEndApp: a name an end record may carry. The shares pseudo-app (`_shares`), the tier's marker tag and
// anything that is not a plain stack name are never eligible (`07` §8.2f, the edge-case table). Whether the name is
// a PROTECTED infrastructure stack is the caller's check — settings does not know the stack list.
func ValidOffsiteEndApp(app string) bool {
return app != "" && app != "." && app != ".." && !strings.HasPrefix(app, "_") && app != "felhom-offbox" &&
!strings.ContainsAny(app, "/\\ \t\n")
}
// StartOffsiteEnd writes the end record for app at now. created is false when a record already exists: a second
// press changes NOTHING — not the date, and the caller sends no second mail.
func (s *Settings) StartOffsiteEnd(app string, now time.Time) (rec OffsiteEnd, created bool, err error) {
if !ValidOffsiteEndApp(app) {
return OffsiteEnd{}, false, fmt.Errorf("offsite end: %q is not an app a household removes", app)
}
s.mu.Lock()
defer s.mu.Unlock()
if cur, ok := s.OffsiteEnds[app]; ok {
return cur, false, nil
}
now = now.UTC().Truncate(time.Second)
rec = OffsiteEnd{App: app, RemovedAt: now.Format(time.RFC3339), EndsAt: now.Add(OffsiteEndAfter).Format(time.RFC3339)}
if s.OffsiteEnds == nil {
s.OffsiteEnds = map[string]OffsiteEnd{}
}
s.OffsiteEnds[app] = rec
if err := s.save(); err != nil {
delete(s.OffsiteEnds, app) // a record that is not on disk is not a record
return OffsiteEnd{}, false, err
}
if s.log != nil {
s.log.Printf("[INFO] [settings] off-site end record WRITTEN for %s: removed %s, its off-site copies end %s (D72)", app, rec.RemovedAt, rec.EndsAt)
}
return rec, true, nil
}
// CancelOffsiteEnd deletes app's end record („keep it after all”, or an install of the same app). Returns whether a
// record existed. why is for the log.
func (s *Settings) CancelOffsiteEnd(app, why string) (bool, error) {
s.mu.Lock()
defer s.mu.Unlock()
cur, ok := s.OffsiteEnds[app]
if !ok {
return false, nil
}
delete(s.OffsiteEnds, app)
if err := s.save(); err != nil {
s.OffsiteEnds[app] = cur
return false, err
}
if s.log != nil {
s.log.Printf("[INFO] [settings] off-site end record DELETED for %s (%s) — its off-site copies are kept (was: ends %s)", app, why, cur.EndsAt)
}
return true, nil
}
// GetOffsiteEnd returns app's pending end record.
func (s *Settings) GetOffsiteEnd(app string) (OffsiteEnd, bool) {
s.mu.RLock()
defer s.mu.RUnlock()
e, ok := s.OffsiteEnds[app]
return e, ok
}
// GetOffsiteEnds returns the pending end records, by app name.
func (s *Settings) GetOffsiteEnds() []OffsiteEnd {
s.mu.RLock()
defer s.mu.RUnlock()
out := make([]OffsiteEnd, 0, len(s.OffsiteEnds))
for _, e := range s.OffsiteEnds {
out = append(out, e)
}
sort.Slice(out, func(i, j int) bool { return out[i].App < out[j].App })
return out
}
// CompleteOffsiteEnd moves app's record to the history after a clean-up window removed its copies. The record is
// keyed on the app AND its removed_at (`07` §8.2f): a record that was deleted or written anew since the window read
// it is NOT completed. Returns whether it was.
func (s *Settings) CompleteOffsiteEnd(app, removedAt string, deletedAt time.Time, snapshots int) (bool, error) {
s.mu.Lock()
defer s.mu.Unlock()
cur, ok := s.OffsiteEnds[app]
if !ok || cur.RemovedAt != removedAt {
return false, nil
}
delete(s.OffsiteEnds, app)
prevDone := s.OffsiteEndsDone
if snapshots > 0 {
done := append([]OffsiteEndDone{{App: app, RemovedAt: removedAt, DeletedAt: deletedAt.UTC().Format(time.RFC3339), Snapshots: snapshots}}, s.OffsiteEndsDone...)
if len(done) > maxOffsiteEndsDone {
done = done[:maxOffsiteEndsDone]
}
s.OffsiteEndsDone = done
}
if err := s.save(); err != nil {
s.OffsiteEnds[app], s.OffsiteEndsDone = cur, prevDone
return false, err
}
if s.log != nil {
s.log.Printf("[INFO] [settings] off-site end record COMPLETED for %s: %d snapshot(s) removed", app, snapshots)
}
return true, nil
}
// GetOffsiteEndsDone returns the history, newest first.
func (s *Settings) GetOffsiteEndsDone() []OffsiteEndDone {
s.mu.RLock()
defer s.mu.RUnlock()
return append([]OffsiteEndDone(nil), s.OffsiteEndsDone...)
}
// OffsiteHubAcceptsEnded: did the hub's LAST window answer say that it reads end records (`accepts_ended`)? Kept in
// settings so a controller restart does not cost a week: the box sends its end records only to a hub that said so.
func (s *Settings) GetOffsiteHubAcceptsEnded() bool {
s.mu.RLock()
defer s.mu.RUnlock()
return s.OffsiteHubAcceptsEnded
}
// SetOffsiteHubAcceptsEnded records the hub's last answer; it writes only on a change.
func (s *Settings) SetOffsiteHubAcceptsEnded(v bool) error {
s.mu.Lock()
defer s.mu.Unlock()
if s.OffsiteHubAcceptsEnded == v {
return nil
}
s.OffsiteHubAcceptsEnded = v
return s.save()
}