v0.168.0: customer-configurable backup window (Mentési időablak)

ONE setting (window start W) drives every nightly leg at fixed, never-stored
offsets: DB dump at W, tier-2 at W+60m, off-box at W+105m (wrap-safe). Precedence
settings > controller.yaml db_dump_schedule > 02:30.

- scheduler.UpdateDaily: retime a daily job at runtime (no restart) via a per-job
  buffered resched chan + a select case in runDailyJob.
- new pure package internal/backupwindow (LegTimes/GateWindow/EffectiveWindow).
- quiesce disk-tier window gate: scheduled cycles run only inside [W+2h,W+6h) with a
  safety valve (age>cadence+24h runs regardless); manual TriggerNow never gated.
  Backend.Due now also returns the backup age (from the agent's own /backup/due).
- backup page: Mentési időablak card (time input + derived leg/gate rows); POST
  /backups/window validates -> saves -> UpdateDaily x3 -> flash.

Tests: 5 groups, all red-proofed. Agent/cadence//backup/due untouched.

controller/internal/quiesce/quiesce.go

@@ -20,6 +20,8 @@ import (
 	"path/filepath"
 	"sync"
 	"time"
+
+	"gitea.dooplex.hu/admin/felhom-controller/internal/backupwindow"
 )
 
 // ErrBackupInProgress is returned by TriggerNow when a scheduled or manual quiesce cycle is already
@@ -27,9 +29,11 @@ import (
 var ErrBackupInProgress = errors.New("quiesce: a backup cycle is already in progress")
 
 // Backend is the agent local-API surface the loop needs (satisfied by an adapter over
-// *agentapi.Client). Kept minimal (bool/string) so the loop is testable with plain fakes.
+// *agentapi.Client). Kept minimal (bool/int/string) so the loop is testable with plain fakes.
+// Due also returns the age of the newest successful backup in seconds (nil = none yet) — the
+// window gate's safety valve reads it so a box powered on only outside its window never starves.
 type Backend interface {
-	Due(ctx context.Context) (bool, error)
+	Due(ctx context.Context) (due bool, ageSecs *int64, err error)
 	StartBackup(ctx context.Context) (jobID string, err error)
 	BackupStatus(ctx context.Context) (phase string, err error)
 }
@@ -68,6 +72,13 @@ type Options struct {
 	StatusPoll time.Duration // how often to poll /backup/status while quiesced
 	MaxQuiesce time.Duration // hard bound on app downtime (unquiesce no matter what)
 	Logger     *log.Logger
+	// WindowStartFn returns the CURRENT effective backup-window start "HH:MM" (customer-configurable,
+	// so it is read fresh each poll — a window change must take effect without restart). When nil the
+	// window gate is disabled and a due cycle runs whenever the agent says due (pre-v0.168.0 behavior).
+	WindowStartFn func() string
+	// Cadence is the agent's backup cadence, used only by the gate's safety valve (run regardless of
+	// the window once the last successful backup is older than Cadence+24h). Defaults to 24h.
+	Cadence time.Duration
 }
 
 // Loop is the quiesce background loop.
@@ -80,6 +91,9 @@ type Loop struct {
 	maxQuiesce time.Duration
 	logger     *log.Logger
 	now        func() time.Time
+	// windowStartFn (nil = gate disabled) + cadence drive the scheduled-cycle window gate (Part 3).
+	windowStartFn func() string
+	cadence       time.Duration
 	// mu single-flights the quiesce cycle across the scheduled loop AND the manual trigger, so the
 	// two can never stop the same stacks concurrently (the persisted marker covers crash-safety across
 	// restarts; this covers concurrency within the process — which a manual trigger introduces).
@@ -100,10 +114,14 @@ func New(o Options) *Loop {
 	if o.Logger == nil {
 		o.Logger = log.Default()
 	}
+	if o.Cadence <= 0 {
+		o.Cadence = 24 * time.Hour
+	}
 	return &Loop{
 		backend: o.Backend, stacks: o.Stacks, markerPath: o.MarkerPath,
 		poll: o.Poll, statusPoll: o.StatusPoll, maxQuiesce: o.MaxQuiesce,
 		logger: o.Logger, now: time.Now,
+		windowStartFn: o.WindowStartFn, cadence: o.Cadence,
 	}
 }
 
@@ -159,7 +177,7 @@ func (l *Loop) runOnce(ctx context.Context) error {
 		return nil
 	}
 
-	due, err := l.backend.Due(ctx)
+	due, ageSecs, err := l.backend.Due(ctx)
 	if err != nil {
 		return fmt.Errorf("check due: %w", err)
 	}
@@ -167,6 +185,17 @@ func (l *Loop) runOnce(ctx context.Context) error {
 		return nil
 	}
 
+	// Window gate (Part 3) — SCHEDULED path only. TriggerNow calls quiesceAndPoll directly and is
+	// never gated. Disabled when no window fn is wired (pre-v0.168.0 behavior).
+	if l.windowStartFn != nil {
+		window := l.windowStartFn()
+		if !scheduledRunAllowed(l.now().In(budapestLocation()), window, ageSecs, l.cadence) {
+			from, to := gateBounds(window)
+			l.logger.Printf("[DEBUG] [quiesce] scheduled backup due but outside the backup window [%s–%s) — deferring to the next poll inside it", from, to)
+			return nil
+		}
+	}
+
 	return l.quiesceAndPoll(ctx)
 }
 
@@ -286,6 +315,63 @@ func (l *Loop) quiesceAndPoll(ctx context.Context) error {
 	}
 }
 
+// ---- window gate (Part 3, v0.168.0) -----------------------------------------------------
+
+var (
+	quiesceBudapest     *time.Location
+	quiesceBudapestOnce sync.Once
+)
+
+func budapestLocation() *time.Location {
+	quiesceBudapestOnce.Do(func() {
+		loc, err := time.LoadLocation("Europe/Budapest")
+		if err != nil {
+			quiesceBudapest = time.UTC
+			return
+		}
+		quiesceBudapest = loc
+	})
+	return quiesceBudapest
+}
+
+const (
+	gateOpenOffsetMin = 120 // gate opens at W+2h
+	gateSpanMin       = 240 // 4h span → [W+2h, W+6h)
+)
+
+// scheduledRunAllowed decides whether a DUE, scheduled whole-guest backup may run at `now` (passed by
+// the caller as Budapest wall-clock — only its hour/minute are read). True when now is inside the gate
+// window [W+2h, W+6h); otherwise true ONLY if the safety valve holds — the newest successful backup is
+// missing (nil) or older than cadence+24h — so a box powered on only outside its window never starves.
+// An unparseable window fails OPEN (allow) rather than block backups forever.
+func scheduledRunAllowed(now time.Time, windowStart string, lastAgeSecs *int64, cadence time.Duration) bool {
+	startMin, err := backupwindow.ParseHHMM(windowStart)
+	if err != nil {
+		return true
+	}
+	nowMin := now.Hour()*60 + now.Minute()
+	if within(nowMin, mod1440(startMin+gateOpenOffsetMin), gateSpanMin) {
+		return true
+	}
+	// Outside the window: only the safety valve may run it.
+	if lastAgeSecs == nil {
+		return true // no recorded backup yet — never withhold the first one
+	}
+	return time.Duration(*lastAgeSecs)*time.Second > cadence+24*time.Hour
+}
+
+// gateBounds returns the gate window [W+2h, W+6h) as HH:MM for the deferral log line.
+func gateBounds(windowStart string) (from, to string) {
+	return backupwindow.GateWindow(windowStart)
+}
+
+func mod1440(m int) int { return ((m % 1440) + 1440) % 1440 }
+
+// within reports whether minute-of-day p falls in [start, start+span) modulo 24h (wrap-safe).
+func within(p, start, span int) bool {
+	return mod1440(p-start) < span
+}
+
 func (l *Loop) restartAll(stacks []string) {
 	for _, s := range stacks {
 		if err := l.stacks.StartStack(s); err != nil {