From 772d956e5e6ecb865807e113b201671a8bc5060e Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:10:43 +0200 Subject: [PATCH] feat: ask less often: settle time, a "nothing to apply" check exit, and one more question after a wait MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - [limits] settle: a tip is checked and asked only when root has seen it unchanged for this long (its own clock, kept as tip_since in the state). - check exit 3: "nothing to apply on this host". The tip is marked nothing, no message is sent, and the applied SHA stays. In the broken state exit 3 is a failed check with its notice. - [limits] reask_after: in ask mode a skipped or expired tip is asked once more when its mark is this old. It counts against questions_per_day. - pullgate status shows "settling until …" and the nothing mark. Closes #41 except the release box. Co-Authored-By: Claude Opus 5.5 --- DESIGN.md | 52 ++- README.md | 5 +- THREAT-MODEL.md | 24 +- contrib/examples/ansible/playbooks.toml | 2 + contrib/examples/config-file/config-repo.toml | 2 + internal/config/config.go | 12 + internal/config/config_test.go | 15 +- internal/gate/apply.go | 2 +- internal/gate/askless_test.go | 349 ++++++++++++++++++ internal/gate/check.go | 19 +- internal/gate/fixture_test.go | 1 + internal/gate/run.go | 92 ++++- internal/gate/status.go | 28 +- internal/listener/listener.go | 2 +- internal/state/state.go | 4 + 15 files changed, 588 insertions(+), 21 deletions(-) create mode 100644 internal/gate/askless_test.go diff --git a/DESIGN.md b/DESIGN.md index c92799a..8da7744 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -192,6 +192,8 @@ max_files = 100000 # default 100000 files in one tree max_tree_bytes = 1073741824 # default 1 GiB in one tree allow_older = false # default false (rule 5) refuse_symlinks = false # default false; true refuses a commit with a symlink that points out of the tree +settle = "30m" # default 0 (ask at once); ask only when the tip has not changed for this long, at most 168h +reask_after = "24h" # default 0 (never); ask a skipped or expired tip once more after this time (ask mode) [listener] user = "pullgate" # the user of the listener; owns the inbox @@ -315,10 +317,30 @@ used again. ("the branch is back to the applied commit"). - tip = the SHA of the open question: nothing to do. - tip is the held SHA, or was asked before and the question expired or - was skipped, or its check failed, or it was refused, or it failed - `max_failed_tries` times: nothing to do. `pullgate status NAME - --ask-again` clears this mark, and also closes an open question for - the tip (section 13). + was skipped, or its check failed, or it was refused, or its check + said "nothing to apply" (step 7), or it failed `max_failed_tries` + times: nothing to do. `pullgate status NAME --ask-again` clears this + mark, and also closes an open question for the tip (section 13). + - **`reask_after`** (default 0, off): in `ask` mode, a tip marked + skipped or expired is asked + once more when its mark is at least `reask_after` old and it is still + the tip. Asking sets the mark to asked; a second Skip or expiry sets + a new mark time, so the next ask comes only after the next wait. It + counts against `questions_per_day` like every question. `auto` mode + has no Skip, so `reask_after` does nothing there. + - **`settle`** (default 0, off): root keeps in its state the time it + first saw the tip (`tip_since`). A new tip, or a clock that went back + before that time, starts it again. While the tip is younger than + `settle`, the run logs "settling" and stops: no check, no question, + no notice. So three merges in ten minutes give one question, for the + last one, and a writer cannot keep moving the branch to make the + owner tap without reading. It also holds in `auto` mode. The time is + root's own: the commit date is written by the writer and is not + trusted. An open question for an older tip stays open while the new + tip settles: it is closed only when the new tip is asked (step 9), as + today while the new tip is checked. A state file from a version + before `settle` has no `tip_since`; the first run sets it to now, so + the tip it knew waits one settle time (fail closed). - tip is not a descendant of the applied SHA (an older commit, a force push, a rewritten branch) and `allow_older` is false: refuse. Send one notice for this SHA and mark it refused. When `allow_older` is true, @@ -328,7 +350,15 @@ used again. send one notice per day, and do not ask. 6. Export the tree of the tip, and the tree of the applied SHA (`PULLGATE_OLD_TREE`). -7. Run `check` as `check_user` (section 11). If it fails, mark the SHA +7. Run `check` as `check_user` (section 11). If it exits with status + **3**, the commit has nothing to apply on this host (for example only + docs, or files for other hosts): mark the SHA `nothing`, send no + message, and do not ask. The applied SHA stays as it is, so the next + question still lists every commit since the last real apply, and its + check and summary still compare with the last applied tree. In the + broken state (section 10) exit 3 is a failed check with its notice, + so the owner sees that a fix forward was not asked. Any other + non-zero status, a timeout or a signal is a failed check. If it fails, mark the SHA "check failed", send a notice with the end of its output, and do not ask. The same SHA is not checked again. In that output the tree paths (`PULLGATE_TREE`, `PULLGATE_OLD_TREE`) become `NEW` and `OLD`. The @@ -684,7 +714,9 @@ Their working directory is `PULLGATE_TREE`. Their umask is 022. Each has a timeo (`check_timeout`, `apply_timeout`); on timeout the whole process group is killed and the command counts as failed. pullgate keeps at most 64 KiB of their output. The output of `apply` and `health` goes to the journal; the -report shows only the exit status. The output of `check` (its last lines) +report shows only the exit status. `check` exits 0 to pass, 3 for +"nothing to apply on this host" (section 7, step 7), and anything else to +fail. The output of `check` (its last lines) and of `summary` goes into Telegram messages, after the cleaning of section 12. @@ -775,11 +807,13 @@ closed after a cut. - `off`: `pullgate run` and `pullgate apply` do nothing. `pullgate status NAME` prints the mode, the applied SHA, the open question, -the held SHA, the broken state ("broken since …, last error …"), the pause -file and an apply in progress. Flags: +the held SHA, the mark of the last tip (`nothing` reads "nothing (the check +found nothing to apply on this host)"), "settling until …" while the tip +waits for `settle`, the broken state ("broken since …, last error …"), the +pause file and an apply in progress. Flags: - `--ask-again`: clear the marks of the last fetched tip (expired, skipped, - check failed, refused, failed, held), so the next run asks again. If a + check failed, nothing, refused, failed, held), so the next run asks again. If a question for the tip is open (for example its message was lost), root removes it from its state, then asks the listener to close its message. The next run asks again with a new question ID and a new code. An diff --git a/README.md b/README.md index f563b31..593cf27 100644 --- a/README.md +++ b/README.md @@ -282,7 +282,8 @@ deploy_key = "/etc/pullgate/NAME.key" known_hosts = "/etc/pullgate/NAME.known_hosts" [commands] -check = ["/path/to/check"] # optional; runs as check_user; a failure means no question +check = ["/path/to/check"] # optional; runs as check_user; a failure means no question; + # exit 3 means "nothing to apply on this host": no question, no message summary = ["/path/to/summary"] # optional; runs as check_user; its output is in the question apply = ["/path/to/apply"] # required; runs as root after Apply health = ["/path/to/health"] # optional; runs as root after apply @@ -296,6 +297,8 @@ questions_per_day = 10 approval_ttl = "12h" max_failed_tries = 1 allow_older = false +settle = "0" # e.g. "30m": ask only when the branch has not changed for this long +reask_after = "0" # e.g. "24h": ask a skipped or expired commit once more after this time ``` The commands get these environment variables: `PULLGATE_SHA`, diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md index 9b11e1d..27f8ad3 100644 --- a/THREAT-MODEL.md +++ b/THREAT-MODEL.md @@ -323,6 +323,11 @@ A clock that goes back before `asked` denies. A clock that jumps forward expires questions early: this denies too. The listener checks expiry with its own clock as well. Timeouts of commands use the monotonic clock. +`settle` counts from the time root first saw the tip; a clock that goes +back before that time starts the wait again. A clock that is wrong and then +corrected forward can make the wait shorter, like `approval_ttl` above. +That only asks sooner; it never applies anything. + *Left.* A clock that is set far back while a question is open can keep that question valid longer than `approval_ttl`. The code still works only once. @@ -382,7 +387,24 @@ repo URL must pass the same check as the clone, because root runs *Attack.* Someone pushes many commits to tire the owner into tapping Apply. *Defense.* At most one open question per instance; a newer tip replaces it. -`questions_per_day` caps the questions. A SHA is asked once. +`questions_per_day` caps the questions. A SHA is asked once, or once more +per `reask_after` after a Skip or an expiry; each of these counts against +`questions_per_day`. With `settle`, a tip is asked only when root has seen +it unchanged for that long, by root's own clock (not the commit date, which +the writer sets). So a writer who keeps moving the branch gets no question +at all, and the owner always has a question that stays the same while he +reads it. + +*Check exit 3.* `check` runs as `check_user` on the commit's tree, so a +hostile commit can make it exit 3. That only marks the SHA `nothing`: no +question, no apply, and the applied SHA stays. It cannot apply anything, +and it is no worse than a check that fails. The next real commit is asked +with every commit since the last real apply, so nothing is hidden from the +owner. Root takes only the exit status; it reads nothing else from the +check. + +*Left.* A writer can delay a question by pushing more often than `settle`. +That only delays; it never applies. ### T16. A bad release binary diff --git a/contrib/examples/ansible/playbooks.toml b/contrib/examples/ansible/playbooks.toml index cc2fccb..8a5435f 100644 --- a/contrib/examples/ansible/playbooks.toml +++ b/contrib/examples/ansible/playbooks.toml @@ -27,6 +27,8 @@ paths = ["ansible.cfg", "site.yml", "roles/pullgate/**", "**/sudoers*"] [limits] questions_per_day = 10 +settle = "30m" # ask only when the branch has not changed for 30 minutes +reask_after = "24h" # ask a skipped or expired commit once more after a day approval_ttl = "24h" [listener] diff --git a/contrib/examples/config-file/config-repo.toml b/contrib/examples/config-file/config-repo.toml index 1a25214..df3dc91 100644 --- a/contrib/examples/config-file/config-repo.toml +++ b/contrib/examples/config-file/config-repo.toml @@ -26,6 +26,8 @@ paths = ["policy.toml"] [limits] questions_per_day = 10 +settle = "30m" # ask only when the branch has not changed for 30 minutes +reask_after = "24h" # ask a skipped or expired commit once more after a day approval_ttl = "12h" max_failed_tries = 1 diff --git a/internal/config/config.go b/internal/config/config.go index 3f80176..ac00aa0 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -84,6 +84,12 @@ type Limits struct { MaxTreeBytes int64 `toml:"max_tree_bytes"` AllowOlder bool `toml:"allow_older"` RefuseSymlinks bool `toml:"refuse_symlinks"` + // Settle is how long the tip must stay the same before it is checked + // and asked (DESIGN.md section 7). 0 asks at once. + Settle Duration `toml:"settle"` + // ReaskAfter asks a skipped or expired tip once more when its mark is + // this old (DESIGN.md section 7). 0 never asks again. + ReaskAfter Duration `toml:"reask_after"` } // ListenerUser is the [listener] section of an instance. @@ -196,6 +202,12 @@ func (c *Instance) validate() error { if c.Limits.QuestionsPerDay < 0 || c.Limits.MaxFailedTries < 0 || c.Limits.MaxFiles < 0 || c.Limits.MaxTreeBytes < 0 { return c.errf("[limits]", "a limit is below 0. Fix: use a positive number") } + if c.Limits.Settle.Duration < 0 || c.Limits.Settle.Duration > MaxTTL { + return c.errf("[limits] settle", "must be at least 0 and at most 168h. Fix: use a time like \"30m\", or \"0\" to ask at once") + } + if c.Limits.ReaskAfter.Duration < 0 { + return c.errf("[limits] reask_after", "is below 0. Fix: use a time like \"24h\", or \"0\" to never ask again") + } if c.Commands.CheckTimeout.Duration < 0 || c.Commands.ApplyTimeout.Duration < 0 { return c.errf("[commands]", "a timeout is below 0") } diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 6fbf3ae..bc0e71a 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -44,7 +44,7 @@ func TestDefaults(t *testing.T) { t.Fatal(err) } if c.Mode != "ask" || c.OnFailure != "pause" || c.Limits.QuestionsPerDay != 10 || c.Limits.MaxFailedTries != 1 || - c.Limits.ApprovalTTL.Hours() != 12 || c.Limits.AllowOlder || c.Commands.CheckUser != "pullgate-check" { + c.Limits.ApprovalTTL.Hours() != 12 || c.Limits.AllowOlder || c.Limits.Settle.Duration != 0 || c.Limits.ReaskAfter.Duration != 0 || c.Commands.CheckUser != "pullgate-check" { t.Fatalf("defaults: %+v", c) } } @@ -61,6 +61,9 @@ func TestRefused(t *testing.T) { "url as option": strings.Replace(good, "ssh://git@git.example.com/owner/config-repo.git", "--upload-pack=x", 1), "branch option": good + "[repo]\n", "ttl too long": good + "[limits]\napproval_ttl = \"200h\"\n", + "settle too long": good + "[limits]\nsettle = \"200h\"\n", + "settle below 0": good + "[limits]\nsettle = \"-1m\"\n", + "reask below 0": good + "[limits]\nreask_after = \"-1h\"\n", "absolute watch path": good + "[watch]\npaths = [\"/etc/x\"]\n", "host html": `host = ""` + good, } @@ -245,3 +248,13 @@ func TestCheckAPIURL(t *testing.T) { } } } + +func TestSettleAndReask(t *testing.T) { + c, err := Load(write(t, good+"[limits]\nsettle = \"30m\"\nreask_after = \"24h\"\n", 0o600), "x", uid()) + if err != nil { + t.Fatal(err) + } + if c.Limits.Settle.Minutes() != 30 || c.Limits.ReaskAfter.Hours() != 24 { + t.Fatalf("settle %s, reask_after %s", c.Limits.Settle.Duration, c.Limits.ReaskAfter.Duration) + } +} diff --git a/internal/gate/apply.go b/internal/gate/apply.go index 789b37c..03bf8c6 100644 --- a/internal/gate/apply.go +++ b/internal/gate/apply.go @@ -174,7 +174,7 @@ func (e *Env) handle(ctx context.Context, st *state.State, a spool.Approval) (Re if a.Action == "skip" { st.SetMark(q.SHA, state.MarkSkipped, now) e.Log.Info("skipped", "sha", q.SHA) - e.reply(q.ID, "Skipped "+code(q.SHA)+". A new commit asks again.") + e.reply(q.ID, "Skipped "+code(q.SHA)+". "+e.skipHint()) return Skipped, false, e.Dir.Save(st) } r, err := e.applySHA(ctx, st, q) diff --git a/internal/gate/askless_test.go b/internal/gate/askless_test.go new file mode 100644 index 0000000..942e74d --- /dev/null +++ b/internal/gate/askless_test.go @@ -0,0 +1,349 @@ +package gate + +import ( + "strings" + "testing" + "time" + + "github.com/code6x/pullgate/internal/spool" + "github.com/code6x/pullgate/internal/state" +) + +// Tests of code6x/pullgate#41: settle, check exit 3, reask_after. + +func (f *fixture) status() string { + f.t.Helper() + var out strings.Builder + if err := f.env.Status(&out, StatusFlags{}); err != nil { + f.t.Fatal(err) + } + return out.String() +} + +func asks(ms []spool.Message) int { + n := 0 + for _, m := range ms { + if m.Kind == spool.KindAsk { + n++ + } + } + return n +} + +func TestSettleTwoTipsGiveOneQuestionForTheSecond(t *testing.T) { + f := newFixture(t, ``, "[limits]\nsettle = \"30m\"\n") + f.commit("first", "one", nil) + if r := f.run(); r != Settling { + t.Fatalf("first run: %s, want settling", r) + } + if ms := f.outbox(); len(ms) != 0 { + t.Fatalf("a settling run sends nothing: %v", ms) + } + if f.read("check-count") != "" { + t.Fatal("a settling tip is not checked yet") + } + if s := f.status(); !strings.Contains(s, "settling until 2026-11-11 12:30") { + t.Fatalf("status must show the settle time:\n%s", s) + } + f.now = f.now.Add(10 * time.Minute) + second := f.commit("second", "two", nil) + if r := f.run(); r != Settling { + t.Fatalf("a new tip settles again: %s", r) + } + if s := f.status(); !strings.Contains(s, "settling until 2026-11-11 12:40") { + t.Fatalf("the settle time starts again with the new tip:\n%s", s) + } + f.now = f.now.Add(25 * time.Minute) // 35m after the first tip, 25m after the second + if r := f.run(); r != Settling { + t.Fatalf("the second tip has not settled: %s", r) + } + f.now = f.now.Add(5 * time.Minute) + if r := f.run(); r != Asked { + t.Fatalf("the settled tip is asked: %s", r) + } + ms := f.outbox() + if asks(ms) != 1 || !contains(ms, second[:12]) { + t.Fatalf("one question, for the second tip: %v", ms) + } + st := f.state() + if len(st.AskTimes) != 1 || st.Open() == nil || st.Open().SHA != second { + t.Fatalf("one question counts against questions_per_day: %+v", st) + } + if strings.Contains(f.status(), "settling") { + t.Fatal("an asked tip is not settling") + } +} + +func TestSettleTipSeenLongerAgoIsAskedAtOnce(t *testing.T) { + f := newFixture(t, ``, "[limits]\nsettle = \"30m\"\n") + f.commit("first", "one", nil) + if r := f.run(); r != Settling { + t.Fatalf("first run: %s", r) + } + f.now = f.now.Add(31 * time.Minute) + if r := f.run(); r != Asked { + t.Fatalf("a tip older than settle is asked at once: %s", r) + } +} + +func TestSettleClockBackStartsAgain(t *testing.T) { + f := newFixture(t, ``, "[limits]\nsettle = \"30m\"\n") + f.commit("first", "one", nil) + f.run() + f.now = f.now.Add(-2 * time.Hour) + if r := f.run(); r != Settling { + t.Fatalf("a clock that went back never asks sooner: %s", r) + } + f.now = f.now.Add(29 * time.Minute) + if r := f.run(); r != Settling { + t.Fatalf("still settling: %s", r) + } +} + +func TestSettleWithoutItAsksAtOnce(t *testing.T) { + f := newFixture(t, ``, "") + f.commit("first", "one", nil) + if r := f.run(); r != Asked { + t.Fatalf("no settle asks at once: %s", r) + } +} + +func TestSettleInAutoMode(t *testing.T) { + f := newFixture(t, `mode = "auto"`, "[limits]\nsettle = \"30m\"\n") + f.commit("first", "one", nil) + if r := f.run(); r != Settling { + t.Fatalf("auto waits for the branch to settle too: %s", r) + } + f.now = f.now.Add(30 * time.Minute) + if r := f.run(); r != AutoQueued { + t.Fatalf("then it is queued: %s", r) + } +} + +func TestCheckExit3IsNothingToApply(t *testing.T) { + f := newFixture(t, ``, "") + first := f.applyNew("one") + docs := f.commit("docs only", "one", map[string]string{"nothing-here": "1"}) + if r := f.run(); r != NothingToDo { + t.Fatalf("run: %s, want %s", r, NothingToDo) + } + if ms := f.outbox(); len(ms) != 0 { + t.Fatalf("exit 3 sends no message: %v", ms) + } + st := f.state() + if m := st.Marks[docs]; m == nil || m.Mark != state.MarkNothing { + t.Fatalf("the tip must be marked nothing: %+v", st.Marks[docs]) + } + if st.Applied != first || st.Open() != nil || len(st.AskTimes) != 1 { + t.Fatalf("the applied SHA stays and nothing is asked: %+v", st) + } + if s := f.status(); !strings.Contains(s, "tip mark: nothing (the check found nothing to apply on this host)") { + t.Fatalf("status must show the nothing mark:\n%s", s) + } + if r := f.run(); r != Nothing { + t.Fatalf("a tip marked nothing is not checked again: %s", r) + } + if got := strings.Count(f.read("check-count"), "x"); got != 2 { + t.Fatalf("the check ran %d times, want 2", got) + } + // The next real commit lists every commit since the last real apply. + f.commit("real change", "two", map[string]string{"nothing-here": ""}) // "" removes the file + if r := f.run(); r != Asked { + t.Fatalf("next commit: %s", r) + } + ms := f.outbox() + if asks(ms) != 1 || !contains(ms, "docs only") || !contains(ms, "real change") { + t.Fatalf("the question lists both commits: %v", ms) + } + // Exit 1 is still a failed check. + f.commit("bad", "three", map[string]string{"fail-check": "1"}) + if r := f.run(); r != CheckFailed { + t.Fatalf("exit 1: %s", r) + } + if !contains(f.outbox(), "The check of") { + t.Fatal("exit 1 sends the failed check notice") + } +} + +func TestCheckExit3InAutoMode(t *testing.T) { + f := newFixture(t, `mode = "auto"`, "") + f.commit("docs only", "one", map[string]string{"nothing-here": "1"}) + if r := f.run(); r != NothingToDo { + t.Fatalf("run: %s", r) + } + if f.state().Open() != nil || f.state().Applied != "" { + t.Fatal("exit 3 queues no apply in auto mode") + } +} + +func TestReaskAfterSkip(t *testing.T) { + f := newFixture(t, ``, "[limits]\nreask_after = \"24h\"\n") + sha := f.commit("first", "one", nil) + f.run() + f.tap(f.ask().Code, "skip") + if r := f.apply(); r != Skipped { + t.Fatalf("skip: %s", r) + } + if !contains(f.outbox(), "once more after 24h0m0s") { + t.Fatal("the skip reply says when the tip is asked again") + } + f.now = f.now.Add(23 * time.Hour) + if r := f.run(); r != Nothing { + t.Fatalf("before reask_after: %s", r) + } + f.now = f.now.Add(time.Hour) + if r := f.run(); r != Asked { + t.Fatalf("after reask_after the skipped tip is asked once more: %s", r) + } + q := f.ask() + if r := f.run(); r != Nothing { + t.Fatalf("asked once: %s", r) + } + if asks(f.outbox()) != 0 { + t.Fatal("no second question while the first is open") + } + // A second Skip starts the wait again. + f.tap(q.Code, "skip") + if r := f.apply(); r != Skipped { + t.Fatalf("second skip: %s", r) + } + f.outbox() + f.now = f.now.Add(12 * time.Hour) + if r := f.run(); r != Nothing { + t.Fatalf("after a second Skip, not again before the next wait: %s", r) + } + f.now = f.now.Add(12 * time.Hour) + if r := f.run(); r != Asked { + t.Fatalf("after the next wait: %s", r) + } + if st := f.state(); st.Open() == nil || st.Open().SHA != sha { + t.Fatal("the question is for the same tip") + } +} + +func TestReaskAfterExpiry(t *testing.T) { + f := newFixture(t, ``, "[limits]\napproval_ttl = \"1h\"\nreask_after = \"24h\"\n") + f.commit("first", "one", nil) + f.run() + f.outbox() + f.now = f.now.Add(2 * time.Hour) + if r := f.run(); r != Nothing { + t.Fatalf("expiry run: %s", r) + } + if !contains(f.outbox(), "once more after 24h0m0s") { + t.Fatal("the expired question says when it is asked again") + } + f.now = f.now.Add(24 * time.Hour) + if r := f.run(); r != Asked { + t.Fatalf("an expired tip is asked once more: %s", r) + } +} + +func TestReaskCountsAgainstQuestionsPerDay(t *testing.T) { + f := newFixture(t, ``, "[limits]\nquestions_per_day = 1\nreask_after = \"1h\"\n") + f.commit("first", "one", nil) + f.run() + f.tap(f.ask().Code, "skip") + f.apply() + f.outbox() + f.now = f.now.Add(2 * time.Hour) + if r := f.run(); r != LimitReached { + t.Fatalf("a reask counts against questions_per_day: %s", r) + } +} + +func TestWithoutReaskNothingChanges(t *testing.T) { + f := newFixture(t, ``, "") + f.commit("first", "one", nil) + f.run() + f.tap(f.ask().Code, "skip") + f.apply() + ms := f.outbox() + if !contains(ms, "Skipped") || contains(ms, "reask_after") { + t.Fatalf("the skip reply is as before: %v", ms) + } + f.now = f.now.Add(30 * 24 * time.Hour) + if r := f.run(); r != Nothing { + t.Fatalf("without reask_after a skipped tip is not asked again: %s", r) + } +} + +func TestCheckRequestRepliesSettlingAndNothing(t *testing.T) { + f := newFixture(t, ``, "[limits]\nsettle = \"30m\"\n") + f.commit("first", "one", map[string]string{"nothing-here": "1"}) + f.request() + if r := f.run(); r != Settling { + t.Fatalf("run: %s", r) + } + if ms := f.outbox(); !contains(ms, "It is settling") || !contains(ms, "2026-11-11 12:30 UTC") { + t.Fatalf("the /check reply says the tip settles: %v", ms) + } + f.now = f.now.Add(31 * time.Minute) + f.request() + if r := f.run(); r != NothingToDo { + t.Fatalf("run: %s", r) + } + if ms := f.outbox(); !contains(ms, "nothing to apply on this host") { + t.Fatalf("the /check reply says there is nothing to apply: %v", ms) + } + f.now = f.now.Add(31 * time.Minute) + f.request() + if r := f.run(); r != Nothing { + t.Fatalf("run: %s", r) + } + if ms := f.outbox(); !contains(ms, "the check said that") { + t.Fatalf("the /check reply names the nothing mark: %v", ms) + } +} + +func TestStatusShowsNoSettleForAHandledTip(t *testing.T) { + f := newFixture(t, ``, "[limits]\nsettle = \"30m\"\n") + f.commit("first", "one", map[string]string{"nothing-here": "1"}) + f.run() + f.now = f.now.Add(31 * time.Minute) + if r := f.run(); r != NothingToDo { + t.Fatalf("run: %s", r) + } + // A new run of the same tip: no settle shown, the mark is shown. + if s := f.status(); strings.Contains(s, "settling") || !strings.Contains(s, "nothing (the check") { + t.Fatalf("status:\n%s", s) + } +} + +func TestReaskNotInAutoMode(t *testing.T) { + f := newFixture(t, `mode = "auto"`, "[limits]\nreask_after = \"1h\"\n") + sha := f.commit("first", "one", nil) + if err := f.env.Dir.Ensure(); err != nil { + t.Fatal(err) + } + st := f.state() + st.LastTip = sha + st.SetMark(sha, state.MarkExpired, f.now) + if err := f.env.Dir.Save(st); err != nil { + t.Fatal(err) + } + f.now = f.now.Add(2 * time.Hour) + if r := f.run(); r != Nothing { + t.Fatalf("reask_after does nothing in auto mode: %s", r) + } +} + +func TestCheckExit3InTheBrokenStateIsAFailedCheck(t *testing.T) { + f := newFixture(t, ``, "") + first := f.applyNew("one") + st := f.state() + st.Broken = &state.Broken{Since: f.now, SHA: first, Reason: "test"} + if err := f.env.Dir.Save(st); err != nil { + t.Fatal(err) + } + fix := f.commit("fix", "one", map[string]string{"nothing-here": "1"}) + if r := f.run(); r != CheckFailed { + t.Fatalf("exit 3 in the broken state: %s, want %s", r, CheckFailed) + } + if !contains(f.outbox(), "The check of") { + t.Fatal("the owner gets a notice") + } + if m := f.state().Marks[fix]; m == nil || m.Mark != state.MarkCheckFailed { + t.Fatalf("mark: %+v", m) + } +} diff --git a/internal/gate/check.go b/internal/gate/check.go index 167c345..95eaf3f 100644 --- a/internal/gate/check.go +++ b/internal/gate/check.go @@ -130,7 +130,11 @@ func (e *Env) askAgainRequest(st *state.State) { case m == nil: e.notice("Nothing to ask again: " + code(tip) + " has no question that expired or was lost.") default: - e.notice("Not asked again: " + code(tip) + " was " + m.Mark + ". /ask-again asks only about a question that expired or was lost. To ask anyway, run as root: pullgate status " + e.Cfg.Name + " --ask-again") + hint := "" + if m.Mark == state.MarkSkipped && e.reaskOn() { + hint = " It is asked once more " + e.Cfg.Limits.ReaskAfter.String() + " after the Skip (reask_after)." + } + e.notice("Not asked again: " + code(tip) + " was " + m.Mark + ". /ask-again asks only about a question that expired or was lost. To ask anyway, run as root: pullgate status " + e.Cfg.Name + " --ask-again" + hint) } } @@ -186,6 +190,8 @@ func (e *Env) checkReply(st *state.State, res Result, err error, limitSent bool) e.notice("No new commit. " + code(tip) + " is waiting for its auto apply.") case tip == st.Held: e.notice("No new question: the last apply of " + code(tip) + " failed and it is held. A newer commit is asked.") + case st.Marks[tip] != nil && st.Marks[tip].Mark == state.MarkNothing: + e.notice("No new question: the check said that " + code(tip) + " has nothing to apply on this host. The applied commit is still " + code(st.Applied) + ".") case st.Marks[tip] != nil && st.Marks[tip].Mark == state.MarkRefused: e.notice("No new question: " + code(tip) + " is not a descendant of the applied commit " + code(st.Applied) + ", so it was refused. To allow it, set allow_older = true in [limits] of the host config.") default: @@ -193,8 +199,17 @@ func (e *Env) checkReply(st *state.State, res Result, err error, limitSent bool) if m := st.Marks[tip]; m != nil { mark = " (" + m.Mark + ")" } - e.notice("No new question: " + code(tip) + " was handled before" + mark + ". To ask again, run as root: pullgate status " + e.Cfg.Name + " --ask-again") + hint := "" + if m := st.Marks[tip]; m != nil && (m.Mark == state.MarkSkipped || m.Mark == state.MarkExpired) && e.reaskOn() { + hint = " It is asked once more " + e.Cfg.Limits.ReaskAfter.String() + " after the mark (reask_after)." + } + e.notice("No new question: " + code(tip) + " was handled before" + mark + ". To ask again, run as root: pullgate status " + e.Cfg.Name + " --ask-again" + hint) } + case Settling: + until, _ := e.settling(st, e.now()) + e.notice("New commit " + code(tip) + ". It is settling: it is asked when the branch has not changed until " + until.UTC().Format("2006-01-02 15:04 MST") + " ([limits] settle).") + case NothingToDo: + e.notice("New commit " + code(tip) + ". The check says it has nothing to apply on this host, so nothing is asked. The applied commit is still " + code(st.Applied) + ".") case AutoQueued: e.notice("New commit " + code(tip) + ". The mode is auto (mode = \"auto\"), so it is applied now, without a tap.") case LimitReached: diff --git a/internal/gate/fixture_test.go b/internal/gate/fixture_test.go index 6ecee75..43da847 100644 --- a/internal/gate/fixture_test.go +++ b/internal/gate/fixture_test.go @@ -61,6 +61,7 @@ cat "$PULLGATE_TREE/value" > `+c+`/live f.script("check.sh", `id -u > `+c+`/check-uid echo x >> `+c+`/check-count if [ -e "$PULLGATE_TREE/fail-check" ]; then echo "bad config "; exit 1; fi +if [ -e "$PULLGATE_TREE/nothing-here" ]; then echo "only docs"; exit 3; fi `) f.script("summary.sh", `id -u > `+c+`/summary-uid echo "value $(cat "$PULLGATE_TREE/value")" diff --git a/internal/gate/run.go b/internal/gate/run.go index 4a62e45..133715d 100644 --- a/internal/gate/run.go +++ b/internal/gate/run.go @@ -4,6 +4,7 @@ import ( "context" "errors" "fmt" + "os/exec" "strings" "time" @@ -24,6 +25,8 @@ const ( Off Result = "off" CutOff Result = "cut-off" Nothing Result = "nothing" + Settling Result = "settling" + NothingToDo Result = "nothing-to-apply" Refused Result = "refused" LimitReached Result = "limit" CheckLimited Result = "check-limited" @@ -92,7 +95,7 @@ func (e *Env) expire(st *state.State) { st.SetMark(q.SHA, state.MarkExpired, now) } if q.Open && !q.Auto { - e.edit(q.ID, "This question for "+code(q.SHA)+" expired. A new commit, or pullgate status "+e.Cfg.Name+" --ask-again, asks again.") + e.edit(q.ID, "This question for "+code(q.SHA)+" expired. "+e.againHint()) } e.Log.Info("question expired", "question", q.ID, "sha", q.SHA) } @@ -220,6 +223,11 @@ func (e *Env) fetchAndDecide(ctx context.Context, st *state.State) (Result, erro return "", fmt.Errorf("fetch: %w", err) } e.Log.Info("fetched", "tip", tip, "applied", st.Applied) + if now := e.now(); tip != st.LastTip || st.TipSince.IsZero() || st.TipSince.After(now) { + // A new tip, or a clock that went back: the settle time starts + // now (fail closed: never sooner). + st.TipSince = now + } st.LastTip = tip e.expire(st) return e.decide(ctx, st, tip) @@ -242,13 +250,23 @@ func (e *Env) decide(ctx context.Context, st *state.State, tip string) (Result, e.Log.Info("broken: the tip is the failed or the old commit; waiting for a fix forward", "sha", tip) return Nothing, nil } + // In the broken state the owner is always asked, also in auto mode. + ask := e.Cfg.Mode == config.ModeAsk || st.Broken != nil if m := st.Marks[tip]; m != nil { // No retry in the broken state: a rollback is never tried there. retry := st.Broken == nil && m.Mark == state.MarkFailed && e.Cfg.OnFailure == config.OnFailureRollback && m.Tries < e.Cfg.Limits.MaxFailedTries - if !retry { + reask := e.reaskOn() && e.reaskDue(m, now) + if !retry && !reask { e.Log.Info("the tip was handled before; waiting for a new commit", "sha", tip, "mark", m.Mark) return Nothing, nil } + if reask { + e.Log.Info("reask_after: asking once more", "sha", tip, "mark", m.Mark, "since", m.At) + } + } + if until, ok := e.settling(st, now); ok { + e.Log.Info("settling: the tip changed not long ago; nothing is asked yet", "sha", tip, "until", until) + return Settling, nil } notDesc := false if st.Applied != "" { @@ -278,8 +296,6 @@ func (e *Env) decide(ctx context.Context, st *state.State, tip string) (Result, return Refused, nil } } - // In the broken state the owner is always asked, also in auto mode. - ask := e.Cfg.Mode == config.ModeAsk || st.Broken != nil // Questions per day. var recent []time.Time for _, t := range st.AskTimes { @@ -316,6 +332,16 @@ func (e *Env) decide(ctx context.Context, st *state.State, tip string) (Result, p.env.Failed = failedSHA(st) if argv := e.Cfg.Commands.Check; len(argv) > 0 { out, err := e.runSandboxed(ctx, argv, p.env) + if exitCode(err) == CheckExitNothing && st.Broken == nil { + // The check says this commit changes nothing on this host. + // No message, and the applied SHA stays, so that the next + // question lists every commit since the last real apply. In + // the broken state exit 3 is a failed check with a notice: + // the owner must not miss that a fix forward was not asked. + st.SetMark(tip, state.MarkNothing, now) + e.Log.Info("check: nothing to apply on this host; not asking", "sha", tip) + return NothingToDo, nil + } if err != nil { st.SetMark(tip, state.MarkCheckFailed, now) e.Log.Warn("check failed; not asking", "sha", tip, "err", err) @@ -386,6 +412,64 @@ func (e *Env) decide(ctx context.Context, st *state.State, tip string) (Result, return Asked, nil } +// CheckExitNothing is the exit status of check that means "this commit +// has nothing to apply on this host" (DESIGN.md section 11). +const CheckExitNothing = 3 + +// exitCode is the exit status of a command that ran to its end and +// failed, else -1 (no error, a timeout, a signal, or no start). +func exitCode(err error) int { + var ee *exec.ExitError + if err == nil || !errors.As(err, &ee) { + return -1 + } + return ee.ExitCode() +} + +// settling says whether the tip changed less than settle ago, and until +// when it waits ([limits] settle). +func (e *Env) settling(st *state.State, now time.Time) (time.Time, bool) { + s := e.Cfg.Limits.Settle.Duration + if s <= 0 { + return time.Time{}, false + } + until := st.TipSince.Add(s) + return until, st.TipSince.IsZero() || now.Before(until) +} + +// reaskDue says whether a skipped or expired tip is asked once more +// ([limits] reask_after). Each new Skip or expiry starts the wait again. +func (e *Env) reaskDue(m *state.Mark, now time.Time) bool { + r := e.Cfg.Limits.ReaskAfter.Duration + if !e.reaskOn() || (m.Mark != state.MarkSkipped && m.Mark != state.MarkExpired) { + return false + } + return !m.At.After(now) && now.Sub(m.At) >= r +} + +// reaskOn says whether reask_after is used: only in ask mode, where a +// question has Skip. +func (e *Env) reaskOn() bool { + return e.Cfg.Limits.ReaskAfter.Duration > 0 && e.Cfg.Mode == config.ModeAsk +} + +// againHint says when a skipped or expired tip is asked again. +func (e *Env) againHint() string { + h := "A new commit, or pullgate status " + e.Cfg.Name + " --ask-again, asks again." + if e.reaskOn() { + h += " Else it is asked once more after " + e.Cfg.Limits.ReaskAfter.String() + " (reask_after)." + } + return h +} + +// skipHint says when a skipped tip is asked again. +func (e *Env) skipHint() string { + if e.reaskOn() { + return "A new commit asks again, or this one once more after " + e.Cfg.Limits.ReaskAfter.String() + " (reask_after)." + } + return "A new commit asks again." +} + // shortTrees replaces the long tree paths in command output with NEW and // OLD: they say nothing to the owner and push the reason out of the // message (code6x/pullgate#25). diff --git a/internal/gate/status.go b/internal/gate/status.go index fb66781..b2b73f0 100644 --- a/internal/gate/status.go +++ b/internal/gate/status.go @@ -4,6 +4,7 @@ import ( "fmt" "io" + "github.com/code6x/pullgate/internal/config" "github.com/code6x/pullgate/internal/state" ) @@ -92,9 +93,19 @@ func (e *Env) statusText(w io.Writer, st *state.State) { if st.Held != "" { show("held", st.Held+" (the last apply failed)") } - if m := st.Marks[st.LastTip]; m != nil && st.LastTip != "" { + m := st.Marks[st.LastTip] + switch { + case st.LastTip == "": + case m != nil && m.Mark == state.MarkNothing: + show("tip mark", "nothing (the check found nothing to apply on this host)") + case m != nil: show("tip mark", fmt.Sprintf("%s (tries %d)", m.Mark, m.Tries)) } + if e.settleShown(st, m) { + if until, ok := e.settling(st, e.now()); ok && !st.TipSince.IsZero() { + show("settle", "settling until "+until.Format("2006-01-02 15:04 MST")) + } + } if b := st.Broken; b != nil { show("broken", fmt.Sprintf("since %s, last error: %s", b.Since.Format("2006-01-02 15:04 MST"), b.Reason)) } @@ -130,3 +141,18 @@ func orNone(s string) string { } return s } + +// settleShown says whether the last tip waits for settle: a tip that a +// run would check and ask, but for the settle time. +func (e *Env) settleShown(st *state.State, m *state.Mark) bool { + tip, open := st.LastTip, st.Open() + switch { + case tip == "" || tip == st.Applied || tip == st.Held || m != nil || e.Cfg.Mode == config.ModeOff: + return false + case open != nil && open.SHA == tip: + return false + case st.Broken != nil && (tip == st.Broken.SHA || tip == st.Broken.OldSHA): + return false + } + return true +} diff --git a/internal/listener/listener.go b/internal/listener/listener.go index a187d52..738b2fc 100644 --- a/internal/listener/listener.go +++ b/internal/listener/listener.go @@ -531,7 +531,7 @@ func (l *Listener) helpText() string { "", "Instances: " + strings.Join(names, ", "), "", - "A question has two buttons. Apply applies that one commit. Skip skips it; a newer commit is asked again.", + "A question has two buttons. Apply applies that one commit. Skip skips it; a newer commit is asked again (and the same one once more after reask_after, if the host config sets it).", "", "On the host, as root:", "pullgate status NAME: the mode, the applied commit, the open question, paused or not", diff --git a/internal/state/state.go b/internal/state/state.go index b15792a..905db50 100644 --- a/internal/state/state.go +++ b/internal/state/state.go @@ -32,6 +32,9 @@ const ( MarkCheckFailed = "check-failed" MarkRefused = "refused" MarkFailed = "failed" + // MarkNothing: the check exited 3, "nothing to apply on this host" + // (DESIGN.md section 7). The applied SHA stays as it is. + MarkNothing = "nothing" ) // Question is one question that root asked. @@ -77,6 +80,7 @@ type State struct { AppliedAt time.Time `json:"applied_at"` Held string `json:"held,omitempty"` LastTip string `json:"last_tip,omitempty"` + TipSince time.Time `json:"tip_since,omitzero"` // when root first saw LastTip as the tip ([limits] settle) Questions []Question `json:"questions"` Marks map[string]*Mark `json:"marks"` InProgress *InProgress `json:"in_progress,omitempty"`