diff --git a/docs/ntfy.md b/docs/ntfy.md index ff87cb66..f0c1ae54 100644 --- a/docs/ntfy.md +++ b/docs/ntfy.md @@ -113,6 +113,38 @@ ordered by importance — a run waiting for a decision, then a failed run, then run that finished since the operator last looked — derived from the run events the server already pushes, so it needs no refresh and starts nothing. +## Tapping a notification + +Run notifications (stage hooks and run-level waiting/failed/succeeded alerts) +set the ntfy `Click` to the app deep link `pipelines://run/`, so a tap on the +phone opens the native Pipelines app at that run. When `PIPELINES_WEB_PUBLIC_URL` +is set to a valid HTTP(S) origin (no credentials, path, query or fragment), each +notification also gets one ntfy `view` action, **Open in browser**, pointing at +`/runs/`. Without it, or with an invalid value, only the app link is +sent. Queued run notifications derive both links from the run id at delivery, +so rows queued by older servers (which stored a web URL) also open the app. + +## Chats that need you + +When a chat asks the operator something — an unresolved question/form or a +permission (approval) request — the server publishes one notification to the +`system` destination: title ` needs your answer` (or `... needs your +approval` for permissions; `Chat` when the session has no title), the question or +permission text as the body, `Click` `pipelines://chat/`, and the +**Open in browser** action to `/chat/` when +`PIPELINES_WEB_PUBLIC_URL` is set. Ordinary finished replies do not notify. + +- Each form/request id notifies at most once per server process: duplicate + events, reconnects and replays of a still-pending question are deduplicated in + memory, and a form first seen already resolved or cancelled never notifies. + The record is not persisted, so a request still pending across a server + restart can notify once more. +- The server only observes a chat while at least one client is subscribed to + it, so questions raised while no client watches the session are not seen. +- Publishing is asynchronous within the same 30-second budget, never blocks or + fails chat handling, and failures are only logged. Nothing is sent when + `PIPELINES_NTFY_URL` is not configured. + ## Explicit delivery stage (optional) The preceding stage must output three nonempty UTF-8 strings: `title`, `summary`, diff --git a/internal/server/chat_attention.go b/internal/server/chat_attention.go new file mode 100644 index 00000000..f448e293 --- /dev/null +++ b/internal/server/chat_attention.go @@ -0,0 +1,159 @@ +package server + +import ( + "context" + "log" + "net/url" + "os" + "strings" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" + "git.a-wan.net/alan/pipelines/internal/stage" +) + +// chatAttentionRetainedLimit bounds the hub-wide set of form/permission ids that +// already produced (or never deserve) an attention notification. +const chatAttentionRetainedLimit = 1024 + +// chatAttentionPublish is the publisher; tests may replace it. +var chatAttentionPublish = stage.PublishNtfy + +// chatAttention is one pending operator-attention notification for a chat. +type chatAttention struct { + sessionID string + approval bool + body string +} + +// claimChatAttentionLocked records key in the hub-wide dedupe set and reports +// whether it was new. Unlike the per-room sets it survives reconnects and room +// teardown, so a replayed pending form or approval is not announced twice. +// Callers must hold h.mu. +func (h *chatHub) claimChatAttentionLocked(key string) bool { + if h.attentionSeen == nil { + h.attentionSeen = map[string]struct{}{} + } + if _, ok := h.attentionSeen[key]; ok { + return false + } + h.attentionSeen[key] = struct{}{} + h.attentionOrder = append(h.attentionOrder, key) + if len(h.attentionOrder) > chatAttentionRetainedLimit { + delete(h.attentionSeen, h.attentionOrder[0]) + h.attentionOrder = h.attentionOrder[1:] + } + return true +} + +// noteFormAttentionLocked notifies the operator once about an unresolved +// question/form. A form first seen resolved or cancelled is only recorded, so a +// later stale copy cannot announce it. Callers must hold h.mu. +func (h *chatHub) noteFormAttentionLocked(frame protocol.ChatEventFrame) { + if frame.Kind != protocol.ChatEventForm || frame.Form == nil || frame.Form.ID == "" || frame.SessionID == "" || !chatAttentionConfigured() { + return + } + form := frame.Form + if !h.claimChatAttentionLocked("form\x00" + frame.SessionID + "\x00" + form.ID) { + return + } + if form.Resolved || form.Cancelled { + return + } + body := form.Title + if len(form.Fields) > 0 { + question := form.Fields[0].Title + if question == "" { + question = form.Fields[0].Description + } + if body == "" { + body = question + } else if question != "" && question != body { + body += ": " + question + } + } + if strings.TrimSpace(body) == "" { + body = "The agent asked a question" + } + kind := strings.ToLower(form.Kind) + h.startChatAttention(chatAttention{sessionID: frame.SessionID, approval: strings.Contains(kind, "permission") || strings.Contains(kind, "approval"), body: body}) +} + +// notePermissionAttentionLocked notifies the operator once about a pending +// approval request. Callers must hold h.mu. +func (h *chatHub) notePermissionAttentionLocked(frame protocol.ChatPermissionFrame) { + if frame.RequestID == "" || frame.SessionID == "" || frame.Resolved || !chatAttentionConfigured() { + return + } + if !h.claimChatAttentionLocked("permission\x00" + frame.SessionID + "\x00" + frame.RequestID) { + return + } + body := frame.Message + if strings.TrimSpace(body) == "" && frame.Action != "" { + body = "Allow " + frame.Action + if len(frame.Resources) > 0 { + body += " " + frame.Resources[0] + } + } + if strings.TrimSpace(body) == "" { + body = "The agent asked for permission" + } + h.startChatAttention(chatAttention{sessionID: frame.SessionID, approval: true, body: body}) +} + +func chatAttentionConfigured() bool { + return os.Getenv("PIPELINES_NTFY_URL") != "" +} + +// startChatAttention publishes asynchronously within the 30-second notification +// budget. It never blocks or fails chat handling; failures are only logged. +func (h *chatHub) startChatAttention(a chatAttention) { + base := h.baseCtx + if base == nil { + base = context.Background() + } + registry := h.registry + h.attentionWG.Add(1) + go func() { + defer h.attentionWG.Done() + ctx, cancel := context.WithTimeout(base, 30*time.Second) + defer cancel() + name := "" + if registry != nil { + if session, found, err := registry.OperatorSession(ctx, a.sessionID); err == nil && found { + name = session.Title + } + } + title, body := chatAttentionText(name, a.approval, a.body) + click, views := chatAttentionLinks(a.sessionID) + if _, err := chatAttentionPublish(ctx, "system", title, body, "", nil, click, views...); err != nil { + log.Printf("chat attention notification session=%s: %v", a.sessionID, err) + } + }() +} + +// chatAttentionText builds a single-line ntfy title/body within PublishNtfy's +// limits. +func chatAttentionText(name string, approval bool, body string) (string, string) { + name = singleLine(name) + if name == "" { + name = "Chat" + } + suffix := " needs your answer" + if approval { + suffix = " needs your approval" + } + return truncateUTF8(name, 256-len(suffix)) + suffix, truncateUTF8(singleLine(body), 2000) +} + +// singleLine folds whitespace (including CR/LF) to single spaces and drops NULs. +func singleLine(text string) string { + return strings.Join(strings.Fields(strings.ReplaceAll(text, "\x00", "")), " ") +} + +// chatAttentionLinks opens the chat in the app; the web origin, when +// configured, is offered as an "Open in browser" action. +func chatAttentionLinks(sessionID string) (string, []stage.NtfyView) { + escaped := url.PathEscape(sessionID) + return "pipelines://chat/" + escaped, webAttentionViews("/chat/" + escaped) +} diff --git a/internal/server/chat_hub.go b/internal/server/chat_hub.go index 7980a29c..5a3bd63f 100644 --- a/internal/server/chat_hub.go +++ b/internal/server/chat_hub.go @@ -41,6 +41,12 @@ type chatHub struct { // userSeq is a monotonic source of ids for the user turns the server echoes // to the other clients, so each retained user message has a stable id. userSeq int + // attentionSeen/attentionOrder are the bounded hub-wide record of forms and + // approval requests already considered for an ntfy attention notification; + // attentionWG tracks in-flight publications. + attentionSeen map[string]struct{} + attentionOrder []string + attentionWG sync.WaitGroup } // chatPart is the retained form of one part. Text and reasoning deltas append to diff --git a/internal/server/chat_room.go b/internal/server/chat_room.go index 181a99df..20745404 100644 --- a/internal/server/chat_room.go +++ b/internal/server/chat_room.go @@ -408,6 +408,7 @@ func (h *chatHub) emitRoom(source *chatRoom, frame protocol.ChatEventFrame) { h.clearCompactionLocked(room) } h.applyLocked(frame) + h.noteFormAttentionLocked(frame) buffered := false var targets []*chatSub if room != nil { @@ -652,6 +653,7 @@ func (h *chatHub) pushPermission(sessionID string, frame protocol.ChatPermission } } room.pending = append(room.pending, frame) + h.notePermissionAttentionLocked(frame) if len(room.pending) > chatRoomPendingLimit { room.pending = room.pending[len(room.pending)-chatRoomPendingLimit:] } diff --git a/internal/server/main_test.go b/internal/server/main_test.go new file mode 100644 index 00000000..8868d371 --- /dev/null +++ b/internal/server/main_test.go @@ -0,0 +1,16 @@ +package server + +import ( + "os" + "testing" +) + +// TestMain isolates the package from an operator's real notification setup: +// a developer shell may export the installed server's ntfy configuration, and +// no test may publish to it. Tests that need ntfy point it at an httptest server. +func TestMain(m *testing.M) { + for _, name := range []string{"PIPELINES_NTFY_URL", "PIPELINES_NTFY_PUBLIC_URL", "PIPELINES_NTFY_TOKEN", "PIPELINES_NTFY_TOKEN_FILE", "PIPELINES_WEB_PUBLIC_URL"} { + os.Unsetenv(name) + } + os.Exit(m.Run()) +} diff --git a/internal/server/notification_web_test.go b/internal/server/notification_web_test.go index c312b547..e82df5c2 100644 --- a/internal/server/notification_web_test.go +++ b/internal/server/notification_web_test.go @@ -1,12 +1,26 @@ package server -import "testing" +import ( + "context" + "encoding/json" + "mime" + "net/http" + "net/http/httptest" + "path/filepath" + "sync" + "testing" + "time" -func TestRunNotificationWebClick(t *testing.T) { - for _, tc := range []struct{ base, want string }{ + "git.a-wan.net/alan/pipelines/internal/pipeline" + "git.a-wan.net/alan/pipelines/internal/protocol" + "git.a-wan.net/alan/pipelines/internal/stage" +) + +func TestRunNotificationAppClickAndWebAction(t *testing.T) { + for _, tc := range []struct{ base, view string }{ {"https://pipelines.example.com", "https://pipelines.example.com/runs/20"}, {"http://10.0.0.75:8095/", "http://10.0.0.75:8095/runs/20"}, - {"", "pipelines://run/20"}, // Existing Android-only installations. + {"", ""}, // No web origin: the app link alone. {"javascript:alert(1)", ""}, {"https://user:password@example.com", ""}, {"https://example.com?token=secret", ""}, @@ -17,9 +31,222 @@ func TestRunNotificationWebClick(t *testing.T) { } { t.Run(tc.base, func(t *testing.T) { t.Setenv("PIPELINES_WEB_PUBLIC_URL", tc.base) - if got := runAttentionClick(20); got != tc.want { - t.Fatalf("click = %q, want %q", got, tc.want) + if got := runAttentionClick(20); got != "pipelines://run/20" { + t.Fatalf("click = %q", got) + } + views := runAttentionViews(20) + if tc.view == "" { + if len(views) != 0 { + t.Fatalf("unexpected views %+v", views) + } + return + } + if len(views) != 1 || views[0].Label != "Open in browser" || views[0].URL != tc.view { + t.Fatalf("views = %+v, want %q", views, tc.view) } }) } } + +type ntfyCapture struct { + Title, Message, Click, Actions string +} + +// newNtfyCapture points the system destination at a mock ntfy endpoint. +func newNtfyCapture(t *testing.T) func() []ntfyCapture { + t.Helper() + var mu sync.Mutex + var got []ntfyCapture + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + decoder := new(mime.WordDecoder) + title, _ := decoder.DecodeHeader(r.Header.Get("Title")) + message, _ := decoder.DecodeHeader(r.Header.Get("Message")) + mu.Lock() + got = append(got, ntfyCapture{title, message, r.Header.Get("Click"), r.Header.Get("Actions")}) + mu.Unlock() + _ = json.NewEncoder(w).Encode(map[string]string{"id": "msg", "event": "message"}) + })) + t.Cleanup(srv.Close) + t.Setenv("PIPELINES_NTFY_URL", srv.URL+"/pipelines") + t.Setenv("PIPELINES_NTFY_TOKEN", "") + t.Setenv("PIPELINES_NTFY_TOKEN_FILE", "") + return func() []ntfyCapture { + mu.Lock() + defer mu.Unlock() + return append([]ntfyCapture(nil), got...) + } +} + +// Rows queued by older servers hold a web URL, the old placeholder deep link or +// an empty click (an invalid web origin). Each delivers with the app link and +// the current web action. +func TestQueuedLegacyRunNotificationsUseAppLink(t *testing.T) { + for _, web := range []string{"https://pipelines.example.com", ""} { + t.Run("web="+web, func(t *testing.T) { + t.Setenv("PIPELINES_WEB_PUBLIC_URL", web) + captured := newNtfyCapture(t) + ctx := context.Background() + s, err := pipeline.Open(filepath.Join(t.TempDir(), "legacy.db")) + if err != nil { + t.Fatal(err) + } + defer s.Close() + clicks := map[int64]string{7: "https://pipelines.example.com/runs/7", 8: "pipelines://run/8", 9: ""} + for id, click := range clicks { + if err := s.EnqueueRunNotification(ctx, pipeline.RunNotification{RunID: id, Sequence: 1, Event: "failed", Channel: "system", Title: "Run failed", Body: "Run failed", Click: click}); err != nil { + t.Fatal(err) + } + } + r := &runner{ctx: ctx, store: s} + r.deliverRunNotifications(time.Now()) + got := captured() + if len(got) != 3 { + t.Fatalf("deliveries = %+v", got) + } + seen := map[string]bool{} + for _, n := range got { + seen[n.Click] = true + want := "" + if web != "" { + want = "view, Open in browser, " + web + "/runs/" + n.Click[len("pipelines://run/"):] + } + if n.Actions != want { + t.Fatalf("actions = %q, want %q", n.Actions, want) + } + } + for _, click := range []string{"pipelines://run/7", "pipelines://run/8", "pipelines://run/9"} { + if !seen[click] { + t.Fatalf("missing %s in %+v", click, got) + } + } + for id := range clicks { + rows, err := s.RunNotifications(ctx, id) + if err != nil || len(rows) != 1 || rows[0].Status != "sent" { + t.Fatalf("run %d rows = %+v %v", id, rows, err) + } + } + }) + } +} + +func chatAttentionHub(t *testing.T, sessions ...string) *chatHub { + t.Helper() + h := newChatHub() + for _, id := range sessions { + h.rooms[id] = newChatRoom(context.Background(), id) + } + return h +} + +func TestChatQuestionNotifiesOnceWithAppLink(t *testing.T) { + t.Setenv("PIPELINES_WEB_PUBLIC_URL", "https://pipelines.example.com") + captured := newNtfyCapture(t) + store := newOperatorStore(t) + if err := store.RecordOperatorSession(context.Background(), "ses_q", t.TempDir(), "Release prep", protocol.ChatSessionTagOperator); err != nil { + t.Fatal(err) + } + h := chatAttentionHub(t, "ses_q") + h.registry = store + form := protocol.ChatForm{ID: "que_1", SessionID: "ses_q", Kind: "question", Title: "Which branch\nshould ship?"} + frame := protocol.ChatEventFrame{SessionID: "ses_q", Kind: protocol.ChatEventForm, Form: &form} + h.emit(frame) + h.emit(frame) // duplicate live event + // A reconnect builds a new room whose readback re-emits the pending form. + h.mu.Lock() + h.rooms["ses_q"] = newChatRoom(context.Background(), "ses_q") + h.mu.Unlock() + h.emit(frame) + h.attentionWG.Wait() + got := captured() + if len(got) != 1 { + t.Fatalf("deliveries = %+v", got) + } + want := ntfyCapture{Title: "Release prep needs your answer", Message: "Which branch should ship?", Click: "pipelines://chat/ses_q", Actions: "view, Open in browser, https://pipelines.example.com/chat/ses_q"} + if got[0] != want { + t.Fatalf("got %+v, want %+v", got[0], want) + } + // Resolution and a later stale copy publish nothing more. + resolved := form + resolved.Resolved = true + h.emit(protocol.ChatEventFrame{SessionID: "ses_q", Kind: protocol.ChatEventForm, Form: &resolved}) + h.attentionWG.Wait() + if n := len(captured()); n != 1 { + t.Fatalf("resolution republished: %d", n) + } +} + +func TestChatResolvedOrReplayedFormsDoNotNotify(t *testing.T) { + captured := newNtfyCapture(t) + h := chatAttentionHub(t, "ses_r") + resolved := protocol.ChatForm{ID: "que_old", SessionID: "ses_r", Kind: "question", Title: "Old?", Resolved: true} + cancelled := protocol.ChatForm{ID: "que_gone", SessionID: "ses_r", Kind: "question", Title: "Gone?", Cancelled: true} + h.emit(protocol.ChatEventFrame{SessionID: "ses_r", Kind: protocol.ChatEventForm, Form: &resolved}) + h.emit(protocol.ChatEventFrame{SessionID: "ses_r", Kind: protocol.ChatEventForm, Form: &cancelled}) + // A stale unresolved copy of an already-resolved form is not announced. + stale := resolved + stale.Resolved = false + h.emit(protocol.ChatEventFrame{SessionID: "ses_r", Kind: protocol.ChatEventForm, Form: &stale}) + // Ordinary reply frames never notify. + h.emit(protocol.ChatEventFrame{SessionID: "ses_r", Kind: protocol.ChatEventText, MessageID: "msg_1", Part: &protocol.ChatPart{ID: "p1"}, Delta: "done"}) + h.emit(protocol.ChatEventFrame{SessionID: "ses_r", Kind: protocol.ChatEventStep, Step: &protocol.ChatStep{Status: protocol.ChatStepEnded}}) + h.attentionWG.Wait() + if got := captured(); len(got) != 0 { + t.Fatalf("unexpected deliveries %+v", got) + } +} + +func TestChatPermissionNotifiesOnce(t *testing.T) { + captured := newNtfyCapture(t) // No web origin: no browser action. + h := chatAttentionHub(t, "ses_p") + frame := protocol.ChatPermissionFrame{SessionID: "ses_p", RequestID: "per_1", Action: "bash", Message: "Run rm -rf build?"} + h.pushPermission("ses_p", frame) + h.pushPermission("ses_p", frame) + // The last subscriber left; a reconnect replays the pending request. + h.mu.Lock() + h.rooms["ses_p"] = newChatRoom(context.Background(), "ses_p") + h.mu.Unlock() + h.pushPermission("ses_p", frame) + resolved := protocol.ChatPermissionFrame{SessionID: "ses_p", RequestID: "per_2", Message: "Already answered", Resolved: true} + h.pushPermission("ses_p", resolved) + h.attentionWG.Wait() + got := captured() + want := ntfyCapture{Title: "Chat needs your approval", Message: "Run rm -rf build?", Click: "pipelines://chat/ses_p"} + if len(got) != 1 || got[0] != want { + t.Fatalf("deliveries = %+v, want one %+v", got, want) + } +} + +func TestChatAttentionNeedsNtfyConfiguration(t *testing.T) { + t.Setenv("PIPELINES_NTFY_URL", "") + calls := 0 + original := chatAttentionPublish + chatAttentionPublish = func(context.Context, string, string, string, string, []byte, string, ...stage.NtfyView) (stage.Values, error) { + calls++ + return nil, nil + } + defer func() { chatAttentionPublish = original }() + h := chatAttentionHub(t, "ses_n") + form := protocol.ChatForm{ID: "que_1", SessionID: "ses_n", Kind: "question", Title: "Ready?"} + h.emit(protocol.ChatEventFrame{SessionID: "ses_n", Kind: protocol.ChatEventForm, Form: &form}) + h.pushPermission("ses_n", protocol.ChatPermissionFrame{SessionID: "ses_n", RequestID: "per_1", Message: "Allow?"}) + h.attentionWG.Wait() + if calls != 0 { + t.Fatalf("published %d without ntfy configuration", calls) + } +} + +// A failing ntfy endpoint never blocks or fails chat handling. +func TestChatAttentionFailureIsOnlyLogged(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + http.Error(w, "down", http.StatusServiceUnavailable) + })) + defer srv.Close() + t.Setenv("PIPELINES_NTFY_URL", srv.URL+"/pipelines") + h := chatAttentionHub(t, "ses_f") + form := protocol.ChatForm{ID: "que_1", SessionID: "ses_f", Kind: "question", Title: "Ready?"} + h.emit(protocol.ChatEventFrame{SessionID: "ses_f", Kind: protocol.ChatEventForm, Form: &form}) + h.attentionWG.Wait() + if forms := h.pendingForms("ses_f"); len(forms) != 1 || forms[0].ID != "que_1" { + t.Fatalf("chat state disturbed: %+v", forms) + } +} diff --git a/internal/server/notify.go b/internal/server/notify.go index 662f3dd6..aaf27f89 100644 --- a/internal/server/notify.go +++ b/internal/server/notify.go @@ -73,7 +73,7 @@ func (r *runner) notifyStep(id int64, name, workspace string, policy *protocol.N return } receipt := &receipts[len(receipts)-1] - result, err := stage.PublishNtfy(ctx, "system", title, summary, filename, data, runAttentionClick(id)) + result, err := stage.PublishNtfy(ctx, "system", title, summary, filename, data, runAttentionClick(id), runAttentionViews(id)...) if err != nil { receipt.Status = "failed" receipt.Diagnostic = err.Error() @@ -294,21 +294,34 @@ func (r *runner) forgetAttention(id int64) { delete(r.attentionSent, id) } -// Prefer the operator's authenticated web origin. Never infer a public address -// from a request Host, the unauthenticated API listener or the ntfy server URL. -// Older Android-only installations retain their deep link until configured. +// runAttentionClick is the notification tap target for a run: always the native +// app deep link, so a tap on the phone opens the Pipelines app. func runAttentionClick(id int64) string { - if raw := os.Getenv("PIPELINES_WEB_PUBLIC_URL"); raw != "" { - base := publicNtfyBase(raw) - if base == "" { - log.Printf("notification web link unavailable: PIPELINES_WEB_PUBLIC_URL must be an HTTP(S) origin without credentials, query or fragment") - return "" - } - return fmt.Sprintf("%s/runs/%d", base, id) - } return fmt.Sprintf("pipelines://run/%d", id) } +// runAttentionViews is the optional "Open in browser" action for a run. +func runAttentionViews(id int64) []stage.NtfyView { + return webAttentionViews(fmt.Sprintf("/runs/%d", id)) +} + +// webAttentionViews returns an "Open in browser" ntfy action for path on the +// operator's authenticated web origin, or nothing when none is configured. +// Never infer a public address from a request Host, the unauthenticated API +// listener or the ntfy server URL. +func webAttentionViews(path string) []stage.NtfyView { + raw := os.Getenv("PIPELINES_WEB_PUBLIC_URL") + if raw == "" { + return nil + } + base := publicNtfyBase(raw) + if base == "" { + log.Printf("notification web link unavailable: PIPELINES_WEB_PUBLIC_URL must be an HTTP(S) origin without credentials, query or fragment") + return nil + } + return []stage.NtfyView{{Label: "Open in browser", URL: base + path}} +} + // notifyRun publishes one run-level attention notification to the operator's // already-configured "system" destination. It is the run counterpart of // notifyStep and reuses the same PublishNtfy machinery, destination and token @@ -386,14 +399,12 @@ func (r *runner) deliverRunNotificationBatch(now time.Time, limit int) { if n == nil { return } - // State transitions enqueue their intent inside the store transaction, - // before notifyRun can supply a server-configured URL. Resolve that - // legacy placeholder here too, including pending intents after restart. - if os.Getenv("PIPELINES_WEB_PUBLIC_URL") != "" && n.Click == fmt.Sprintf("pipelines://run/%d", n.RunID) { - n.Click = runAttentionClick(n.RunID) - } + // Links are derived from the run id at delivery, not from the stored + // click: rows queued by older servers may hold a web URL (or nothing), + // and the web origin is server configuration that can change. + n.Click = runAttentionClick(n.RunID) ctx, cancel := context.WithTimeout(r.ctx, 30*time.Second) - result, publishErr := stage.PublishNtfy(ctx, n.Channel, n.Title, n.Body, "", nil, n.Click) + result, publishErr := stage.PublishNtfy(ctx, n.Channel, n.Title, n.Body, "", nil, n.Click, runAttentionViews(n.RunID)...) cancel() messageID, _ := result["message_id"].(string) save, done := context.WithTimeout(context.Background(), 5*time.Second) diff --git a/internal/server/notify_test.go b/internal/server/notify_test.go index d17c5603..9bfead5a 100644 --- a/internal/server/notify_test.go +++ b/internal/server/notify_test.go @@ -37,8 +37,8 @@ func TestStageNotificationEventsAndArtifactAudit(t *testing.T) { var calls atomic.Int32 srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { count := calls.Add(1) - if click := r.Header.Get("Click"); !strings.HasPrefix(click, "https://pipelines.example.com/runs/") { - t.Errorf("stage notification lacks web run link: %q", click) + if click, actions := r.Header.Get("Click"), r.Header.Get("Actions"); !strings.HasPrefix(click, "pipelines://run/") || actions != "view, Open in browser, https://pipelines.example.com/runs/"+strings.TrimPrefix(click, "pipelines://run/") { + t.Errorf("stage notification lacks app click/web action: %q %q", click, actions) } filename, _ := new(mime.WordDecoder).DecodeHeader(r.Header.Get("Filename")) body, _ := io.ReadAll(r.Body) @@ -300,14 +300,14 @@ func TestRunAttentionNotificationDelivery(t *testing.T) { } defer store.Close() type delivered struct { - method, path, title, message, click, authorization string + method, path, title, message, click, authorization, actions string } deliveries := make(chan delivered, 8) srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { decoder := new(mime.WordDecoder) title, _ := decoder.DecodeHeader(r.Header.Get("Title")) message, _ := decoder.DecodeHeader(r.Header.Get("Message")) - deliveries <- delivered{r.Method, r.URL.Path, title, message, r.Header.Get("Click"), r.Header.Get("Authorization")} + deliveries <- delivered{r.Method, r.URL.Path, title, message, r.Header.Get("Click"), r.Header.Get("Authorization"), r.Header.Get("Actions")} _ = json.NewEncoder(w).Encode(map[string]string{"id": "attention-receipt", "event": "message"}) })) defer srv.Close() @@ -341,7 +341,7 @@ func TestRunAttentionNotificationDelivery(t *testing.T) { if first.title != "Run needs your decision" || !strings.Contains(first.message, "Run #7") || !strings.Contains(first.message, "release") || !strings.Contains(first.message, "decision") || !strings.Contains(first.message, "approve") { t.Fatalf("waiting notification does not identify the run/pipeline/need: %+v", first) } - if first.click != "https://pipelines.example.com/runs/7" { + if first.click != "pipelines://run/7" || first.actions != "view, Open in browser, https://pipelines.example.com/runs/7" { t.Fatalf("waiting notification click does not open the run: %q", first.click) } if first.authorization != "" { @@ -351,7 +351,7 @@ func TestRunAttentionNotificationDelivery(t *testing.T) { if second.title != "Run failed" || !strings.Contains(second.message, "Run #7") || !strings.Contains(second.message, "release") || !strings.Contains(second.message, "deploy") || !strings.Contains(second.message, "provider returned 500") { t.Fatalf("failed notification is not actionable: %+v", second) } - if second.click != "https://pipelines.example.com/runs/7" { + if second.click != "pipelines://run/7" || second.actions != "view, Open in browser, https://pipelines.example.com/runs/7" { t.Fatalf("failed notification click does not open the run: %q", second.click) } select { diff --git a/internal/server/run_notification_outbox_test.go b/internal/server/run_notification_outbox_test.go index 95840e2c..60aacc6d 100644 --- a/internal/server/run_notification_outbox_test.go +++ b/internal/server/run_notification_outbox_test.go @@ -28,8 +28,8 @@ func TestRunNotificationPublisherFailureRetriesAfterReopen(t *testing.T) { } var calls atomic.Int32 server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - if got := r.Header.Get("Click"); got != "https://pipelines.example.com/runs/7" { - t.Errorf("wrong web retry link: %q", got) + if got, actions := r.Header.Get("Click"), r.Header.Get("Actions"); got != "pipelines://run/7" || actions != "view, Open in browser, https://pipelines.example.com/runs/7" { + t.Errorf("wrong retry links: %q %q", got, actions) } if calls.Add(1) == 1 { http.Error(w, "transient", http.StatusServiceUnavailable) @@ -93,9 +93,12 @@ func TestTransactionalSuccessNotificationUsesWebLink(t *testing.T) { var calls atomic.Int32 endpoint := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { calls.Add(1) - if got, want := req.Header.Get("Click"), "https://pipelines.example.com/runs/"+fmt.Sprint(id); got != want { + if got, want := req.Header.Get("Click"), "pipelines://run/"+fmt.Sprint(id); got != want { t.Errorf("click = %q, want %q", got, want) } + if got, want := req.Header.Get("Actions"), "view, Open in browser, https://pipelines.example.com/runs/"+fmt.Sprint(id); got != want { + t.Errorf("actions = %q, want %q", got, want) + } _ = json.NewEncoder(w).Encode(map[string]string{"id": "web-success", "event": "message"}) })) defer endpoint.Close() diff --git a/internal/stage/ntfy.go b/internal/stage/ntfy.go index 3c236d79..cc1ffa25 100644 --- a/internal/stage/ntfy.go +++ b/internal/stage/ntfy.go @@ -92,14 +92,19 @@ func (NtfyStage) Run(ctx context.Context, def Definition, input Values) (Result, // An empty filename publishes an event without an attachment. A non-empty click // is an optional ntfy Click action (an absolute URL) so a tap on the notification // opens the destination the operator should act on; it is validated here and -// never carries credentials. -func PublishNtfy(ctx context.Context, destination, title, summary, filename string, data []byte, click string) (Values, error) { +// never carries credentials. Optional views add ntfy "view" action buttons (for +// example "Open in browser"); each is validated as strictly as the click. +func PublishNtfy(ctx context.Context, destination, title, summary, filename string, data []byte, click string, views ...NtfyView) (Values, error) { if !destinationName.MatchString(destination) || strings.TrimSpace(title) == "" || strings.TrimSpace(summary) == "" || len(title) > 256 || len(summary) > 2048 || !utf8.ValidString(title) || !utf8.ValidString(summary) || strings.ContainsAny(title+summary, "\r\n\x00") { return nil, fmt.Errorf("invalid ntfy notification metadata") } if !validNtfyClick(click) { return nil, fmt.Errorf("invalid ntfy click action") } + actions, err := ntfyViewActions(views) + if err != nil { + return nil, err + } if len(data) > 1<<20 || (filename != "" && (filename != filepath.Base(filename) || filename == "." || strings.ContainsAny(filename, "/\\\r\n\x00") || len(filename) > 200)) { return nil, fmt.Errorf("invalid ntfy attachment") } @@ -154,6 +159,9 @@ func PublishNtfy(ctx context.Context, destination, title, summary, filename stri if click != "" { request.Header.Set("Click", click) } + if actions != "" { + request.Header.Set("Actions", actions) + } if filename != "" { request.Header.Set("Filename", mime.BEncoding.Encode("utf-8", filename)) } @@ -213,3 +221,43 @@ func validNtfyClick(click string) bool { u, err := url.Parse(click) return err == nil && u.Scheme != "" && u.User == nil && u.Fragment == "" } + +// NtfyView is one ntfy "view" action button: a tap opens URL. Label is short +// printable ASCII and URL is an absolute HTTP(S) address without credentials. +type NtfyView struct { + Label string + URL string +} + +// ntfyViewActions renders views in ntfy's simple Actions header format +// ("view,