Skip to content

Commit aae5203

Browse files
groupskyclaude
andcommitted
feat: update pullgate from Telegram: a notice for each new release, /update installs it with its units
pullgate update (root, pullgate-update.timer and pullgate-update.path) looks for a new release with the copy of install.sh built into the binary. It sends one notice per new release that passed the SHA-256 and attestation checks (a security release says so and repeats daily), and a warning for a release that failed them. /update asks with the version, the SHA-256 and the release link. Apply installs only that tarball, with every check again, then the units the new binary carries, reloads, re-enables and restarts them, restarts the listener last, and rolls back when the listener does not stay active. Fixes #9 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent cc21e75 commit aae5203

27 files changed

Lines changed: 3004 additions & 32 deletions

‎.github/workflows/ci.yml‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -99,9 +99,9 @@ jobs:
9999
echo "$out"
100100
# The "not executable" line of each service shows that systemd
101101
# really loaded our units.
102-
n="$(echo "$out" | grep -c -E '^pullgate-(apply@[^ ]*|listen|run@[^ ]*)\.service: Command /usr/local/bin/pullgate is not executable' || true)"
103-
if [ "$n" -ne 3 ]; then
104-
echo "expected 3 'not executable' lines (apply, listen, run), got $n" >&2
102+
n="$(echo "$out" | grep -c -E '^pullgate-(apply@[^ ]*|listen|run@[^ ]*|update)\.service: Command /usr/local/bin/pullgate is not executable' || true)"
103+
if [ "$n" -ne 4 ]; then
104+
echo "expected 4 'not executable' lines (apply, listen, run, update), got $n" >&2
105105
exit 1
106106
fi
107107
if echo "$out" \
@@ -144,13 +144,21 @@ jobs:
144144
with:
145145
go-version-file: go.mod
146146
- name: Build
147-
run: CGO_ENABLED=0 go build -trimpath -o "${RUNNER_TEMP}/pullgate" ./cmd/pullgate
148-
- name: The README install, then a good commit and a failed one
147+
# Two builds of this commit with release versions: the first is
148+
# installed, /update moves it to the second. The versions are far
149+
# above every real release, so the daily look at the real GitHub
150+
# (before the fake one is in place) finds nothing newer.
151+
run: |
152+
CGO_ENABLED=0 go build -trimpath -ldflags "-X main.version=900.0.0" -o "${RUNNER_TEMP}/pullgate" ./cmd/pullgate
153+
mkdir -p "${RUNNER_TEMP}/new"
154+
CGO_ENABLED=0 go build -trimpath -ldflags "-X main.version=900.0.1" -o "${RUNNER_TEMP}/new/pullgate" ./cmd/pullgate
155+
- name: The README install, a good commit, a failed one, and /update
149156
# The install commands come from README.md itself. Root and the
150157
# listener are different users, under the real units. A tap on a
151158
# fake Telegram applies a commit; a failing commit rolls back
152-
# (DESIGN.md section 14, issue #27).
153-
run: sudo sh test/units/full-loop.sh "${RUNNER_TEMP}/pullgate"
159+
# (DESIGN.md section 14, issue #27). Then /update installs the
160+
# second build from a fake GitHub, with its units (issue #9).
161+
run: sudo sh test/units/full-loop.sh "${RUNNER_TEMP}/pullgate" --update-to "${RUNNER_TEMP}/new/pullgate"
154162

155163
lint:
156164
runs-on: ubuntu-latest

‎AGENTS.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@ change code. They are the rules the code must follow.
2626
list, the cut to one message (DESIGN.md section 12).
2727
- `internal/gate/` - `run`, `apply` and `status` (DESIGN.md sections 7,
2828
9, 10, 13).
29+
- `internal/selfupdate/` - `pullgate update`: the notice of a new release,
30+
`/update`, and the install with its units (DESIGN.md section 15).
31+
- `embed.go` - the files that the binary carries: `install.sh` and the
32+
units of `contrib/systemd/`. The tests of `install.sh` are in the same
33+
package.
2934
- `contrib/` - example systemd units and example configs.
3035
- `install.sh` - installs or updates a release on a host, after its checks
3136
(DESIGN.md section 16). Its tests are `install_linux_test.go`, at the

‎DESIGN.md‎

Lines changed: 169 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ protects, and where it stops.
3232
starts a normal run now, instead of at the next timer (sections 8 and 9).
3333
- **pause file**: `/var/lib/pullgate/NAME/paused`. While it exists, the
3434
instance does nothing: no run, no apply.
35+
- **update question**: a question that names one release of pullgate
36+
itself: its version and the SHA-256 of its tarball (section 15).
3537

