notify

package
v0.99.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 17, 2026 License: GPL-3.0 Imports: 17 Imported by: 0

Documentation

Overview

Package notify provides the notification dispatcher interface and registry.

Index

Constants

View Source 
const (
	// AgentNotifyTemplateID is the seeded template for chatagent send_notification.
	AgentNotifyTemplateID = "agent.notify"
	// AgentNotifyTemplateBody is the default body for AgentNotifyTemplateID.
	AgentNotifyTemplateBody = "{{ .summary }}"
	// AgentApprovalTemplateID is the seeded template for tool-approval inbox alerts.
	AgentApprovalTemplateID = "agent.approval"
	// AgentApprovalTemplateBody is the default body for AgentApprovalTemplateID.
	AgentApprovalTemplateBody = "{{ .summary }}"
	// LifeQuestCompletedTemplateID is the seeded template for life quest completion inbox alerts.
	LifeQuestCompletedTemplateID = "life.quest.completed"
	// LifeQuestCompletedTemplateBody is the default body for LifeQuestCompletedTemplateID.
	LifeQuestCompletedTemplateBody = "{{ .summary }}"
	// LifeQuestFailedTemplateID is the seeded template for life quest failure inbox alerts.
	LifeQuestFailedTemplateID = "life.quest.failed"
	// LifeQuestFailedTemplateBody is the default body for LifeQuestFailedTemplateID.
	LifeQuestFailedTemplateBody = "{{ .summary }}"
	// InappChannelURI is the seeded URI for the system inapp channel.
	InappChannelURI = "inapp://inbox"
)
View Source 
const (
	// ChannelInapp is the seeded in-app inbox channel name.
	ChannelInapp = "inapp"
	// PayloadKeyURL is an optional deep-link URL in the gateway payload.
	PayloadKeyURL = "url"
	// PayloadKeyTitle is an optional title override in the gateway payload.
	PayloadKeyTitle = "title"
	// PayloadKeyCorrelationID links inapp and deferred external records.
	PayloadKeyCorrelationID = "correlation_id"
	// PayloadKeyEscalateAfter overrides escalate delay (Go duration string, e.g. "5m").
	PayloadKeyEscalateAfter = "escalate_after"
)
View Source 
const (
	RuleActionThrottle  = manifest.RuleActionThrottle
	RuleActionAggregate = manifest.RuleActionAggregate
	RuleActionMute      = manifest.RuleActionMute
	RuleActionDrop      = manifest.RuleActionDrop
)

Rule action constants.

View Source 
const ConnectivityTestTemplateID = "test"

ConnectivityTestTemplateID is the template ID written by web UI channel connectivity tests. Retry for these records re-runs the channel probe instead of GatewaySend.

View Source 
const (
	// PayloadKeySummary is the key in the GatewaySend payload map for the summary text.
	PayloadKeySummary = "summary"
)
View Source 
const PlaygroundTemplateID = "playground"

PlaygroundTemplateID is the template ID written by the Notifications playground when sending with a custom (ad-hoc) template body.

Variables

View Source 
var (
	// ErrNoDefaultChannel reports that no enabled default notify channel is configured.
	ErrNoDefaultChannel = errors.New("no default notify channel configured")
	// ErrNoDefaultTemplate reports that no default notify template is configured.
	ErrNoDefaultTemplate = errors.New("no default notify template configured")
)

Functions

func ClearPresenceForTest added in v0.99.0 

func ClearPresenceForTest()

ClearPresenceForTest removes all presence entries (tests only).

func DefaultInboxChannels added in v0.99.0 

func DefaultInboxChannels(ctx context.Context) []string

DefaultInboxChannels returns [inapp] plus the global default external channel when configured.

func EscalateAfter added in v0.99.0 

func EscalateAfter() time.Duration

EscalateAfter returns the default unread escalate delay.

func FlushDueDeferred added in v0.99.0 

func FlushDueDeferred(ctx context.Context)

FlushDueDeferred processes deferred records that are due for external dispatch.

func GatewaySend added in v0.92.0 

func GatewaySend(ctx context.Context, uid types.Uid, templateID string, channels []string, payload map[string]any) error

