Files
felhom.eu/hub/internal/store/offsite_ended.go
T

489 lines
20 KiB
Go

package store
import (
"database/sql"
"encoding/json"
"fmt"
"sort"
"strings"
"sync"
"time"
)
// D72 / D84 (`09` §3 decisions 292 and 309; `07-backup-architecture.md` §8.2f part 4) — THE HUB'S OWN RECORD of which
// apps a box runs, kept by the hub's clock. A box may ask a clean-up window to remove the off-site snapshots of an app
// the household removed 30 days ago; the hub agrees only when THIS table says the app has been absent from that box's
// reported app list for 30 days. The box's own dates are never read for that.
//
// One row per (household, app) the hub has seen in a report's `stacks.deployed`, or that the box named in a pending
// end record. `absent_since` is the hub's time of the FIRST report that did not list the app; it is cleared the moment
// a report lists the app again (an install ends every claim). Rows go with the household (residueQueries,
// orphanTables).
// migrateOffsiteEnded creates the presence table and the three window columns. Idempotent.
func (s *Store) migrateOffsiteEnded() error {
if _, err := s.db.Exec(`
CREATE TABLE IF NOT EXISTS offsite_app_presence (
customer_id TEXT NOT NULL,
app TEXT NOT NULL,
absent_since TEXT,
PRIMARY KEY (customer_id, app)
);`); err != nil {
return fmt.Errorf("offsite_app_presence: %w", err)
}
// What the hub agreed to at the open, what it refused, and what the box then named as removed (only ids the hub
// agreed to are kept). JSON text; NULL on every window that had no ended app.
s.db.Exec("ALTER TABLE offsite_windows ADD COLUMN ended_agreed TEXT")
s.db.Exec("ALTER TABLE offsite_windows ADD COLUMN ended_refused TEXT")
s.db.Exec("ALTER TABLE offsite_windows ADD COLUMN ended_removed TEXT")
// 1 on a row that exists ONLY because the box named the app in an end record (the hub never saw it installed).
s.db.Exec("ALTER TABLE offsite_app_presence ADD COLUMN claim_born INTEGER NOT NULL DEFAULT 0")
if _, err := s.db.Exec(`
CREATE TABLE IF NOT EXISTS offsite_large_requests (
customer_id TEXT NOT NULL,
set_key TEXT NOT NULL,
first_seen TEXT NOT NULL,
PRIMARY KEY (customer_id, set_key)
);`); err != nil {
return fmt.Errorf("offsite_large_requests: %w", err)
}
s.db.Exec("ALTER TABLE offsite_windows ADD COLUMN ended_apps TEXT") // agreed app → its agreed ids (the per-app record)
return nil
}
// AppPresence is the hub's record of one app on one box.
type AppPresence struct {
// Present: the newest report lists the app.
Present bool
// AbsentSince is the hub's time of the first report without the app (zero while Present).
AbsentSince time.Time
// ClaimBorn: the hub never saw this app in the box's app list — the row exists only because the box named the
// app in a pending end record. The operator was warned when it appeared (NoteAppListClaims).
ClaimBorn bool
}
// A box's lists are the box's own word, so the record is bounded three ways (security review of 2026-11-15):
//
// 1. ONE REPORT may name at most maxPresenceApps apps in each list.
// 2. A NAME is stored only when it has the shape of an app name (ValidPresenceApp) and is not reserved
// (ReservedPresenceApp: the shares pseudo-app, the tier's marker, the box's own infrastructure stacks).
// 3. ONE HOUSEHOLD holds at most maxPresenceRows rows. A new name above that first takes the place of the oldest
// ABSENT row that the same report does not name in a pending end record; when there is no such row the new name
// is not stored, and the hub says so in its log once per household (not per report).
//
// THERE IS NO AGE LIMIT ON A ROW, on purpose. An absent row is what makes a real ended app eligible exactly 30 days
// after the hub saw it leave; a row that aged out would start that clock again at the next claim — LATER than the
// household was told. So a row leaves only with the household (PurgeCustomerResidue, PurgeOrphanRows), by an install
// of the app (it becomes present), or by rule 3. Rule 3 can never make an app eligible EARLIER: an evicted app has no
// row, a claim for it starts a new clock at that moment, and 30 days are counted from there. It can make one LATER —
// only for a household that has passed maxPresenceRows names AND whose report did not carry the claim (its off-site
// tier was off). A row is ~60 bytes; 400 rows per household is the whole cost.
const (
maxPresenceApps = 300
maxPresenceRows = 400
maxPresenceName = 64
// maxUnseenClaimsTold: how many never-seen apps of ONE household the operator is warned about (one mail each).
// A box that invents more names is already eight warnings loud; the rest are stored and not mailed.
maxUnseenClaimsTold = 8
)
// UnseenClaim is an app a box named in a pending end record that the hub never saw in the box's app list — told to
// the operator once, at the moment the row is made.
type UnseenClaim struct {
App string
AbsentSince time.Time // the hub's clock starts here; it could agree EndedAppAfter later
}
// ValidPresenceApp: the shape of an app (stack) name — 1..64 of letters, digits, `.`, `_`, `-`, starting with a
// letter or a digit. Anything else a box sends is not stored and can never be agreed.
func ValidPresenceApp(app string) bool {
if app == "" || len(app) > maxPresenceName {
return false
}
for i, r := range app {
switch {
case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9':
case i > 0 && (r == '.' || r == '_' || r == '-'):
default:
return false
}
}
return true
}
// reservedPresenceApps are names that are never an app a household removes: the tier's marker tag and the box's own
// infrastructure stacks (the controller's protected list: `controller.yaml.default` plus its always-protected
// `samba`). The shares pseudo-app `_shares` is refused by its shape already (ValidPresenceApp).
var reservedPresenceApps = map[string]bool{
"felhom-offbox": true, "traefik": true, "cloudflared": true, "felhom-controller": true, "filebrowser": true,
"samba": true, "felhom-samba": true,
}
// ReservedPresenceApp reports a reserved name (case does not matter, as on the box).
func ReservedPresenceApp(app string) bool { return reservedPresenceApps[strings.ToLower(app)] }
// NoteAppList updates the record from ONE report: `deployed` is the report's app list, `claimed` the apps the box
// names in pending off-site end records. now is the HUB's clock.
//
// - an app in `deployed` is present (its absence, if any, is forgotten);
// - an app the hub knew as present and that is not in `deployed` is absent since now;
// - a claimed app the hub has NO row for and that is not in `deployed` gets a row, absent since now — the hub's
// clock for an app removed before the hub kept this record starts when the hub first hears the claim, never at a
// date the box names.
//
// It writes only when something changes, so a steady box costs one read per report.
func (s *Store) NoteAppList(customerID string, deployed, claimed []string, now time.Time) error {
_, err := s.NoteAppListClaims(customerID, deployed, claimed, now)
return err
}
// NoteAppListClaims is NoteAppList, and returns the never-seen apps this report named for the FIRST time (review of
// 2026-11-15): the caller warns the operator about each, 30 days before the hub could agree to anything for it. An
// app is returned once — when its row is made — and at most maxUnseenClaimsTold such rows per household are told.
func (s *Store) NoteAppListClaims(customerID string, deployed, claimed []string, now time.Time) (unseen []UnseenClaim, err error) {
if customerID == "" {
return nil, fmt.Errorf("NoteAppList: empty customer_id")
}
if len(deployed) > maxPresenceApps {
deployed = deployed[:maxPresenceApps]
}
if len(claimed) > maxPresenceApps {
claimed = claimed[:maxPresenceApps]
}
cur, err := s.AppPresences(customerID)
if err != nil {
return nil, err
}
stamp := now.UTC().Format(time.RFC3339)
in := make(map[string]bool, len(deployed))
isClaimed := make(map[string]bool, len(claimed))
for _, app := range claimed {
isClaimed[app] = true
}
type change struct {
app string
absent sql.NullString
claimBorn bool
}
var changes, added []change // changes touch a row that exists; added need a NEW row (rule 3)
for _, app := range deployed {
if !ValidPresenceApp(app) || ReservedPresenceApp(app) || in[app] {
continue
}
in[app] = true
if p, ok := cur[app]; !ok {
added = append(added, change{app: app})
} else if !p.Present {
changes = append(changes, change{app: app})
}
}
for app, p := range cur {
if p.Present && !in[app] {
changes = append(changes, change{app: app, absent: sql.NullString{String: stamp, Valid: true}})
}
}
seen := map[string]bool{}
for _, app := range claimed {
if !ValidPresenceApp(app) || ReservedPresenceApp(app) || in[app] || seen[app] {
continue
}
seen[app] = true
if _, ok := cur[app]; !ok {
added = append(added, change{app: app, absent: sql.NullString{String: stamp, Valid: true}, claimBorn: true})
}
}
// Rule 3: the household's row limit. Room is made only from absent rows this report does not claim, oldest first.
var evict []string
refusedNew := 0
if over := len(cur) + len(added) - maxPresenceRows; over > 0 {
type old struct {
app string
since time.Time
}
var free []old
for app, p := range cur {
if !p.Present && !in[app] && !isClaimed[app] {
free = append(free, old{app, p.AbsentSince})
}
}
sort.Slice(free, func(i, j int) bool {
if !free[i].since.Equal(free[j].since) {
return free[i].since.Before(free[j].since)
}
return free[i].app < free[j].app
})
for i := 0; i < len(free) && i < over; i++ {
evict = append(evict, free[i].app)
}
if short := over - len(evict); short > 0 {
refusedNew = short
added = added[:len(added)-short] // the report's app list first, then its claims: the tail goes
}
}
s.notePresenceFull(customerID, refusedNew, len(evict))
// The never-seen apps to tell: the rows made now for a claim, while the household holds fewer than the limit.
bornBefore := 0
evicted := make(map[string]bool, len(evict))
for _, app := range evict {
evicted[app] = true
}
for app, p := range cur {
if p.ClaimBorn && !evicted[app] {
bornBefore++
}
}
for _, c := range added {
if c.claimBorn && bornBefore+len(unseen) < maxUnseenClaimsTold {
unseen = append(unseen, UnseenClaim{App: c.app, AbsentSince: now.UTC()})
}
}
changes = append(changes, added...)
if len(changes) == 0 && len(evict) == 0 {
return nil, nil
}
tx, err := s.db.Begin()
if err != nil {
return nil, err
}
defer tx.Rollback()
for _, app := range evict {
if _, err := tx.Exec(`DELETE FROM offsite_app_presence WHERE customer_id = ? AND app = ?`, customerID, app); err != nil {
return nil, fmt.Errorf("NoteAppList %s/%s: %w", customerID, app, err)
}
}
for _, c := range changes {
// claim_born is set only on a row made for a claim, and cleared the moment a report lists the app: an app
// the hub has seen installed is an ordinary app from then on.
born := 0
if c.claimBorn {
born = 1
} else if p, ok := cur[c.app]; ok && p.ClaimBorn && c.absent.Valid {
born = 1
}
if _, err := tx.Exec(`INSERT INTO offsite_app_presence (customer_id, app, absent_since, claim_born) VALUES (?, ?, ?, ?)
ON CONFLICT(customer_id, app) DO UPDATE SET absent_since = excluded.absent_since, claim_born = excluded.claim_born`, customerID, c.app, c.absent, born); err != nil {
return nil, fmt.Errorf("NoteAppList %s/%s: %w", customerID, c.app, err)
}
}
if err := tx.Commit(); err != nil {
return nil, err
}
return unseen, nil
}
// presenceFull remembers, per household, that the row limit was said in the log — so a box that sends new names in
// every report gives ONE line, not one per report. In memory: a hub restart says it once more.
var (
presenceFullMu sync.Mutex
presenceFull = map[string]bool{}
)
func (s *Store) notePresenceFull(customerID string, refusedNew, evicted int) {
presenceFullMu.Lock()
defer presenceFullMu.Unlock()
if refusedNew == 0 && evicted == 0 {
delete(presenceFull, customerID)
return
}
if presenceFull[customerID] {
return
}
presenceFull[customerID] = true
if s.logger != nil {
s.logger.Printf("[WARN] offsite app record for %s is at its limit of %d names: this report took the place of %d old absent name(s) and %d new name(s) were NOT stored. A box does not run that many apps — look at what it reports. (Said once; not repeated per report.)",
customerID, maxPresenceRows, evicted, refusedNew)
}
}
// AppPresences returns the hub's record for one household, by app.
func (s *Store) AppPresences(customerID string) (map[string]AppPresence, error) {
rows, err := s.db.Query(`SELECT app, absent_since, claim_born FROM offsite_app_presence WHERE customer_id = ?`, customerID)
if err != nil {
return nil, err
}
defer rows.Close()
out := map[string]AppPresence{}
for rows.Next() {
var app string
var absent sql.NullString
var born sql.NullInt64
if err := rows.Scan(&app, &absent, &born); err != nil {
return nil, err
}
p := AppPresence{Present: !absent.Valid || absent.String == "", ClaimBorn: born.Int64 == 1}
if !p.Present {
// A date that cannot be read stays the zero time, and the caller REFUSES an absent app with a zero
// AbsentSince: an unreadable date is never "absent long ago".
if t, perr := time.Parse(time.RFC3339, absent.String); perr == nil {
p.AbsentSince = t
}
}
out[app] = p
}
return out, rows.Err()
}
// EndedRefusal is one app the hub refused in a window, with the reason in plain words.
type EndedRefusal struct {
App string `json:"app"`
Reason string `json:"reason"`
}
// SetOffsiteWindowEnded records, on the window's own row, the snapshot ids the hub agreed to for ended apps and the
// apps it refused. Called once, at the open.
func (s *Store) SetOffsiteWindowEnded(id int64, agreed []string, byApp map[string][]string, refused []EndedRefusal) error {
var a, r, m sql.NullString
if len(byApp) > 0 {
b, _ := json.Marshal(byApp)
m = sql.NullString{String: string(b), Valid: true}
}
if len(agreed) > 0 {
b, _ := json.Marshal(agreed)
a = sql.NullString{String: string(b), Valid: true}
}
if len(refused) > 0 {
b, _ := json.Marshal(refused)
r = sql.NullString{String: string(b), Valid: true}
}
_, err := s.db.Exec(`UPDATE offsite_windows SET ended_agreed = ?, ended_refused = ?, ended_apps = ? WHERE id = ?`, a, r, m, id)
return err
}
// SetOffsiteWindowEndedRemoved records which agreed ids the box named as removed. The caller passes only ids the hub
// agreed to; this function checks it again against the row, so an id the hub never agreed to can not be stored.
func (s *Store) SetOffsiteWindowEndedRemoved(id int64, removed []string) ([]string, error) {
w, err := s.GetOffsiteWindow(id)
if err != nil || w == nil {
return nil, fmt.Errorf("SetOffsiteWindowEndedRemoved: window %d: %v", id, err)
}
ok := make(map[string]bool, len(w.EndedAgreed))
for _, a := range w.EndedAgreed {
ok[a] = true
}
var kept []string
dup := map[string]bool{}
for _, r := range removed {
if ok[r] && !dup[r] {
dup[r] = true
kept = append(kept, r)
}
}
sort.Strings(kept)
var v sql.NullString
if len(kept) > 0 {
b, _ := json.Marshal(kept)
v = sql.NullString{String: string(b), Valid: true}
}
if _, err := s.db.Exec(`UPDATE offsite_windows SET ended_removed = ? WHERE id = ?`, v, id); err != nil {
return nil, err
}
return kept, nil
}
func jsonStrings(v sql.NullString) []string {
if !v.Valid || v.String == "" {
return nil
}
var out []string
if json.Unmarshal([]byte(v.String), &out) != nil {
return nil
}
return out
}
// THE HUB'S OWN FIRST SIGHT OF A LARGE REQUEST (security review of 2026-11-15). A request to remove more than half of
// a store for removed apps waits a week after the hub first saw it (offsitekeys). That first sight is kept HERE, in a
// table only the hub writes: (household, a key of the app set, first_seen). It was first found by searching the
// windows' refusal text — text that also held names a box had claimed, so a box could plant its own „first sight”.
// No box-supplied text is searched any more.
// maxLargeRequestRows bounds one household's rows: a box can ask for many app sets.
const maxLargeRequestRows = 50
// LargeEndedRequestFirstSeen returns when the hub first saw this household ask for this app set in a large request,
// if that was after `since` (zero time: never, or too long ago — the request then waits again).
func (s *Store) LargeEndedRequestFirstSeen(customerID, key string, since time.Time) time.Time {
var v sql.NullString
if err := s.db.QueryRow(`SELECT first_seen FROM offsite_large_requests WHERE customer_id = ? AND set_key = ?`, customerID, key).Scan(&v); err != nil || !v.Valid {
return time.Time{}
}
t, err := time.Parse(time.RFC3339, v.String)
if err != nil || t.Before(since) {
return time.Time{}
}
return t
}
// NoteLargeEndedRequest records the hub's first sight (now) of this app set — replacing a sight that is older than
// the caller's memory is the caller's choice: it calls this only when LargeEndedRequestFirstSeen answered „never”.
// A household holds at most maxLargeRequestRows rows; the oldest go first.
func (s *Store) NoteLargeEndedRequest(customerID, key string, now time.Time) error {
if customerID == "" || key == "" {
return fmt.Errorf("NoteLargeEndedRequest: empty household or key")
}
tx, err := s.db.Begin()
if err != nil {
return err
}
defer tx.Rollback()
if _, err := tx.Exec(`INSERT INTO offsite_large_requests (customer_id, set_key, first_seen) VALUES (?, ?, ?)
ON CONFLICT(customer_id, set_key) DO UPDATE SET first_seen = excluded.first_seen`, customerID, key, now.UTC().Format(time.RFC3339)); err != nil {
return err
}
if _, err := tx.Exec(`DELETE FROM offsite_large_requests WHERE customer_id = ? AND set_key NOT IN (
SELECT set_key FROM offsite_large_requests WHERE customer_id = ? ORDER BY first_seen DESC, set_key LIMIT ?)`, customerID, customerID, maxLargeRequestRows); err != nil {
return err
}
return tx.Commit()
}
// BackdateLargeEndedRequestsForTest moves a household's first sights into the past. TEST-ONLY.
func (s *Store) BackdateLargeEndedRequestsForTest(customerID string, by time.Duration) error {
rows, err := s.db.Query(`SELECT set_key, first_seen FROM offsite_large_requests WHERE customer_id = ?`, customerID)
if err != nil {
return err
}
type row struct{ key, at string }
var all []row
for rows.Next() {
var r row
if err := rows.Scan(&r.key, &r.at); err != nil {
rows.Close()
return err
}
all = append(all, r)
}
rows.Close()
for _, r := range all {
t, perr := time.Parse(time.RFC3339, r.at)
if perr != nil {
continue
}
if _, err := s.db.Exec(`UPDATE offsite_large_requests SET first_seen = ? WHERE customer_id = ? AND set_key = ?`, t.Add(-by).Format(time.RFC3339), customerID, r.key); err != nil {
return err
}
}
return nil
}
// CountCustomerSentSince counts the mails of one type the hub's own log says were SENT to a household since `since`.
func (s *Store) CountCustomerSentSince(customerID, eventType string, since time.Time) (int, error) {
return s.countCustomerLog(customerID, eventType, since, `status = 'sent'`)
}
// CountCustomerTriesSince counts every try of one type that REACHED the mail service for a household since `since`
// — `sent` and `failed` (the notice's daily limit; it survives a hub restart, which a counter in memory would not).
// A try that failed is counted because „failed” is what the hub saw, not what the mail service did: a send that
// timed out on the hub's side may have gone (review of 2026-11-15, finding 2). A held mail never reached the
// service and is not counted.
func (s *Store) CountCustomerTriesSince(customerID, eventType string, since time.Time) (int, error) {
return s.countCustomerLog(customerID, eventType, since, `status IN ('sent', 'failed')`)
}
func (s *Store) countCustomerLog(customerID, eventType string, since time.Time, status string) (int, error) {
var n int
err := s.db.QueryRow(`SELECT COUNT(*) FROM notification_log WHERE customer_id = ? AND event_type = ? AND channel = 'customer' AND `+status+` AND created_at >= ?`,
customerID, eventType, since.UTC().Format("2006-01-02 15:04:05")).Scan(&n)
return n, err
}