Skip to content

Commit 772d956

Browse files
groupskyclaude
andcommitted
feat: ask less often: settle time, a "nothing to apply" check exit, and one more question after a wait
- [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 <noreply@anthropic.com>
1 parent b91914c commit 772d956

15 files changed

Lines changed: 588 additions & 21 deletions

File tree

‎DESIGN.md‎

Lines changed: 43 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,8 @@ max_files = 100000 # default 100000 files in one tree
192192
max_tree_bytes = 1073741824 # default 1 GiB in one tree
193193
allow_older = false # default false (rule 5)
194194
refuse_symlinks = false # default false; true refuses a commit with a symlink that points out of the tree
195+
settle = "30m" # default 0 (ask at once); ask only when the tip has not changed for this long, at most 168h
196+
reask_after = "24h" # default 0 (never); ask a skipped or expired tip once more after this time (ask mode)
195197

196198
[listener]
197199
user = "pullgate" # the user of the listener; owns the inbox
@@ -315,10 +317,30 @@ used again.
315317
("the branch is back to the applied commit").
316318
- tip = the SHA of the open question: nothing to do.
317319
- tip is the held SHA, or was asked before and the question expired or
318-
was skipped, or its check failed, or it was refused, or it failed
319-
`max_failed_tries` times: nothing to do. `pullgate status NAME
320-
--ask-again` clears this mark, and also closes an open question for
321-
the tip (section 13).
320+
was skipped, or its check failed, or it was refused, or its check
321+
said "nothing to apply" (step 7), or it failed `max_failed_tries`
322+
times: nothing to do. `pullgate status NAME --ask-again` clears this
323+
mark, and also closes an open question for the tip (section 13).
324+
- **`reask_after`** (default 0, off): in `ask` mode, a tip marked
325+
skipped or expired is asked
326+
once more when its mark is at least `reask_after` old and it is still
327+
the tip. Asking sets the mark to asked; a second Skip or expiry sets
328+
a new mark time, so the next ask comes only after the next wait. It
329+
counts against `questions_per_day` like every question. `auto` mode
330+
has no Skip, so `reask_after` does nothing there.
331+
- **`settle`** (default 0, off): root keeps in its state the time it
332+
first saw the tip (`tip_since`). A new tip, or a clock that went back
333+
before that time, starts it again. While the tip is younger than
334+
`settle`, the run logs "settling" and stops: no check, no question,
335+
no notice. So three merges in ten minutes give one question, for the
336+
last one, and a writer cannot keep moving the branch to make the
337+
owner tap without reading. It also holds in `auto` mode. The time is
338+
root's own: the commit date is written by the writer and is not
339+
trusted. An open question for an older tip stays open while the new
340+
tip settles: it is closed only when the new tip is asked (step 9), as
341+
today while the new tip is checked. A state file from a version
342+
before `settle` has no `tip_since`; the first run sets it to now, so
343+
the tip it knew waits one settle time (fail closed).
322344
- tip is not a descendant of the applied SHA (an older commit, a force
323345
push, a rewritten branch) and `allow_older` is false: refuse. Send one
324346
notice for this SHA and mark it refused. When `allow_older` is true,
@@ -328,7 +350,15 @@ used again.
328350
send one notice per day, and do not ask.
329351
6. Export the tree of the tip, and the tree of the applied SHA
330352
(`PULLGATE_OLD_TREE`).
331-
7. Run `check` as `check_user` (section 11). If it fails, mark the SHA
353+
7. Run `check` as `check_user` (section 11). If it exits with status
354+
**3**, the commit has nothing to apply on this host (for example only
355+
docs, or files for other hosts): mark the SHA `nothing`, send no
356+
message, and do not ask. The applied SHA stays as it is, so the next
357+
question still lists every commit since the last real apply, and its
358+
check and summary still compare with the last applied tree. In the
359+
broken state (section 10) exit 3 is a failed check with its notice,
360+
so the owner sees that a fix forward was not asked. Any other
361+
non-zero status, a timeout or a signal is a failed check. If it fails, mark the SHA
332362
"check failed", send a notice with the end of its output, and do not
333363
ask. The same SHA is not checked again. In that output the tree paths
334364
(`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
684714
(`check_timeout`, `apply_timeout`); on timeout the whole process group is
685715
killed and the command counts as failed. pullgate keeps at most 64 KiB of
686716
their output. The output of `apply` and `health` goes to the journal; the
687-
report shows only the exit status. The output of `check` (its last lines)
717+
report shows only the exit status. `check` exits 0 to pass, 3 for
718+
"nothing to apply on this host" (section 7, step 7), and anything else to
719+
fail. The output of `check` (its last lines)
688720
and of `summary` goes into Telegram messages, after the cleaning of
689721
section 12.
690722

@@ -775,11 +807,13 @@ closed after a cut.
775807
- `off`: `pullgate run` and `pullgate apply` do nothing.
776808

777809
`pullgate status NAME` prints the mode, the applied SHA, the open question,
778-
the held SHA, the broken state ("broken since …, last error …"), the pause
779-
file and an apply in progress. Flags:
810+
the held SHA, the mark of the last tip (`nothing` reads "nothing (the check
811+
found nothing to apply on this host)"), "settling until …" while the tip
812+
waits for `settle`, the broken state ("broken since …, last error …"), the
813+
pause file and an apply in progress. Flags:
780814

781815
- `--ask-again`: clear the marks of the last fetched tip (expired, skipped,
782-
check failed, refused, failed, held), so the next run asks again. If a
816+
check failed, nothing, refused, failed, held), so the next run asks again. If a
783817
question for the tip is open (for example its message was lost), root
784818
removes it from its state, then asks the listener to close its message.
785819
The next run asks again with a new question ID and a new code. An

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -282,7 +282,8 @@ deploy_key = "/etc/pullgate/NAME.key"
282282
known_hosts = "/etc/pullgate/NAME.known_hosts"
283283

284284
[commands]
285-
check = ["/path/to/check"] # optional; runs as check_user; a failure means no question
285+
check = ["/path/to/check"] # optional; runs as check_user; a failure means no question;
286+
# exit 3 means "nothing to apply on this host": no question, no message
286287
summary = ["/path/to/summary"] # optional; runs as check_user; its output is in the question
287288
apply = ["/path/to/apply"] # required; runs as root after Apply
288289
health = ["/path/to/health"] # optional; runs as root after apply
@@ -296,6 +297,8 @@ questions_per_day = 10
296297
approval_ttl = "12h"
297298
max_failed_tries = 1
298299
allow_older = false
300+
settle = "0" # e.g. "30m": ask only when the branch has not changed for this long
301+
reask_after = "0" # e.g. "24h": ask a skipped or expired commit once more after this time
299302
```
300303

301304
The commands get these environment variables: `PULLGATE_SHA`,

‎THREAT-MODEL.md‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -323,6 +323,11 @@ A clock that goes back before `asked` denies. A clock that jumps forward
323323
expires questions early: this denies too. The listener checks expiry with its
324324
own clock as well. Timeouts of commands use the monotonic clock.
325325

326+
`settle` counts from the time root first saw the tip; a clock that goes
327+
back before that time starts the wait again. A clock that is wrong and then
328+
corrected forward can make the wait shorter, like `approval_ttl` above.
329+
That only asks sooner; it never applies anything.
330+
326331
*Left.* A clock that is set far back while a question is open can keep that
327332
question valid longer than `approval_ttl`. The code still works only once.
328333

@@ -382,7 +387,24 @@ repo URL must pass the same check as the clone, because root runs
382387
*Attack.* Someone pushes many commits to tire the owner into tapping Apply.
383388

384389
*Defense.* At most one open question per instance; a newer tip replaces it.
385-
`questions_per_day` caps the questions. A SHA is asked once.
390+
`questions_per_day` caps the questions. A SHA is asked once, or once more
391+
per `reask_after` after a Skip or an expiry; each of these counts against
392+
`questions_per_day`. With `settle`, a tip is asked only when root has seen
393+
it unchanged for that long, by root's own clock (not the commit date, which
394+
the writer sets). So a writer who keeps moving the branch gets no question
395+
at all, and the owner always has a question that stays the same while he
396+
reads it.
397+
398+
*Check exit 3.* `check` runs as `check_user` on the commit's tree, so a
399+
hostile commit can make it exit 3. That only marks the SHA `nothing`: no
400+
question, no apply, and the applied SHA stays. It cannot apply anything,
401+
and it is no worse than a check that fails. The next real commit is asked
402+
with every commit since the last real apply, so nothing is hidden from the
403+
owner. Root takes only the exit status; it reads nothing else from the
404+
check.
405+
406+
*Left.* A writer can delay a question by pushing more often than `settle`.
407+
That only delays; it never applies.
386408

387409
### T16. A bad release binary
388410

‎contrib/examples/ansible/playbooks.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ paths = ["ansible.cfg", "site.yml", "roles/pullgate/**", "**/sudoers*"]
2727

2828
[limits]
2929
questions_per_day = 10
30+
settle = "30m" # ask only when the branch has not changed for 30 minutes
31+
reask_after = "24h" # ask a skipped or expired commit once more after a day
3032
approval_ttl = "24h"
3133

3234
[listener]

‎contrib/examples/config-file/config-repo.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ paths = ["policy.toml"]
2626

2727
[limits]
2828
questions_per_day = 10
29+
settle = "30m" # ask only when the branch has not changed for 30 minutes
30+
reask_after = "24h" # ask a skipped or expired commit once more after a day
2931
approval_ttl = "12h"
3032
max_failed_tries = 1
3133

‎internal/config/config.go‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,12 @@ type Limits struct {
8484
MaxTreeBytes int64 `toml:"max_tree_bytes"`
8585
AllowOlder bool `toml:"allow_older"`
8686
RefuseSymlinks bool `toml:"refuse_symlinks"`
87+
// Settle is how long the tip must stay the same before it is checked
88+
// and asked (DESIGN.md section 7). 0 asks at once.
89+
Settle Duration `toml:"settle"`
90+
// ReaskAfter asks a skipped or expired tip once more when its mark is
91+
// this old (DESIGN.md section 7). 0 never asks again.
92+
ReaskAfter Duration `toml:"reask_after"`
8793
}
8894

8995
// ListenerUser is the [listener] section of an instance.
@@ -196,6 +202,12 @@ func (c *Instance) validate() error {
196202
if c.Limits.QuestionsPerDay < 0 || c.Limits.MaxFailedTries < 0 || c.Limits.MaxFiles < 0 || c.Limits.MaxTreeBytes < 0 {
197203
return c.errf("[limits]", "a limit is below 0. Fix: use a positive number")
198204
}
205+
if c.Limits.Settle.Duration < 0 || c.Limits.Settle.Duration > MaxTTL {
206+
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")
207+
}
208+
if c.Limits.ReaskAfter.Duration < 0 {
209+
return c.errf("[limits] reask_after", "is below 0. Fix: use a time like \"24h\", or \"0\" to never ask again")
210+
}
199211
if c.Commands.CheckTimeout.Duration < 0 || c.Commands.ApplyTimeout.Duration < 0 {
200212
return c.errf("[commands]", "a timeout is below 0")
201213
}

‎internal/config/config_test.go‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ func TestDefaults(t *testing.T) {
4444
t.Fatal(err)
4545
}
4646
if c.Mode != "ask" || c.OnFailure != "pause" || c.Limits.QuestionsPerDay != 10 || c.Limits.MaxFailedTries != 1 ||
47-
c.Limits.ApprovalTTL.Hours() != 12 || c.Limits.AllowOlder || c.Commands.CheckUser != "pullgate-check" {
47+
c.Limits.ApprovalTTL.Hours() != 12 || c.Limits.AllowOlder || c.Limits.Settle.Duration != 0 || c.Limits.ReaskAfter.Duration != 0 || c.Commands.CheckUser != "pullgate-check" {
4848
t.Fatalf("defaults: %+v", c)
4949
}
5050
}
@@ -61,6 +61,9 @@ func TestRefused(t *testing.T) {
6161
"url as option": strings.Replace(good, "ssh://git@git.example.com/owner/config-repo.git", "--upload-pack=x", 1),
6262
"branch option": good + "[repo]\n",
6363
"ttl too long": good + "[limits]\napproval_ttl = \"200h\"\n",
64+
"settle too long": good + "[limits]\nsettle = \"200h\"\n",
65+
"settle below 0": good + "[limits]\nsettle = \"-1m\"\n",
66+
"reask below 0": good + "[limits]\nreask_after = \"-1h\"\n",
6467
"absolute watch path": good + "[watch]\npaths = [\"/etc/x\"]\n",
6568
"host html": `host = "<b>"` + good,
6669
}
@@ -245,3 +248,13 @@ func TestCheckAPIURL(t *testing.T) {
245248
}
246249
}
247250
}
251+
252+
func TestSettleAndReask(t *testing.T) {
253+
c, err := Load(write(t, good+"[limits]\nsettle = \"30m\"\nreask_after = \"24h\"\n", 0o600), "x", uid())
254+
if err != nil {
255+
t.Fatal(err)
256+
}
257+
if c.Limits.Settle.Minutes() != 30 || c.Limits.ReaskAfter.Hours() != 24 {
258+
t.Fatalf("settle %s, reask_after %s", c.Limits.Settle.Duration, c.Limits.ReaskAfter.Duration)
259+
}
260+
}

‎internal/gate/apply.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ func (e *Env) handle(ctx context.Context, st *state.State, a spool.Approval) (Re
174174
if a.Action == "skip" {
175175
st.SetMark(q.SHA, state.MarkSkipped, now)
176176
e.Log.Info("skipped", "sha", q.SHA)
177-
e.reply(q.ID, "Skipped "+code(q.SHA)+". A new commit asks again.")
177+
e.reply(q.ID, "Skipped "+code(q.SHA)+". "+e.skipHint())
178178
return Skipped, false, e.Dir.Save(st)
179179
}
180180
r, err := e.applySHA(ctx, st, q)

0 commit comments

Comments
 (0)