Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -499,7 +499,24 @@ nothing):
- Then the normal run goes on, so a stream of `/status` never stops the
fetches. After a `/pause`, the run ends as paused.

To go on after `/pause`, root runs `pullgate status NAME --resume`.
**`/resume NAME` and `/ask-again NAME`** (code6x/pullgate#33) go the same
way, with request files `resume` and `ask-again`. They are limited, so
that they cannot undo a safety stop:

- `resume`: root lifts the pause only if the pause file is one that
`/pause` wrote: a regular file of root, with one link, of exactly one
line `paused from Telegram at YYYY-MM-DD HH:MM UTC`. A pause by pullgate
itself (a cut-off apply), by root (`pullgate status --pause`) or with
any other text stays, and the reply says to run `pullgate status NAME
--resume` as root. `/resume` never ends the broken state (section 10).
- `ask-again`: root clears only an open question for the last tip (its
message may be lost; the next question has a new code) or an `expired`
mark, and saves the state before the listener closes the message. It
refuses every other case: a tip that is skipped, failed, held, refused,
failed its check, the failed commit of the broken state, or an instance
that is paused or off. When `resume` and `pause` come in one run, the
pause wins. Root's `pullgate status
NAME --ask-again` still clears every mark.

**`/check`.** The listener writes a check request (section 8) only when all
of these hold, else it writes nothing:
Expand Down
13 changes: 11 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,16 +191,25 @@ usual Apply question, or "No new commit (the applied commit is …)", or
- Without `pullgate-check@NAME.path`, the request waits for the next timer
run.

## Status and pause: `/status`, `/pause`
## Status and pause: `/status`, `/pause`, `/resume`, `/ask-again`

- `/status` (all instances) or `/status NAME`: the mode, the applied
commit, the last tip, the open question, paused or not and why, broken
or not. It changes nothing. At most one answer per instance a minute.
- `/pause NAME`: pauses the instance. Nothing is fetched, asked or applied
until root runs `pullgate status NAME --resume` on the host. If it is
until you send `/resume NAME` (or root runs `pullgate status NAME --resume`). If it is
paused already, the old pause stays as it is. A reason after NAME is not
sent to the host.

- `/resume NAME`: lifts a pause that `/pause` set. Whoever holds the bot
token can do that too: if you suspect the token, pause as root. Any other pause (one
that pullgate set itself after a cut-off apply, or one that root set)
stays: run `pullgate status NAME --resume` as root.
- `/ask-again NAME`: asks again about the newest commit, but only when its
question expired or was lost. A commit that was skipped, failed, held or
refused is not asked again from Telegram; root can, with
`pullgate status NAME --ask-again`.

As with `/check`, only your user ID in your chat counts, and the listener
only writes a small request file; root does the work.

Expand Down
19 changes: 17 additions & 2 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -479,7 +479,7 @@ until the owner resets it (DESIGN.md section 8). The run unit has no start
limit, so the timer goes on. This denies; it never approves. A clock jump back of more than
a minute allows one more run.

### T18b. `/status` and `/pause` from a stolen token or the listener
### T18b. `/status`, `/pause`, `/resume`, `/ask-again` from a stolen token or the listener

*Attack.* Someone with the bot token, or a compromised listener, sends
`/status` or `/pause`, or writes the request files directly.
Expand All @@ -500,7 +500,22 @@ reads its own state and acts. So the most they can do:
`/pause` cannot replace the reason of a safety pause, and a later
limited `/resume` (code6x/pullgate#33) cannot use it to lift one.

They cannot resume, approve, or change the state: the state directory is
*`/resume` and `/ask-again`* (code6x/pullgate#33) can undo a stop, so
they are limited. `/resume` lifts only a pause whose file is exactly what
`/pause` writes (root's regular file, one link, one line in that form):
the only pause a thief could set anyway. So if the owner suspects the
token or the listener, the owner pauses as root (`pullgate status NAME
--pause`): a token holder can lift a `/pause`. `/resume` moves the file
aside and checks that it is the file it checked, so a pause that root
writes at the same moment is put back and stays. A pause that pullgate set after a
cut-off apply, or that root set, stays, and so does the broken state
(T6). `/ask-again` clears only an expired mark or an open question; it
never re-asks a commit that the owner skipped or that failed, was held or
was refused, so a thief cannot re-ask a skipped commit and hope for a
wrong tap. A new question still needs the owner's tap, and counts in
`questions_per_day`.

Apart from that, they cannot approve or change the state: the state directory is
root's (0700), and any other file in the check directory is removed and
does nothing (a test).

Expand Down
2 changes: 1 addition & 1 deletion internal/gate/apply.go
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ func (e *Env) ignoreAll(st *state.State, paused bool) (Result, error) {
why := "the instance is off (mode = \"off\")."
res := Off
if paused {
why = "the instance is paused. Run as root: <code>pullgate status " + e.Cfg.Name + " --resume</code>"
why = "the instance is paused. " + e.resumeHint()
res = Paused
}
for {
Expand Down
82 changes: 80 additions & 2 deletions internal/gate/check.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import (
"strings"
"time"

"github.com/code6x/pullgate/internal/config"
"github.com/code6x/pullgate/internal/message"
"github.com/code6x/pullgate/internal/spool"

Expand All @@ -27,11 +28,20 @@ func (e *Env) takeChecks() spool.Requests {
e.Log.Error("read the check requests", "err", err)
}
if r.Any() {
e.Log.Info("requests taken", "check", r.Check, "status", r.Status, "pause", r.Pause)
e.Log.Info("requests taken", "check", r.Check, "status", r.Status, "pause", r.Pause, "resume", r.Resume, "ask-again", r.AskAgain)
}
return r
}

// resumeHint says how to go on after a pause: /resume for a /pause, else
// root.
func (e *Env) resumeHint() string {
if e.Dir.TelegramPaused(e.UID) {
return "Send <code>/resume " + e.Cfg.Name + "</code>"
}
return "Run as root: <code>pullgate status " + e.Cfg.Name + " --resume</code>"
}

// pauseRequest acts on /pause: it writes the pause file, unless there is
// one. A pause that is there already is never changed, so that a later
// /resume (code6x/pullgate#33) cannot lift it. The pause itself is never
Expand All @@ -48,14 +58,82 @@ func (e *Env) pauseRequest(st *state.State) {
text = "⏸ " + e.Cfg.Name + " was paused already: " + message.Code(e.Dir.PauseReason())
default:
e.Log.Info("paused from Telegram")
text = "⏸ " + e.Cfg.Name + " is paused. Nothing is fetched, asked or applied. To go on, run as root: <code>pullgate status " + e.Cfg.Name + " --resume</code>"
text = "⏸ " + e.Cfg.Name + " is paused. Nothing is fetched, asked or applied. To go on, send <code>/resume " + e.Cfg.Name + "</code>."
}
if d := now.Sub(st.PauseNote); d >= CheckInterval || d <= -CheckInterval {
st.PauseNote = now
e.notice(text)
}
}

// resumeRequest acts on /resume: it lifts only a pause that /pause wrote
// (code6x/pullgate#33). A pause by pullgate itself (a cut-off apply) or by
// root stays: a compromised listener must not undo a safety stop.
func (e *Env) resumeRequest(st *state.State) {
var text string
switch {
case !e.Dir.Paused():
text = e.Cfg.Name + " is not paused."
default:
lifted, err := e.Dir.ResumeTelegram(e.UID)
if err != nil {
e.Log.Error("remove the pause file", "err", err)
text = "Error: " + e.Cfg.Name + " could not be resumed. See the journal of the host."
break
}
if !lifted {
text = "⏸ " + e.Cfg.Name + " stays paused: this pause was not set from Telegram (" + message.Code(e.Dir.PauseReason()) + "), so /resume does not lift it. Check the host, then run as root: <code>pullgate status " + e.Cfg.Name + " --resume</code>"
break
}
e.Log.Info("resumed from Telegram")
text = "▶ " + e.Cfg.Name + " goes on."
if st.Broken != nil {
text += " It is still broken: only a fix forward is asked."
}
}
e.notice(text)
}

// askAgainRequest acts on /ask-again: it asks again only about a question
// that expired or was lost (an open one), never about a commit that was
// skipped, failed, held, refused or failed its check (code6x/pullgate#33).
func (e *Env) askAgainRequest(st *state.State) {
tip := st.LastTip
m := st.Marks[tip]
switch {
case e.Dir.Paused() || e.Cfg.Mode == config.ModeOff:
e.notice("Not asked again: " + e.Cfg.Name + " is paused or off. Resume it first.")
case tip == "" || tip == st.Applied:
e.notice("Nothing to ask again: there is no new commit.")
case st.Broken != nil && (tip == st.Broken.SHA || tip == st.Broken.OldSHA):
e.notice("Not asked again: " + code(tip) + " is the failed commit of the broken state. Push a fix forward, or check the host and run as root: <code>pullgate status " + e.Cfg.Name + " --resume</code>")
case tip == st.Held:
e.notice("Not asked again: the apply of " + code(tip) + " failed and it is held. To try it again, run as root: <code>pullgate status " + e.Cfg.Name + " --ask-again</code>")
case m != nil && m.Mark == state.MarkAsked:
q := forgetOpen(st, tip)
delete(st.Marks, tip)
// Save first: the listener forgets the code only when root has.
if err := e.Dir.Save(st); err != nil {
e.Log.Error("save the state", "err", err)
e.notice("Error: the question could not be closed. See the journal of the host.")
return
}
if q != nil && !q.Auto {
e.edit(q.ID, "This question for "+code(q.SHA)+" is closed: the owner sent /ask-again. The next question has a new code.")
}
e.Log.Info("ask again from Telegram: open question", "sha", tip)
e.notice("Asking again about " + code(tip) + ".")
case m != nil && m.Mark == state.MarkExpired:
delete(st.Marks, tip)
e.Log.Info("ask again from Telegram: expired question", "sha", tip)
e.notice("Asking again about " + code(tip) + ".")
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: <code>pullgate status " + e.Cfg.Name + " --ask-again</code>")
}
}

// statusRequest answers /status with the facts of "pullgate status",
// at most once a minute.
func (e *Env) statusRequest(st *state.State) {
Expand Down
177 changes: 177 additions & 0 deletions internal/gate/request_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -113,3 +113,180 @@ func TestListenerCannotPauseByOtherFiles(t *testing.T) {
})
}
}

func TestResumeLiftsOnlyATelegramPause(t *testing.T) {
cases := map[string]func(f *fixture){
"root --pause": func(f *fixture) { _ = f.env.Status(new(strings.Builder), StatusFlags{Pause: true}) },
"cut off": func(f *fixture) { _ = f.env.Dir.Pause("the apply of x was cut off") },
"planted prefix": func(f *fixture) { _ = f.env.Dir.Pause(state.TelegramPause + "2026-11-11 12:00 UTC and more") },
"two lines": func(f *fixture) { _ = f.env.Dir.Pause(state.TelegramPause + "2026-11-11 12:00 UTC\nx") },
"telegram": nil,
}
for name, pause := range cases {
t.Run(name, func(t *testing.T) {
f := newFixture(t, ``, "")
f.applyNew("one")
if pause == nil {
f.requestKind(spool.RequestPause)
f.run()
} else {
pause(f)
}
f.outbox()
f.requestKind(spool.RequestResume)
f.run()
out := f.outbox()
if pause == nil {
if f.env.Dir.Paused() || !contains(out, "goes on") {
t.Fatal("/resume must lift a /pause")
}
return
}
if !f.env.Dir.Paused() || !contains(out, "this pause was not set from Telegram") {
t.Fatalf("/resume must not lift this pause: %+v", out)
}
})
}
}

func TestResumeDoesNotEndBroken(t *testing.T) {
f := newFixture(t, `on_failure = "rollback"`, "")
breakIt(t, f)
f.requestKind(spool.RequestPause)
f.run()
f.requestKind(spool.RequestResume)
f.run()
if f.env.Dir.Paused() || f.state().Broken == nil || !contains(f.outbox(), "still broken") {
t.Fatal("/resume lifts the pause, but the broken state stays")
}
}

func TestAskAgainOnlyExpiredOrLost(t *testing.T) {
t.Run("expired", func(t *testing.T) {
f := newFixture(t, ``, "")
f.applyNew("one")
f.commit("second", "two", nil)
f.run()
f.ask()
f.now = f.now.Add(13 * time.Hour) // approval_ttl is 12h
if r := f.run(); r != Nothing {
t.Fatalf("after expiry: %s", r)
}
f.outbox()
f.requestKind(spool.RequestAskAgain)
if r := f.run(); r != Asked {
t.Fatalf("/ask-again on an expired question: %s", r)
}
})
t.Run("lost", func(t *testing.T) {
f := newFixture(t, ``, "")
f.applyNew("one")
f.commit("second", "two", nil)
f.run()
old := f.ask() // as if it never reached the chat
f.requestKind(spool.RequestAskAgain)
if r := f.run(); r != Asked {
t.Fatalf("/ask-again on an open question: %s", r)
}
if f.ask().Code == old.Code {
t.Fatal("the new question needs a new code")
}
})
for _, mark := range []string{"skipped", "failed", "held", "refused", "check-failed"} {
t.Run(mark, func(t *testing.T) {
f := newFixture(t, ``, "")
f.applyNew("one")
sha := f.commit("second", "two", nil)
f.run()
f.outbox()
st := f.state()
st.Questions = nil
if mark == "held" {
st.Held = sha
st.SetMark(sha, state.MarkFailed, f.now)
} else {
st.SetMark(sha, mark, f.now)
}
if err := f.env.Dir.Save(st); err != nil {
t.Fatal(err)
}
f.requestKind(spool.RequestAskAgain)
if r := f.run(); r != Nothing {
t.Fatalf("/ask-again on %s: %s", mark, r)
}
if !contains(f.outbox(), "Not asked again") {
t.Fatal("no reply")
}
})
}
}

func TestTelegramPauseFileForm(t *testing.T) {
good := state.TelegramPause + "2026-11-11 12:00 UTC"
for name, setup := range map[string]func(f *fixture){
"hard link": func(f *fixture) {
_ = f.env.Dir.Pause(good)
_ = os.Link(f.env.Dir.PauseFile(), f.env.Dir.PauseFile()+"2")
},
"symlink": func(f *fixture) {
other := filepath.Join(f.base, "other")
_ = os.WriteFile(other, []byte(good+"\n"), 0o644)
_ = os.Symlink(other, f.env.Dir.PauseFile())
},
"trailing space": func(f *fixture) { _ = f.env.Dir.Pause(good + " ") },
"not UTC": func(f *fixture) { _ = f.env.Dir.Pause(state.TelegramPause + "2026-11-11 12:00 CET") },
} {
t.Run(name, func(t *testing.T) {
f := newFixture(t, ``, "")
if err := f.env.Dir.Ensure(); err != nil {
t.Fatal(err)
}
setup(f)
if f.env.Dir.TelegramPaused(f.env.UID) {
t.Fatal("must not count as a /pause")
}
if ok, _ := f.env.Dir.ResumeTelegram(f.env.UID); ok || !f.env.Dir.Paused() {
t.Fatal("must not be lifted")
}
})
}
}

func TestPauseWinsOverResumeInOneRun(t *testing.T) {
f := newFixture(t, ``, "")
f.applyNew("one")
f.requestKind(spool.RequestPause)
f.run()
f.now = f.now.Add(2 * time.Minute)
f.requestKind(spool.RequestResume)
f.requestKind(spool.RequestPause)
f.run()
if !f.env.Dir.Paused() {
t.Fatal("with /resume and /pause in one run, the pause wins")
}
}

func TestAskAgainRefusedWhilePausedOrBroken(t *testing.T) {
f := newFixture(t, `on_failure = "rollback"`, "")
breakIt(t, f)
f.outbox()
f.requestKind(spool.RequestAskAgain)
f.run()
if !contains(f.outbox(), "failed commit of the broken state") {
t.Fatal("/ask-again must refuse the broken failed commit")
}
g := newFixture(t, ``, "")
g.applyNew("one")
g.commit("second", "two", nil)
g.run()
q := g.ask()
_ = g.env.Dir.Pause("paused by the owner")
g.requestKind(spool.RequestAskAgain)
g.run()
if !contains(g.outbox(), "is paused or off") {
t.Fatal("/ask-again while paused must be refused")
}
if g.state().FindCode(q.Code) < 0 {
t.Fatal("the question must stay while paused")
}
}
Loading