Files
pipelines/internal/protocol/notifications.go
T

120 lines
5.3 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 app tap target (normally the same run deep link ntfy gets).
Click string `json:"click"`
RunClick string `json:"run_click,omitempty"`
Artifact *NotificationArtifact `json:"artifact,omitempty"`
Preview string `json:"preview,omitempty"`
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"`
}
// NotificationArtifact is the run artifact opened by an app notification.
type NotificationArtifact struct {
RunID int64 `json:"run_id"`
Sequence int `json:"sequence"`
Path string `json:"path"`
Name string `json:"name"`
URL string `json:"url"`
MediaType string `json:"media_type"`
}
// 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
}