GatewaySend is the central notification gateway entry point. It renders a notification template and dispatches the message to the specified channels. Channels are resolved from the global NotifyChannel registry first; when a UID is set, per-user notify:<channel> config is used as a fallback. Rules (throttle, mute, aggregate) are applied before sending (when rule engine is initialized). When channels include a successful inapp delivery, other channels are deferred and flushed by the escalation worker (presence / unread timeout), re-evaluating rules at flush time.

func GatewaySendDefaultChannel added in v0.98.0 

func GatewaySendDefaultChannel(ctx context.Context, uid types.Uid, templateID string, payload map[string]any) error

GatewaySendDefaultChannel sends using an explicit template and the global default channel.

func GatewaySendDefaults added in v0.98.0 

func GatewaySendDefaults(ctx context.Context, uid types.Uid, payload map[string]any) error

GatewaySendDefaults sends using the global default template and default channel.

func IsConnectivityTestTemplate added in v0.96.1 

func IsConnectivityTestTemplate(templateID string) bool

IsConnectivityTestTemplate reports whether templateID identifies a connectivity-test record.

func IsPlaygroundTemplate added in v0.96.2 

func IsPlaygroundTemplate(templateID string) bool

IsPlaygroundTemplate reports whether templateID identifies a playground custom-send record.

func IsPresent added in v0.99.0 

func IsPresent(uid string) bool

IsPresent reports whether uid has been active within the presence window.

func IsSystemNotifyChannel added in v0.99.0 

func IsSystemNotifyChannel(name string) bool

IsSystemNotifyChannel reports whether name is a protected system channel.

func List 

func List() map[string]Notifyer

List returns a copy of the registered Notifyer map.

func ParseSchema 

func ParseSchema(testString string) (string, error)

func ParseTemplate 

func ParseTemplate(testString string, templates []string) (types.KV, error)

func PresenceWindow added in v0.99.0 

func PresenceWindow() time.Duration

PresenceWindow returns the configured presence activity window.

func Register 

func Register(id string, notifyer Notifyer)

Register adds a Notifyer to the global registry.

func ResolveDefaultChannelName added in v0.98.0 

func ResolveDefaultChannelName(ctx context.Context) (string, error)

ResolveDefaultChannelName returns the name of the global default enabled channel.

func ResolveDefaultTemplateID added in v0.98.0 

func ResolveDefaultTemplateID(ctx context.Context) (string, error)

ResolveDefaultTemplateID returns the template_id of the global default template.

func SeedAgentApprovalTemplate added in v0.99.0 

func SeedAgentApprovalTemplate(ctx context.Context) error

SeedAgentApprovalTemplate ensures the agent.approval template exists.

func SeedAgentNotifyTemplate added in v0.98.0 

func SeedAgentNotifyTemplate(ctx context.Context) error

SeedAgentNotifyTemplate ensures the agent.notify template exists (not marked default).

func SeedInappChannel added in v0.99.0 

func SeedInappChannel(ctx context.Context) error

SeedInappChannel ensures the system inapp channel exists (not marked default).

func SeedLifeQuestCompletedTemplate added in v0.99.0 

func SeedLifeQuestCompletedTemplate(ctx context.Context) error

SeedLifeQuestCompletedTemplate ensures the life.quest.completed template exists.

func SeedLifeQuestFailedTemplate added in v0.99.0 

func SeedLifeQuestFailedTemplate(ctx context.Context) error

SeedLifeQuestFailedTemplate ensures the life.quest.failed template exists.

func Send 

func Send(text string, message Message) error

func SendToProtocol added in v0.96.0 

func SendToProtocol(protocol, uri string, message Message) error

SendToProtocol dispatches a message using an explicit notify protocol. Unlike Send, the URI scheme (for example http/https used by ntfy endpoints) is not used for provider lookup — protocol selects the Notifyer.

func SetEscalateAfterForTest added in v0.99.0 

func SetEscalateAfterForTest(d time.Duration)

SetEscalateAfterForTest overrides the default unread escalate delay (tests only).

