Skip to content

Commit 9095c14

Browse files
groupskyclaude
andcommitted
feat: /check from Telegram to look for a new commit now
Refs #8 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 8cc4e3a commit 9095c14

16 files changed

Lines changed: 1206 additions & 46 deletions

File tree

‎DESIGN.md‎

Lines changed: 107 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -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).
5358
5. **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

7681
Root 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

7986
The run unit is sandboxed (read-only system, private `/tmp`, no new
8087
privileges). 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

104112
The 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
121129
through the open directory, creates files in them with
122130
`O_CREAT|O_EXCL|O_NOFOLLOW` under a random temporary name and renames them
123131
in 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

268276
1. 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.
271282
2. If the state shows an apply in progress (section 10), write the pause
272283
file, report, and exit.
273284
3. Make sure the clone and the spool directories exist with the right owners
@@ -338,6 +349,58 @@ files older than one minute.
338349
auto approval (`PathExists=`), and starts `pullgate apply NAME`. The apply
339350
service 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

343406
Root keeps its questions in `state.json`:
@@ -355,7 +418,11 @@ still counts (rule 2). The listener forgets a code when it handles the
355418
Every 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
359426
these 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:
372439
Then it writes the approval, edits the question ("Apply tapped. Waiting for
373440
the 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
376467
file exists or `mode = "off"`, it removes the approvals, replies "ignored:
377468
the 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
566663
The end-to-end test (`test/e2e`, build tag `e2e`) builds the binary, makes a
567664
bare repo with two commits, runs `pullgate run`, the listener against the
568665
fake 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

571669
The tests of `install.sh` (`install_linux_test.go`, at the root) run the
572670
script with `/bin/sh` against a fake release: a fake `curl`, `uname`, `gh`

‎README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,10 +109,36 @@ cp contrib/systemd/* /etc/systemd/system/
109109
systemctl daemon-reload
110110
systemctl enable --now pullgate-listen.service
111111
systemctl enable --now pullgate-apply@NAME.path pullgate-run@NAME.timer
112+
systemctl enable --now pullgate-check@NAME.path # optional: /check
112113
```
113114

114115
Every step logs to the journal: `journalctl -t pullgate`.
115116

117+
## Check now: `/check`
118+
119+
The timer runs every 5 minutes. After a push you do not have to wait: send
120+
the bot `/check` (all instances) or `/check NAME` (one instance). The
121+
listener answers "Checking NAME…" and writes a check request.
122+
`pullgate-check@NAME.path` then starts the normal run at once. You get the
123+
usual Apply question, or "No new commit (the applied commit is …)", or
124+
"NAME is paused" / "NAME is off" (then nothing is fetched).
125+
126+
- Only your user ID in your chat counts. The text must be exactly
127+
`/check` or `/check NAME`. Other messages get no request. Edited messages
128+
do not count.
129+
- `/check` never applies anything in `ask` mode: it only fetches and asks.
130+
**In `auto` mode, `/check` applies a new commit at once, without a tap**,
131+
as the timer would a few minutes later.
132+
- Root allows at most one run per minute from `/check`. More requests in
133+
that minute are dropped, with one reply. The listener also takes at most
134+
one `/check` per instance in 10 seconds.
135+
- `pullgate-check@NAME.path` stops after 10 starts in a minute. Then
136+
`/check` waits for the timer until you run
137+
`systemctl reset-failed pullgate-check@NAME.path` and
138+
`systemctl start pullgate-check@NAME.path`.
139+
- Without `pullgate-check@NAME.path`, the request waits for the next timer
140+
run.
141+
116142
## Config
117143

118144
The instance config `/etc/pullgate/NAME.toml`:

0 commit comments

Comments
 (0)