3638
## 2. The rules
3739

@@ -78,6 +80,7 @@ These rules come from issue #1. Each one has tests (section 14).
7880
| `check`, `summary` | `check_user` (default `pullgate-check`) | `pullgate run` | nothing |
7981
| `apply`, `health` | root | `pullgate apply` | what the owner's command needs |
8082
| `pullgate status NAME` | root | the owner | nothing |
83+
| `pullgate update` | root | a timer (`pullgate-update.timer`, daily), or a path unit (`pullgate-update.path`) for `/update` and a tap | the binary, the units, its own state (section 15) |
8184

8285
Root and the listener never talk directly. They use a spool directory
8386
(section 8). Both units start the same `pullgate-run@NAME.service`, so a
@@ -110,6 +113,9 @@ can be less strict; each example sets what its `apply` needs.
110113
| `/var/spool/pullgate/NAME/inbox` | listener, 0700 | approvals from the listener to root |
111114
| `/var/spool/pullgate/NAME/check` | listener, 0700 | check requests from the listener to root |
112115
| `/var/lib/pullgate-listener/state.json` | listener, 0600 | the listener's open questions |
116+
| `/var/lib/pullgate/_update/` and `.../tmp/` | root, 0700 | the state, the lock and the downloads of `pullgate update` (section 15) |
117+
| `/var/spool/pullgate/_update/` | as `NAME/` above | the outbox, inbox and check request of the updates |
118+
| `/usr/local/bin/.pullgate.prev` | root | the old binary during an update (a hard link) |
113119

114120
The paths can be changed with `--config-dir`, `--state-dir` and
115121
`--spool-dir`, for tests.
@@ -490,7 +496,7 @@ usage text, which lists the instances and never repeats the message.
490496

491497
**`/help`.** When the text is exactly `/help`, from `owner_id`, in
492498
`chat_id`, not edited, the listener replies with a fixed list: the
493-
commands (`/check`, `/check NAME`, `/help`), the instance names from
499+
commands (`/check`, `/check NAME`, `/update`, `/help`), the instance names from
494500
`instances`, what Apply and Skip do, and the root commands for the host
495501
(`pullgate status NAME`, `--pause`, `--resume`, `--ask-again`), at most
496502
once per minute. The
@@ -752,6 +758,17 @@ that cannot be enabled, fails CI. Without root, CI also runs
752758
checks that each unit the README tells you to enable has an `[Install]`
753759
section with `WantedBy=`.
754760

761+
`internal/selfupdate` tests `pullgate update` with the real built-in
762+
`install.sh` against a fake release (a fake `curl`, `gh` and `uname`, and
763+
fake binaries): the question, the install, a wrong SHA-256, a failed
764+
attestation, a wrong version (each before the question and on Apply), a
765+
tarball that changed after the question, an older version, a newer release
766+
while a question is open, Skip, an expired question, a listener that does
767+
not start (rollback), a crash at each step, the daily notice (once, again
768+
each day for a security release, off with `check = false`), and the unit
769+
update (a changed unit, a new unit, a masked unit, a disabled unit, a
770+
drop-in).
771+
755772
`test/units/full-loop.sh` (CI job `install-loop`, on each pull request
756773
and on `main`) is the path a user takes, as root on the throwaway runner:
757774

@@ -775,7 +792,14 @@ and on `main`) is the path a user takes, as root on the throwaway runner:
775792
4. It restarts the listener and checks that it polls again.
776793
5. A commit whose apply fails: the rollback runs, and its notice reaches
777794
the fake Telegram.
778-
6. Each unit of the README `start` block is `enabled` and `active`.
795+
6. With `--update-to` (the CI job builds this commit twice, as 900.0.0
796+
and 900.0.1): a fake GitHub (a fake `/usr/bin/curl` that serves local
797+
files, and a fake gh in `[updates] gh`, because the build under test has
798+
no attestation), a changed unit and a drop-in, then `/update` on the
799+
fake Telegram. The fake taps Apply; root installs 900.0.1 with the
800+
built-in `install.sh`, puts back the shipped unit, lists the drop-in,
801+
restarts the listener, and the new listener sends the report.
802+
7. Each unit of the README `start` block is `enabled` and `active`.
779803

780804
After each loop, the outbox must be empty and the listener must have
781805
logged no error and no warning. So a message that root writes and the
@@ -788,12 +812,143 @@ tag's own `install.sh --version X.Y.Z`, then runs
788812
The Release workflow calls it after it publishes; it also runs on
789813
`release: published` and by hand.
790814