func SetNotifyConfigStore added in v0.99.0 

func SetNotifyConfigStore(s NotifyConfigStore)

SetNotifyConfigStore wires the global notify channel/template store.

func SetNotifyRecords added in v0.99.0 

func SetNotifyRecords(s NotifyRecords)

SetNotifyRecords wires the persistence backend for notification delivery records.

func SetNotifyUserConfig added in v0.99.0 

func SetNotifyUserConfig(s NotifyUserConfig)

SetNotifyUserConfig wires the per-user notify config backend.

func SetPresenceWindowForTest added in v0.99.0 

func SetPresenceWindowForTest(d time.Duration)

SetPresenceWindowForTest overrides the presence activity window (tests only).

func StartEscalationWorker added in v0.99.0 

func StartEscalationWorker()

StartEscalationWorker starts a background ticker that flushes due deferred notifications.

func StopEscalationWorker added in v0.99.0 

func StopEscalationWorker()

StopEscalationWorker stops the escalation worker.

func StopEscalationWorkerForTest added in v0.99.0 

func StopEscalationWorkerForTest()

StopEscalationWorkerForTest stops the escalation worker (tests only).

func TemplateReferencesSummary added in v0.98.0 

func TemplateReferencesSummary(defaultTemplate, overridesJSON string) bool

TemplateReferencesSummary reports whether a template body (and overrides JSON) references the summary payload field used by GatewaySendDefaults.

func TouchPresence added in v0.99.0 

func TouchPresence(uid string)

TouchPresence records that uid was active on the web UI now.

func Unregister added in v0.96.0 

func Unregister(id string)

Unregister removes a previously registered Notifyer. It is a no-op if the id is not found. Intended primarily for test teardown.

func UserNotifyChannels added in v0.96.0 

func UserNotifyChannels(ctx context.Context, uid types.Uid) ([]string, error)

UserNotifyChannels returns channel names configured for the user under notify:<channel> keys.

func WaitForRecordAsyncForTest added in v0.96.0 

func WaitForRecordAsyncForTest()

WaitForRecordAsyncForTest blocks until all in-flight recordAsync goroutines finish.

func WarnSkipNoDefault added in v0.98.0 

func WarnSkipNoDefault(err error, what string) bool

WarnSkipNoDefault logs and skips when err is a missing-default sentinel. Returns true when the caller should treat the send as a soft skip.

Types

type ListNotifyRecordsOptions added in v0.99.0 

type ListNotifyRecordsOptions struct {
	Limit      int    // max 100, default 20
	Cursor     string // opaque cursor: ID value as string
	Channel    string // exact channel name filter; empty means any
	RuleID     string // exact rule_id filter; empty means any
	Status     string // exact status filter; empty means any
	UnreadOnly bool   // when true, only rows with nil read_at
}

ListNotifyRecordsOptions holds filters and pagination for listing notification records.

type Message 

type Message struct {
	Title    string
	Body     string
	Url      string
	Priority Priority
}

type NotifyConfigStore added in v0.99.0 

type NotifyConfigStore interface {
	GetDefaultNotifyChannelRaw(ctx context.Context) (model.NotifyChannel, error)
	GetNotifyChannelByNameRaw(ctx context.Context, name string) (model.NotifyChannel, error)
	CreateNotifyChannel(ctx context.Context, name, protocol, uri string) (int64, error)
	GetDefaultNotifyTemplate(ctx context.Context) (model.NotifyTemplate, error)
	GetNotifyTemplateByTemplateID(ctx context.Context, templateID string) (model.NotifyTemplate, error)
	CreateNotifyTemplate(ctx context.Context, tmpl model.NotifyTemplate) (int64, error)
}

NotifyConfigStore persists global notify channels and templates used by the gateway.

func GetNotifyConfigStore added in v0.99.0 

func GetNotifyConfigStore() NotifyConfigStore

GetNotifyConfigStore returns the injected notify config store, or nil when unset.

type NotifyRecords added in v0.99.0 

