@@ -27,6 +27,9 @@ protects, and where it stops.
2727 button. It holds the code and the button (apply or skip). Nothing else.
2828- ** tree** : a clean, read-only copy of the files of one commit, written by
2929 pullgate itself from git objects.
30+ - ** check request** : a small file that the listener writes when the owner
31+ sends ` /check ` or ` /check NAME ` . It holds no data from the message. It
32+ starts a normal run now, instead of at the next timer (sections 8 and 9).
3033- ** pause file** : ` /var/lib/pullgate/NAME/paused ` . While it exists, the
3134 instance does nothing: no run, no apply.
3235
@@ -49,7 +52,9 @@ These rules come from issue #1. Each one has tests (section 14).
4952 no port. It accepts a tap only from the configured owner user ID, in the
5053 configured chat, on an open question. All it can do is write an approval
5154 for that open question. The approval carries only the code. Root looks
52- up the SHA in its own state.
55+ up the SHA in its own state. The only other thing it can write is a
56+ check request for ` /check ` of the owner. That request holds no data, and
57+ it only starts a normal run sooner (sections 8 and 9).
53585 . ** Root does the apply.** It acts only on an approval whose code matches a
5459 question that root recorded itself, and only within the time limit of that
5560 question. By default it moves forward only: the new SHA must descend from
@@ -66,15 +71,17 @@ These rules come from issue #1. Each one has tests (section 14).
6671
6772| process | user | started by | holds |
6873| ---| ---| ---| ---|
69- | ` pullgate run NAME ` | root | a timer (` pullgate-run@NAME.timer ` ) | the clone, the state, the deploy key |
74+ | ` pullgate run NAME ` | root | a timer (` pullgate-run@NAME.timer ` ), or a path unit ( ` pullgate-check@NAME.path ` ) when a check request exists | the clone, the state, the deploy key |
7075| ` pullgate apply NAME ` | root | a path unit (` pullgate-apply@NAME.path ` ) when the inbox is not empty, or the auto approval exists | the state |
7176| ` pullgate listen ` | ` pullgate ` (own user) | a service (` pullgate-listen.service ` ) | the bot token, its list of open questions |
7277| ` check ` , ` summary ` | ` check_user ` (default ` pullgate-check ` ) | ` pullgate run ` | nothing |
7378| ` apply ` , ` health ` | root | ` pullgate apply ` | what the owner's command needs |
7479| ` pullgate status NAME ` | root | the owner | nothing |
7580
7681Root and the listener never talk directly. They use a spool directory
77- (section 8).
82+ (section 8). Both units start the same ` pullgate-run@NAME.service ` , so a
83+ run on ` /check ` has the same sandbox, the same lock and the same rules as a
84+ run on the timer. systemd never starts one unit twice at once.
7885
7986The run unit is sandboxed (read-only system, private ` /tmp ` , no new
8087privileges). The apply unit runs the owner's ` apply ` command as root, so it
@@ -99,6 +106,7 @@ can be less strict; each example sets what its `apply` needs.
99106| ` /var/spool/pullgate/ ` and ` /var/spool/pullgate/NAME/ ` | root, 0755 | the spool |
100107| ` /var/spool/pullgate/NAME/outbox ` | root, group listener, 0770 | messages from root to the listener |
101108| ` /var/spool/pullgate/NAME/inbox ` | listener, 0700 | approvals from the listener to root |
109+ | ` /var/spool/pullgate/NAME/check ` | listener, 0700 | check requests from the listener to root |
102110| ` /var/lib/pullgate-listener/state.json ` | listener, 0600 | the listener's open questions |
103111
104112The paths can be changed with ` --config-dir ` , ` --state-dir ` and
@@ -121,8 +129,8 @@ path that the listener can change. It opens the spool directories with
121129through the open directory, creates files in them with
122130` O_CREAT|O_EXCL|O_NOFOLLOW ` under a random temporary name and renames them
123131in the same directory. ` /var/spool/pullgate ` and ` NAME/ ` are owned by root
124- and pass the check of section 6, so the listener cannot swap ` outbox ` or
125- ` inbox ` for a symlink.
132+ and pass the check of section 6, so the listener cannot swap ` outbox ` ,
133+ ` inbox ` or ` check ` for a symlink.
126134
127135## 5. The instance config
128136
@@ -266,8 +274,11 @@ used again.
266274## 7. One run (` pullgate run NAME ` )
267275
2682761 . Read the config. Take the lock (` flock ` , no wait). If another run or
269- apply holds it, log "busy" and exit 0. If the pause file exists, log
270- "paused" and exit 0. If ` mode = "off" ` , log "off" and exit 0.
277+ apply holds it, log "busy" and exit 0; but when a check request waits,
278+ wait for the lock instead (section 8). If the pause file exists, log
279+ "paused" and exit 0. If ` mode = "off" ` , log "off" and exit 0. When a
280+ check request waits, take it first (section 8); then paused and off
281+ send a reply ("NAME is paused" or "NAME is off"), and do not fetch.
2712822 . If the state shows an apply in progress (section 10), write the pause
272283 file, report, and exit.
2732843 . Make sure the clone and the spool directories exist with the right owners
@@ -338,6 +349,58 @@ files older than one minute.
338349auto approval (` PathExists= ` ), and starts ` pullgate apply NAME ` . The apply
339350service has a start limit, so a stuck file cannot start it in a loop.
340351
352+ ** Check requests** (the listener writes, root reads and removes). The
353+ listener writes ` /var/spool/pullgate/NAME/check/request ` for ` /check `
354+ (section 9): a ` .tmp-* ` file renamed to that one fixed name, so many
355+ requests before root reads them are one file. The content is always the
356+ six bytes ` check\n ` . It holds nothing from the message: not the text, not
357+ a SHA, not a code. A check request can only start a normal run. It is not
358+ an approval, and ` pullgate apply ` never reads this directory.
359+
360+ ` pullgate-check@NAME.path ` watches the directory (` DirectoryNotEmpty= ` ) and
361+ starts ` pullgate-run@NAME.service ` , the unit of the timer. ` pullgate run ` ,
362+ with the lock held:
363+
364+ 1 . Reads and removes every file in the directory, with the checks of an
365+ approval: through ` os.OpenRoot ` with ` O_NOFOLLOW ` , a regular file owned
366+ by the listener user, at most 64 bytes. It must also have the name
367+ ` request ` and exactly the content ` check\n ` . Root removes each file
368+ before it acts. A bad file is logged and removed; it is not a request.
369+ A run that finds only bad files goes on as a normal (timer) run, with
370+ no reply and no mark against the limit.
371+ 2 . ** The limit** , kept by root in its own ` state.json ` (` check_at ` ), not
372+ by the listener: at most one run per minute (` CheckInterval ` ) starts
373+ from a check request. When the last one is less than a minute away
374+ (before or after, so a clock jump back of less than a minute does not
375+ pass it), the run removes the request and exits without a fetch. It
376+ sends one reply per minute: "A check ran less than a minute ago, so this
377+ /check was dropped." (` check_note ` ).
378+ 3 . Paused or off: reply so, do not fetch.
379+ 4 . Else the normal run (section 7). After it, a reply says what it found,
380+ unless the question or a notice says it already: "No new commit. The
381+ applied commit is SHA.", "the question for SHA is still open", "SHA was
382+ handled before (mark)", "the last apply of SHA failed and it is held",
383+ or, in ` auto ` mode, "New commit SHA … it is applied now, without a tap"
384+ (section 13). A run that fails sends "The check failed. See the journal
385+ of the host", without the error text.
386+
387+ ** A request while the lock is held.** A run started by the timer exits
388+ "busy" when another process holds the lock. A run that sees a check request
389+ waits for the lock instead (` flock ` with a wait), so the request is not
390+ lost and the path unit does not start the run again and again. The lock
391+ makes sure that two runs, or a run and an apply, never run at once. The
392+ run unit's ` TimeoutStartSec ` caps the wait.
393+
394+ ** The start limit.** Each check request starts the run unit. The path unit
395+ has a trigger limit (` TriggerLimitBurst=10 ` in 60 seconds), which stops a
396+ loop when a run fails before it removes the request. If the limit is hit,
397+ systemd stops the path unit until the owner runs `systemctl reset-failed
398+ pullgate-check@NAME.path ` and starts it again. The run unit has no start
399+ limit (` StartLimitIntervalSec=0 ` ), so many requests never stop the timer.
400+ So that ` /check ` alone never hits the limit, the listener also writes at
401+ most one request per instance in 10 seconds (` CheckGap ` , kept in
402+ memory). Root does not trust this: its own limit is the one above.
403+
341404## 9. Questions and approvals
342405
343406Root keeps its questions in ` state.json ` :
@@ -355,7 +418,11 @@ still counts (rule 2). The listener forgets a code when it handles the
355418Every list entry is removed when it is answered or expires.
356419
357420** The listener** calls ` deleteWebhook ` at start and then ` getUpdates ` with
358- ` allowed_updates = ["callback_query"] ` . It accepts a tap only when all of
421+ ` allowed_updates = ["callback_query", "message"] ` . It keeps the last 200
422+ ` update_id ` s that it handled in its state file. An update with one of them
423+ was handled before: it is ignored, a tap and a message alike. A lower ID
424+ that is not in the list still counts, because Telegram may start the IDs
425+ again at a random number after a quiet week. It accepts a tap only when all of
359426these hold, else it answers "This question is closed." and writes nothing:
360427
361428- ` from.id ` is ` owner_id ` , and ` message.chat.id ` is ` chat_id ` ;
@@ -372,6 +439,30 @@ these hold, else it answers "This question is closed." and writes nothing:
372439Then it writes the approval, edits the question ("Apply tapped. Waiting for
373440the host." or "Skipped."), and answers the tap.
374441
442+ ** ` /check ` .** The listener writes a check request (section 8) only when all
443+ of these hold, else it writes nothing:
444+
445+ - ` from.id ` is ` owner_id ` , and ` chat.id ` is ` chat_id ` ;
446+ - it is a new message, not an edited one (no ` edited_message ` , no
447+ ` edit_date ` );
448+ - the text is exactly ` /check ` (a request for every instance in
449+ ` instances ` ) or exactly ` /check NAME ` , with one space and a NAME that is
450+ in ` instances ` . Nothing before, after or between: no second word, no new
451+ line, no ` @ ` . So ` /check@otherbot ` does nothing. The listener does not
452+ know its own bot name, so it refuses ` /check@ ` for its own name too (in a
453+ private chat Telegram sends ` /check ` without it).
454+
455+ Then it replies "Checking NAME…" to the message. A second ` /check ` for the
456+ same instance within 10 seconds writes nothing and gets "a check was asked
457+ a few seconds ago" (section 8, the start limit). When a request cannot be
458+ written (for example the host never ran pullgate for NAME, so the directory
459+ does not exist), it replies that the request was not saved. To the owner in
460+ the chat, a text that starts with ` /check ` but does not match gets the
461+ usage text, which lists the instances and never repeats the message. A
462+ message of another user, or in another chat, gets no answer. The listener
463+ never logs the text of a message: only why it was ignored and the sender
464+ ID.
465+
375466** Root** (` pullgate apply NAME ` ) takes the lock (with a wait). If the pause
376467file exists or ` mode = "off" ` , it removes the approvals, replies "ignored:
377468the instance is paused" (or off) to each question it knows, and exits.
@@ -528,6 +619,12 @@ closed after a cut.
528619 0600). The path unit starts ` pullgate apply ` , which handles it like an
529620 approval from the inbox, then removes it, and reports. The apply needs
530621 the same checks (code, time, forward only). For development hosts.
622+ ** ` /check ` on an ` auto ` instance** starts the run as the timer does, so a
623+ new commit is applied at once, without a tap. This is a choice: an auto
624+ instance applies every new commit within one timer period anyway, so
625+ ` /check ` only makes it sooner. It cannot apply a commit that the timer
626+ would not apply. The reply says "it is applied now, without a tap". Who
627+ does not want this keeps the instance in ` ask ` mode.
531628- ` off ` : ` pullgate run ` and ` pullgate apply ` do nothing.
532629
533630` pullgate status NAME ` prints the mode, the applied SHA, the open question,
@@ -566,7 +663,8 @@ Each rule and each limit has a test. The tests use a fake Telegram server
566663The end-to-end test (` test/e2e ` , build tag ` e2e ` ) builds the binary, makes a
567664bare repo with two commits, runs ` pullgate run ` , the listener against the
568665fake Telegram server, a tap, ` pullgate apply ` , and checks that the second
569- commit was applied.
666+ commit was applied. Then it sends ` /check ` and checks the request, the run
667+ and the reply "No new commit".
570668
571669The tests of ` install.sh ` (` install_linux_test.go ` , at the root) run the
572670script with ` /bin/sh ` against a fake release: a fake ` curl ` , ` uname ` , ` gh `
0 commit comments