791-
## 15. Not in version 0.1
815+
## 15. Updates of pullgate itself (`/update`)
816+
817+
The owner updates pullgate from Telegram. It is the same gate as for a
818+
commit: one question that names one exact release, and a tap. What it
819+
trusts: THREAT-MODEL.md, T20.
820+
821+
**The parts.** `pullgate update` runs as root, from
822+
`pullgate-update.service`. Two units start it: `pullgate-update.timer`
823+
(once a day) and `pullgate-update.path` (the check request or an approval
824+
of the updates). It reads `/etc/pullgate/listener.toml` (it needs no
825+
token), and uses its own state and spool, named `_update`
826+
(`/var/lib/pullgate/_update/`, `/var/spool/pullgate/_update/`). An instance
827+
name cannot start with `_`, so no instance can use them. The binary carries
828+
two things of its own version: a copy of `install.sh` (section 16), and the
829+
units of `contrib/systemd/` (`pullgate units` prints them as JSON, with the
830+
list of units that the README enables).
831+
832+
**The listener** handles `/update` as `/check`: only exactly `/update`,
833+
from `owner_id`, in `chat_id`, not edited. It writes the check request
834+
`_update/check/request` (the six bytes `check\n`, nothing from the
835+
message), at most one in 10 seconds, and replies "Looking for a new release
836+
of pullgate…". A tap on an update question writes an approval to
837+
`_update/inbox`, as for an instance (section 9). It sends what root puts
838+
in `_update/outbox`.
839+
840+
**Looking for a release.** Root runs the built-in `install.sh
841+
--check-only` with `TMPDIR=/var/lib/pullgate/_update/tmp`. The script does
842+
the checks of section 16 on the newest release (the SHA-256 and the
843+
attestation; it does not run the new binary before the tap), installs
844+
nothing, and
845+
prints lines that start with `@pullgate ` for root: `version X.Y.Z
846+
security|normal`, `up-to-date X.Y.Z`, `fetched X.Y.Z`, `checked X.Y.Z
847+
SHA256 security|normal`. A release is a security release when its notes
848+
have the section `### Security` (release-please makes it from `security:`
849+
pull requests, docs/releasing.md). Root itself checks again that the
850+
version is newer than its own. Then:
851+
852+
- **Up to date**: nothing. For `/update`, a notice says so.
853+
- **A newer release that passed every check**: for `/update`, root asks.
854+
From the timer, it sends one notice per release: the version, the link
855+
to the release notes and "send /update to install it". A security
856+
release says so on the first line, and its notice comes again each day
857+
(23 hours) until it is installed. A notice has no buttons and needs no
858+
tap. `[updates] check = false` in `listener.toml` stops the daily look
859+
and its notices; `/update` still works.
860+
- **A release that failed a check** (after its files were downloaded):
861+
one warning notice per release ("failed a check, so it is not
862+
offered"), with the reason from `install.sh`. It never gets a question
863+
or the "/update" hint. For `/update`, the warning comes each time.
864+
- **No answer from GitHub** (before the download): a log line; for
865+
`/update`, a notice. A build from the source (`pullgate dev`) does
866+
nothing and says so: it cannot know which release is newer.
867+
868+
At most one `/update` per minute is acted on (`check_at` in root's state).
869+
870+
**The question.** Root makes a new code, writes the question to its state
871+
(synced), then to the outbox, as in section 7:
872+
873+
```
874+
pullgate on <b>HOST</b>, update of pullgate
875+
⚠ Security release. It fixes a security problem. (only for one)
876+
Update pullgate to <code>X.Y.Z</code>?
877+
Installed now: <code>OLD</code>
878+
Release notes: https://github.com/code6x/pullgate/releases/tag/vX.Y.Z
879+
File: <code>pullgate_X.Y.Z_linux_ARCH.tar.gz</code>
880+
SHA-256: <code>…64 hex digits…</code>
881+
```
882+
883+
It can be answered for 12 hours. At most one update question is open.
884+
When the timer or `/update` finds a newer checked release while a question
885+
is open, root closes the old one ("a newer question replaced this one")
886+
and asks again. When the installed version is the newest again (installed
887+
by hand), it closes the question.
888+
889+
**Root's state**, `/var/lib/pullgate/_update/state.json` (root, 0600):
890+
`question` (id, code, version, sha256, asked, expires), `notified` and
891+
`warned` (release → time of its last notice), `check_at`, `check_note`,
892+
and `in_progress` (version, from, started) while an update runs.
893+
894+
**Apply.** `pullgate update` takes the lock (`_update/lock`), reads the
895+
approvals as in section 9 (code with a constant-time compare, time, once),
896+
and takes the version and the SHA-256 **from its own state**. Skip: a reply,
897+
nothing else. Apply, forward only (the version must be newer than its
898+
own; never an older one from Telegram):
899+
900+
1. Write `in_progress` (synced). Give the old binary a second name,
901+
`DIR/.pullgate.prev` (a hard link), and sync the directory.
902+
2. Run the built-in `install.sh --version X.Y.Z --sha256 SHA256
903+
--forward-only --bin-dir DIR` (and `--gh` from `[updates] gh`). It
904+
downloads the files again and does every check again; the tarball must
905+
also have the SHA-256 of the question. It renames the new file over
906+
`DIR/pullgate` as its last step. A failure here installs nothing: root
907+
removes `.pullgate.prev`, clears `in_progress` and reports why.
908+
3. Run `DIR/pullgate version`: it must print `pullgate X.Y.Z`.
909+
4. Run `DIR/pullgate units` (the new binary). Check the list: only names
910+
`pullgate-*.service`, `.timer`, `.path`, at most 32 files of 64 KiB.
911+
Write each unit that differs from `/etc/systemd/system/NAME` (a
912+
temporary file, sync, rename), and keep the old content. A unit there
913+
that is a link (masked) is left alone. Drop-ins
914+
(`/etc/systemd/system/pullgate-*.d/*`) are never changed; they are
915+
listed in the report.
916+
5. `systemctl daemon-reload`. For each unit that the README enables (for
917+
each instance in `instances`): when it is enabled, or new in this
918+
version, `systemctl reenable` and `systemctl restart` it. A unit that
919+
the owner disabled stays disabled. The listener is re-enabled here,
920+
but restarted last.
921+
6. `systemctl restart pullgate-listen.service`, wait 5 seconds, and check
922+
`systemctl is-active pullgate-listen.service`.
923+
7. Remove `.pullgate.prev`, clear `in_progress`, and write the report:
924+
"pullgate is updated: OLD → NEW", the units it installed, the links it
925+
left alone, and every drop-in. The new listener sends it.
926+
927+
When step 3, 4, 5 or 6 fails: rename `.pullgate.prev` back over
928+
`DIR/pullgate`, write back the old unit files (and remove the new ones),
929+
`daemon-reload`, restart the units and the listener, clear `in_progress`,
930+
and report "the update failed: REASON. pullgate OLD is back". If the
931+
rollback has problems too, the report says which, and how to fix it by
932+
hand with `install.sh`.
933+
934+
**A crash** leaves `in_progress`. The binary is the old file or the new
935+
one: each change of the name `pullgate` is a rename in one directory, after
936+
a sync (THREAT-MODEL.md, T10). The next start reports "the update was cut
937+
off" with what `pullgate version` says, and how to check the host. It does
938+
not guess, and leaves `.pullgate.prev` for the owner.
939+
940+
**The config** (in `listener.toml`, every key optional):
792941

793-
- Self-update of pullgate. `install.sh` updates it only when root runs
794-
the script (section 16).
795-
- Signed commits (`git verify-commit`).
796-
- A web UI.
942+
```toml
943+
[updates]
944+
check = true # false: no daily look, no notices; /update works
945+
listener_user = "pullgate" # the listener user: owns the inbox of the updates
946+
gh = "/usr/bin/gh" # the gh that checks the attestation, as install.sh --gh
947+
```
948+
949+
There is no key to skip a check.
950+
951+
**Not yet**: signed commits (`git verify-commit`), a web UI.
797952

798953
## 16. The install script
799954

@@ -804,6 +959,13 @@ It is a POSIX `sh` script. Root runs it on the host itself:
804959
sh install.sh [--version X.Y.Z] [--bin-dir DIR] [--gh PATH] [--reinstall]
805960
```
806961

962+
`pullgate update` runs the copy of this script that is built into the
963+
binary, with three more flags (section 15): `--check-only` (every check,
964+
install nothing), `--sha256 HEX` (with `--version`: install only a tarball
965+
with this SHA-256) and `--forward-only` (never the same or an older
966+
version). It reads the lines that start with `@pullgate ` on the standard
967+
output.
968+
807969
All the work is in functions. Only the last line starts `main`, so a
808970
download that stops in the middle runs nothing. The steps:
809971

0 commit comments

Comments
 (0)