type NotifyRecords interface {
	Record(ctx context.Context, uid, channel, templateID, summary, status, errorMsg, ruleID string, payload map[string]any) (int64, error)
	RecordParams(ctx context.Context, p RecordParams) (int64, error)
	ListRecords(ctx context.Context, uid string, opts ListNotifyRecordsOptions) ([]model.NotificationRecord, string, error)
	CountUnread(ctx context.Context, uid, channel, status string) (int, error)
	MarkRead(ctx context.Context, uid string, ids ...int64) error
	MarkReadByCorrelation(ctx context.Context, uid, correlationID string) error
	ListDueDeferred(ctx context.Context, now time.Time, limit int) ([]model.NotificationRecord, error)
	UpdateRecordStatus(ctx context.Context, id int64, status, errorMsg string) error
	HasUnreadSuccessByCorrelation(ctx context.Context, uid, correlationID string) (bool, error)
	GetRecord(ctx context.Context, id int64) (*model.NotificationRecord, error)
	DeleteOldest(ctx context.Context, uid string, keepN int) error
}

NotifyRecords persists notification delivery history without exposing ORM types.

func GetNotifyStore added in v0.92.0 

func GetNotifyStore() NotifyRecords

GetNotifyStore returns the injected NotifyRecords backend, or nil when unset.

type NotifyUserConfig added in v0.99.0 

type NotifyUserConfig interface {
	ListConfigByPrefix(ctx context.Context, uid types.Uid, topic, prefix string) ([]model.ConfigItem, error)
	ConfigGet(ctx context.Context, uid types.Uid, topic, key string) (types.KV, error)
}

NotifyUserConfig reads per-user notify:<channel> configuration.

func GetNotifyUserConfig added in v0.99.0 

func GetNotifyUserConfig() NotifyUserConfig

GetNotifyUserConfig returns the injected user notify config store, or nil when unset.

type Notifyer 

type Notifyer interface {
	// Protocol Define protocol
	Protocol() string
	// Templates Define object templates
	Templates() []string
	// Send notify
	Send(tokens types.KV, message Message) error
}

type Override added in v0.97.0 

type Override = manifest.Override

Override is a channel-specific template override.

type Priority 

type Priority int32
const (
	Low Priority = iota + 1
	Moderate
	Normal
	High
	Emergency
)

type RecordParams added in v0.99.0 

type RecordParams struct {
	UID           string
	Channel       string
	TemplateID    string
	Summary       string
	Status        string
	ErrorMsg      string
	RuleID        string
	CorrelationID string
	Payload       map[string]any
	EscalateAt    *time.Time
}

RecordParams holds fields for inserting a notification delivery record.

type Rule added in v0.97.0 

type Rule = manifest.Rule

Rule is a notification filtering or aggregation rule.

type RuleAction added in v0.97.0 

type RuleAction = manifest.RuleAction

RuleAction is the action to take when a rule matches.

type RuleMatch added in v0.97.0 

type RuleMatch = manifest.RuleMatch

RuleMatch is the event and channel matching criteria.

type RuleParams added in v0.97.0 

type RuleParams = manifest.RuleParams

RuleParams holds action-specific parameters.

type Template added in v0.97.0 

type Template = manifest.Template

Template is a notification message template with optional per-channel overrides.

Source Files

View all Source files

Directories

Path Synopsis
Package inapp implements the in-app inbox notification provider.
 Package inapp implements the in-app inbox notification provider.
Package manifest holds shared notification template and rule type definitions.
 Package manifest holds shared notification template and rule type definitions.
Package messagepusher implements the Message Pusher notification provider.
 Package messagepusher implements the Message Pusher notification provider.
Package ntfy implements the ntfy notification provider.
 Package ntfy implements the ntfy notification provider.
Package pushover implements Pushover notification provider.
 Package pushover implements Pushover notification provider.
Package rules provides the notification rule engine for throttling, aggregation, and mute/DND.
 Package rules provides the notification rule engine for throttling, aggregation, and mute/DND.
Package slack implements the Slack notification provider.
 Package slack implements the Slack notification provider.
Package template provides notification template rendering using Go text/template with Sprig function library support.
 Package template provides notification template rendering using Go text/template with Sprig function library support.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.