Files
pipelines/internal/protocol/notifications.go
T
alan d1846441cc Stream ntfy notifications to app clients over /connect
Record every notification published to ntfy (run outbox, stage notify
hooks, chat question/approval/reply) in a persisted app_notifications
outbox and stream it to subscribe_notifications clients with an after
cursor; clear_notifications and ack_attention clear across devices, as do
runs leaving waiting, deleted runs and answered chat questions. Add the
notify.ntfy_enabled setting (default on) to stop only the ntfy publish.
2026-11-01 02:03:58 +00:00

108 lines
4.8 KiB
Go

package protocol
import "fmt"
// App notifications are the same operator notifications the server publishes
// to ntfy, streamed over /connect so the Pipelines app can post them itself
// without the ntfy app. Every publication point records one notification
// (persisted, with a stable id) before it publishes to ntfy, so the stream
// carries exactly the set ntfy gets, governed by the same notification
// settings; notify.ntfy_enabled=false stops only the ntfy publish.
//
// → {"type":"subscribe_notifications","id":"1","after":"run:7:3:waiting"}
// ← {"type":"notifications_subscribed","id":"1","notifications":[{...}],"ids":["chat:ses_x:form:f1"]}
// ← {"type":"notification","notification":{...}} (push)
// ← {"type":"notifications_cleared","ids":["run:7:3:waiting"]} (push)
// → {"type":"clear_notifications","id":"2","ids":["run:7:3:waiting"]}
// ← {"type":"notifications_cleared","id":"2","ids":[...]} (reply: the ids it cleared)
//
// subscribe_notifications replies with every still-active notification newer
// than the optional "after" cursor (a notification id the client already
// holds), oldest first, bounded to the newest MaxReplayedNotifications within
// the store's retention window (7 days); an unknown or pruned cursor replays the whole bounded
// set. The reply's "ids" lists notifications cleared within the retention
// window (bounded) so a reconnecting client can dismiss ones it still shows.
// After the reply the connection receives "notification" and
// "notifications_cleared" pushes in order. Subscribing again replaces the
// subscription.
//
// clear_notifications is the app's dismiss/tap: it clears the named ids, has
// the same effect as the matching ack_attention (a run_waiting id dismisses
// "<run>:Decision", run_failed/stage_failed "<run>:Failed", a chat id marks
// the chat seen) and pushes notifications_cleared to every other subscriber.
// An ack_attention from any client, a run leaving "waiting", a deleted run and
// an answered chat question/approval also clear and push.
const (
SubscribeNotifications = "subscribe_notifications"
NotificationsSubscribed = "notifications_subscribed"
NotificationPush = "notification"
NotificationsCleared = "notifications_cleared"
ClearNotifications = "clear_notifications"
)
// App notification kinds.
const (
NotificationRunWaiting = "run_waiting" // a run needs a human decision
NotificationRunFailed = "run_failed" // a run (or its final stage) failed
NotificationRunSucceeded = "run_succeeded" // a run succeeded
NotificationStageFailed = "stage_failed" // a stage notify hook reported a failure mid-run
NotificationStageSucceeded = "stage_succeeded" // a stage notify hook reported a success mid-run
NotificationChatQuestion = "chat_question" // a chat asked a question
NotificationChatApproval = "chat_approval" // a chat asks for permission/approval
NotificationChatReply = "chat_reply" // a chat finished its reply
)
// DefaultNotificationPriority is ntfy's default priority, which every ntfy
// publication uses today (the server sends no Priority header).
const DefaultNotificationPriority = 3
// MaxReplayedNotifications bounds a subscribe reply and MaxClearNotificationIDs
// one clear_notifications request.
const (
MaxReplayedNotifications = 100
MaxClearNotificationIDs = 500
maxNotificationIDLength = 512
)
// AppNotification is one operator notification as streamed to app clients.
type AppNotification struct {
// ID is stable and is the id used to clear it: "run:<run>:<step>:<event>"
// or "chat:<session>:<form|permission|reply>:<id>".
ID string `json:"id"`
Kind string `json:"kind"`
Title string `json:"title"`
Message string `json:"message"`
// Click is the same deep link ntfy gets (pipelines://run/<id>,
// pipelines://chat/<id>).
Click string `json:"click"`
Priority int `json:"priority"`
Tags []string `json:"tags"`
// CreatedAt is RFC3339 (UTC).
CreatedAt string `json:"created_at"`
// Group is "run:<id>" or "chat:<id>" for Android notification grouping.
Group string `json:"group"`
}
// ValidateClearNotifications checks a clear_notifications id list.
func ValidateClearNotifications(ids []string) ([]string, error) {
if len(ids) == 0 {
return nil, fmt.Errorf("clear_notifications must name at least one id")
}
if len(ids) > MaxClearNotificationIDs {
return nil, fmt.Errorf("clear_notifications may carry at most %d ids", MaxClearNotificationIDs)
}
seen := make(map[string]struct{}, len(ids))
result := make([]string, 0, len(ids))
for _, id := range ids {
if id == "" || len(id) > maxNotificationIDLength {
return nil, fmt.Errorf("invalid notification id %q", id)
}
if _, dup := seen[id]; dup {
continue
}
seen[id] = struct{}{}
result = append(result, id)
}
return result, nil
}