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 // ":Decision", run_failed/stage_failed ":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:::" // or "chat:::". 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/, // pipelines://chat/). Click string `json:"click"` Priority int `json:"priority"` Tags []string `json:"tags"` // CreatedAt is RFC3339 (UTC). CreatedAt string `json:"created_at"` // Group is "run:" or "chat:" 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 }