Documentation
¶
Overview ¶
Package notify provides durable, rule-filtered owner notifications. Channel secrets never appear in API responses, delivery logs, or transport errors.
Index ¶
- Constants
- Variables
- func BridgeEventTypes() []string
- func CanonicalToLegacyKind(canonical string) (string, bool)
- func ChannelKindDescriptors() []extend.Descriptor
- func EventKindDescriptors() []extend.Descriptor
- func LegacyToCanonicalTypes(legacyKind string) []string
- func PublishMQTT(ctx context.Context, cfg MQTTConfig, msg MQTTMessage) error
- func RunMonitor(input io.Reader) error
- func ValidateMQTTBroker(endpoint string) error
- func ValidateMQTTTopic(topic string) error
- type BridgeOptions
- type BridgeStats
- type BusBridge
- type Channel
- type ChannelKind
- type DeliverOptions
- type DeliverResult
- type DetectedEpisode
- type EmbedField
- type Event
- type FavoriteEpisodeDetector
- type Heartbeat
- type KindRegistry
- type MQTTConfig
- type MQTTMessage
- type Options
- type PushKeys
- type PushSubscription
- type Service
- func (s *Service) BackupFailed(ctx context.Context, err error) error
- func (s *Service) Channels(ctx context.Context) ([]Channel, error)
- func (s *Service) DeliverToChannels(ctx context.Context, channelIDs []string, e Event, opts DeliverOptions) ([]DeliverResult, error)
- func (s *Service) Drain(ctx context.Context) error
- func (s *Service) Emit(ctx context.Context, e Event) error
- func (s *Service) EmitOnce(ctx context.Context, key string, e Event) (bool, error)
- func (s *Service) ForgetTitleAvailableOnce(ctx context.Context, keys []string) (int64, error)
- func (s *Service) HTTPClient() *http.Client
- func (s *Service) Handler() http.Handler
- func (s *Service) Heartbeat(ctx context.Context) error
- func (s *Service) HeartbeatSettings(ctx context.Context, redact bool) (Heartbeat, error)
- func (s *Service) Kinds() *KindRegistry
- func (s *Service) MigrateSecrets(ctx context.Context) (int, error)
- func (s *Service) ObserveIndexer(e newznab.Event)
- func (s *Service) ObservePlayback(ev playback.Event)
- func (s *Service) Prune(ctx context.Context) (int64, error)
- func (s *Service) PublishMQTT(ctx context.Context, brokerID, topic string, payload []byte, qos byte, ...) error
- func (s *Service) RegisterChannelKind(k ChannelKind) error
- func (s *Service) Run(ctx context.Context)
- func (s *Service) SampleHealth(ctx context.Context) error
- func (s *Service) Save(ctx context.Context, c Channel) error
- func (s *Service) SaveHeartbeat(ctx context.Context, h Heartbeat) error
- func (s *Service) Subscribe(fn func(Event)) func()
- func (s *Service) TitleAvailable(ctx context.Context, title string) error
- func (s *Service) TitleAvailableOnce(ctx context.Context, key, title string) error
- func (s *Service) UpdateAvailable(ctx context.Context, current, version string) error
- func (s *Service) UpdateInstalled(ctx context.Context, from, to string) error
- func (s *Service) UpdateRolledBack(ctx context.Context, version, restored, reason string) error
- func (s *Service) WatchProcess(executable string) (func(bool) error, error)
- type ViewerAlerts
- type ViewerPush
- func (p *ViewerPush) Drain(ctx context.Context) error
- func (p *ViewerPush) PublicKey(ctx context.Context, viewer *core.User) (string, error)
- func (p *ViewerPush) PurgeViewer(ctx context.Context, viewerID int64) error
- func (p *ViewerPush) Register(ctx context.Context, viewer *core.User, subscription PushSubscription, ...) error
- func (p *ViewerPush) Registered(ctx context.Context, viewer *core.User, endpoint string) (bool, error)
- func (p *ViewerPush) Unregister(ctx context.Context, viewer *core.User, endpoint string) error
Constants ¶
const Redacted = "[configured]"
Variables ¶
var Kinds = eventKindIDs()
Kinds lists every event kind Ether accepts. Definitions live in events.go.
Functions ¶
func BridgeEventTypes ¶
func BridgeEventTypes() []string
BridgeEventTypes returns the sorted list of canonical event types observed by the events.Bus -> notify bridge.
func CanonicalToLegacyKind ¶
CanonicalToLegacyKind returns the legacy notify.Event kind for a canonical events.Bus event type, if one exists.
func ChannelKindDescriptors ¶ added in v0.3.3
func ChannelKindDescriptors() []extend.Descriptor
ChannelKindDescriptors returns the built-in channelKind descriptors for the extend registry.
func EventKindDescriptors ¶ added in v0.3.3
func EventKindDescriptors() []extend.Descriptor
EventKindDescriptors returns the built-in eventKind descriptors for the extend registry.
func LegacyToCanonicalTypes ¶
LegacyToCanonicalTypes returns all canonical event types that map to a legacy notify.Event kind (sorted deterministically).
func PublishMQTT ¶
func PublishMQTT(ctx context.Context, cfg MQTTConfig, msg MQTTMessage) error
PublishMQTT opens a bounded MQTT 3.1.1 connection, publishes msg with the requested QoS (0, 1, or 2) and retain flag, and disconnects cleanly. Returned errors never include broker addresses, usernames, or passwords.
func RunMonitor ¶ added in v0.2.4
RunMonitor is used only by the executable's notification-monitor entry point. A killed host, network outage, or supervisor killing the whole process group also stops this watcher. An external uptime monitor is required for those.
func ValidateMQTTBroker ¶
ValidateMQTTBroker checks that an endpoint is a valid host:port with no control characters.
func ValidateMQTTTopic ¶
ValidateMQTTTopic ensures a publish topic is non-empty, bounded, and contains no MQTT wildcard or control characters.
Types ¶
type BridgeOptions ¶
type BridgeOptions struct {
// Name overrides the subscription name (defaults to "notify-bridge").
Name string
// BufferSize overrides the subscriber queue depth (defaults to bus default).
BufferSize int
// EmitTimeout bounds each svc.Emit call (defaults to 5s).
EmitTimeout time.Duration
// SkipLegacyKinds skips bridging specific legacy kinds (e.g. if an older
// emitter still calls notify.Service directly during staged rollout).
SkipLegacyKinds map[string]bool
// Logger logs bridge errors; defaults to service logger or slog.Default.
Logger *slog.Logger
}
BridgeOptions configures an events.Bus -> notify.Service bridge.
type BridgeStats ¶
BridgeStats summarizes bridge activity for tests and observability.
type BusBridge ¶
type BusBridge struct {
// contains filtered or unexported fields
}
BusBridge subscribes asynchronously to an events.Bus and forwards canonical events to legacy notify.Service channel rules without blocking publishers.
func StartBusBridge ¶
func StartBusBridge(ctx context.Context, svc *Service, bus *events.Bus, opts BridgeOptions) (*BusBridge, error)
StartBusBridge wires bus -> svc asynchronously. Every channel that still has matching legacy channel.Events receives the notification identically; channels with no matching legacy rules are ignored without side effects.
func (*BusBridge) Stats ¶
func (b *BusBridge) Stats() BridgeStats
Stats returns the current bridge counters.
type Channel ¶
type Channel struct {
ID string `json:"id"`
Name string `json:"name"`
Kind string `json:"kind"`
Enabled bool `json:"enabled"`
Events []string `json:"events"`
Settings map[string]string `json:"settings,omitempty"`
Secrets map[string]string `json:"secrets,omitempty"`
PerMinute int `json:"perMinute"`
DigestMinutes int `json:"digestMinutes"`
}
Channel is one notification destination. Kind-specific values live in Settings (plain) and Secrets (sealed at rest, redacted by the owner API), keyed by the field names of the kind's schema (kinds.go).
func (*Channel) SetSubscription ¶ added in v0.3.3
func (c *Channel) SetSubscription(p *PushSubscription)
SetSubscription stores p as the channel's subscription secret.
func (Channel) Subscription ¶ added in v0.2.4
func (c Channel) Subscription() (*PushSubscription, error)
Subscription decodes the browser push subscription held in Secrets.
type ChannelKind ¶ added in v0.3.3
type ChannelKind struct {
ID string
Owner string // extend.Builtin or a plugin id
Label extend.Text
Hint extend.Text
Icon string
Order int
Fields []extend.SettingsField
SendTest bool
Selectable bool
Formats []string
MaxLength int
Validate func(c Channel) error
Deliver func(ctx context.Context, s *Service, c Channel, e Event) error
}
ChannelKind is one way notifications can be delivered: a settings schema the console renders, validation, and delivery. Built-ins and (through Service.RegisterChannelKind) plugin kinds use the same shape; each kind becomes a channelKind descriptor in the extend registry.
func BuiltinChannelKinds ¶ added in v0.3.3
func BuiltinChannelKinds() []ChannelKind
BuiltinChannelKinds returns Ether's own channel kinds, ordered as in the console picker.
func (ChannelKind) Descriptor ¶ added in v0.3.3
func (k ChannelKind) Descriptor() extend.Descriptor
Descriptor returns the kind as a channelKind descriptor.
type DeliverOptions ¶
type DeliverOptions struct {
// BypassDigest delivers immediately even when a channel has DigestMinutes > 0.
BypassDigest bool
// QueueOnly always enqueues rows into notify_queue without performing
// synchronous network I/O on the caller's goroutine.
QueueOnly bool
}
DeliverOptions controls explicit channel delivery via DeliverToChannels.
type DeliverResult ¶
type DeliverResult struct {
ChannelID string `json:"channelId"`
Status string `json:"status"` // "sent" | "queued" | "skipped" | "failed"
Error string `json:"error,omitempty"`
}
DeliverResult reports the per-channel outcome of DeliverToChannels.
type DetectedEpisode ¶
type DetectedEpisode struct {
ShowKey core.RatingKey
ShowTitle string
EpisodeKey core.RatingKey
EpisodeTitle string
Season int
Episode int
AirDate string
FollowerCount int
}
DetectedEpisode describes a newly aired episode detected for one or more viewers following a favourited show.
type EmbedField ¶
type EmbedField struct {
Name string `json:"name"`
Value string `json:"value"`
Inline bool `json:"inline,omitempty"`
}
EmbedField is one key/value field rendered inside rich notification embeds (such as Discord embeds and Slack attachments).
type Event ¶
type Event struct {
HTML string `json:"html,omitempty"`
Kind string `json:"kind"`
Title string `json:"title"`
Message string `json:"message"`
At time.Time `json:"at"`
PosterURL string `json:"posterUrl,omitempty"`
Color string `json:"color,omitempty"`
Fields []EmbedField `json:"fields,omitempty"`
Priority int `json:"priority,omitempty"`
LinkURL string `json:"linkUrl,omitempty"`
}
func MapEnvelopeToLegacyEvent ¶
MapEnvelopeToLegacyEvent converts a canonical events.Envelope into the corresponding legacy notify.Event, returning ok=false when the event type has no legacy notification counterpart or lacks required fields (e.g. newsletter HTML).
type FavoriteEpisodeDetector ¶ added in v0.3.0
type FavoriteEpisodeDetector struct {
Preferences *ViewerAlerts
// Episodes must return only visible, currently favorited shows and episodes.
Episodes func(context.Context, *core.User) ([]core.Title, error)
Now func() time.Time
OnDetected func([]DetectedEpisode)
}
FavoriteEpisodeDetector scans only currently authorized favorites. The caller runs it under the cluster leader lease. The database uniqueness constraint also protects against overlap during a leader handoff.
type KindRegistry ¶ added in v0.3.3
type KindRegistry struct {
// contains filtered or unexported fields
}
KindRegistry holds the channel kinds a service can validate and deliver. It is safe for concurrent use; the plugin host registers plugin kinds here as plugins are installed.
func NewKindRegistry ¶ added in v0.3.3
func NewKindRegistry(kinds ...ChannelKind) *KindRegistry
NewKindRegistry returns a registry holding kinds.
func (*KindRegistry) Get ¶ added in v0.3.3
func (r *KindRegistry) Get(id string) (ChannelKind, bool)
Get returns one kind.
func (*KindRegistry) List ¶ added in v0.3.3
func (r *KindRegistry) List() []ChannelKind
List returns every kind, ordered for pickers.
func (*KindRegistry) Register ¶ added in v0.3.3
func (r *KindRegistry) Register(k ChannelKind) error
Register adds a kind. IDs must be unique; plugin kinds are namespaced by their descriptor but share this delivery table by full descriptor id.
func (*KindRegistry) RemovePlugin ¶ added in v0.3.3
func (r *KindRegistry) RemovePlugin(id, owner string)
RemovePlugin removes a plugin's channel kind without affecting built-ins.
type MQTTConfig ¶
type MQTTConfig struct {
Endpoint string // host:port
TLS bool
TLSConfig *tls.Config // optional override (e.g. test CA)
Username string
Password string
ClientID string
}
MQTTConfig describes an MQTT 3.1.1 broker connection.
type MQTTMessage ¶
MQTTMessage is a single MQTT PUBLISH packet.
type Options ¶
type Options struct {
// NodeID names this node on the queue rows it claims; a random id is
// used when empty.
NodeID string
Providers func() []usenet.ProviderStats
CacheUsage func() (int64, int64)
Client *http.Client
Now func() time.Time
Logger *slog.Logger
// Sealer protects stored channel secrets and the push identity
// (secrets.go); nil stores them as given.
Sealer config.FieldSealer
// Kinds is the channel-kind registry; nil uses the built-ins.
Kinds *KindRegistry
}
type PushSubscription ¶ added in v0.2.4
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
func (*Service) BackupFailed ¶ added in v0.2.48
BackupFailed reports a scheduled backup that did not complete.
func (*Service) DeliverToChannels ¶
func (s *Service) DeliverToChannels(ctx context.Context, channelIDs []string, e Event, opts DeliverOptions) ([]DeliverResult, error)
DeliverToChannels sends e directly to the specified notification channel IDs (or all enabled channels when channelIDs is empty or contains "*"), reusing channel secret sealing, per-channel rate limits, digest batching, delivery history, and plugin notification channel kinds.
func (*Service) EmitOnce ¶ added in v0.2.48
EmitOnce emits e unless an event was already emitted under key, and reports whether it emitted. The key and the queued deliveries commit in one transaction: a crash or a failed enqueue leaves neither, so a later attempt emits it.
func (*Service) ForgetTitleAvailableOnce ¶
ForgetTitleAvailableOnce drops the records of TitleAvailableOnce keys whose caller knows the event can never be emitted again (watchlist episode alerts it has pruned), and reports the rows removed.
func (*Service) HTTPClient ¶ added in v0.3.3
HTTPClient is the client channel kinds deliver with.
func (*Service) Heartbeat ¶ added in v0.2.4
Heartbeat is called only after a successful local HTTP probe. The remote monitor must alert when these one-minute pings stop (allow a three-minute grace).
func (*Service) HeartbeatSettings ¶ added in v0.2.4
func (*Service) Kinds ¶ added in v0.3.3
func (s *Service) Kinds() *KindRegistry
Kinds returns the service's channel-kind registry.
func (*Service) MigrateSecrets ¶ added in v0.2.4
MigrateSecrets seals channel secrets stored in plaintext, rewrites flat pre-registry channel rows in the new {settings, secrets} shape, and seals the push identity. It returns how many rows it rewrote. A row is replaced only if it is unchanged since read, so it is safe to rerun on any node; a row that does not open is left untouched and reported in the error.
func (*Service) ObserveIndexer ¶
ObserveIndexer alerts once per outage, retrying failed queue writes at most once a minute. Database waits never hold the shared health mutex.
func (*Service) ObservePlayback ¶
ObservePlayback only enqueues; network delivery runs separately in Run. The playback bus also carries console-refresh kinds (update, progress, surface) that are not notification events; those are skipped silently.
func (*Service) Prune ¶
Prune removes favourite-episode alert rows that can no longer be delivered and seen rows whose episodes can no longer alert, and reports the rows removed. notify_once keys are not aged out here: each guards an event its caller may still raise (an update version a downgraded server is offered again; watchlist episode keys are dropped by the watchlist prune).
func (*Service) PublishMQTT ¶
func (s *Service) PublishMQTT(ctx context.Context, brokerID, topic string, payload []byte, qos byte, retain bool) error
PublishMQTT looks up an enabled MQTT notification channel by brokerID, opens its sealed broker credentials, and publishes one MQTT 3.1.1 message.
func (*Service) RegisterChannelKind ¶ added in v0.3.3
func (s *Service) RegisterChannelKind(k ChannelKind) error
RegisterChannelKind adds a channel kind (plugin kinds; WS9f).
func (*Service) Run ¶
Run is the single queue consumer. Failed sends are recorded without automatic retry, avoiding duplicate delivery when an upstream timeout is ambiguous.
func (*Service) SampleHealth ¶
SampleHealth emits one alert on entering an unhealthy state, rather than one alert for every sample. Normal recovery allows a later outage to alert again.
func (*Service) SaveHeartbeat ¶ added in v0.2.4
func (*Service) Subscribe ¶ added in v0.3.3
Subscribe observes successfully emitted events, independent of channel selection.
func (*Service) TitleAvailable ¶
TitleAvailable lets the discovery/watchlist flow publish availability.
func (*Service) TitleAvailableOnce ¶ added in v0.2.48
TitleAvailableOnce publishes availability once per key (an episode, say), however often a caller retries after a failure or crash.
func (*Service) UpdateAvailable ¶ added in v0.2.48
UpdateAvailable announces a release once per version.
func (*Service) UpdateInstalled ¶
UpdateInstalled announces, once per version, a self-update that confirmed healthy.
func (*Service) UpdateRolledBack ¶
UpdateRolledBack announces, once per version, an update that failed and was rolled back.
func (*Service) WatchProcess ¶ added in v0.2.4
WatchProcess starts a small independent delivery process. The returned function must be called on normal exit, with clean=false for a fatal run error. A panic must be allowed to terminate the parent so that EOF reaches the watcher.
type ViewerAlerts ¶ added in v0.3.0
type ViewerAlerts struct {
DB *sql.DB
Active func(context.Context, int64) (*core.User, error)
Now func() time.Time
}
ViewerAlerts keeps viewer notification settings separate from owner channels. Active must consult current membership, not a cached viewer supplied by the caller.
func (*ViewerAlerts) Enabled ¶ added in v0.3.0
Enabled defaults to false for every viewer without an explicit preference.
func (*ViewerAlerts) SetEnabled ¶ added in v0.3.0
SetEnabled records the time of each off-to-on transition so detection can suppress episodes already aired before a viewer opted in.
type ViewerPush ¶ added in v0.3.0
type ViewerPush struct {
Notifications *Service
Preferences *ViewerAlerts
Allowed func(context.Context, *core.User, core.RatingKey) (bool, error)
Now func() time.Time
// Send is optional and permits offline tests; nil uses the web-push transport.
Send func(context.Context, PushSubscription, Event) error
}
ViewerPush uses viewer-owned destinations, separate from owner channels. Allowed must recheck the favorite show and current episode/show policy.
func (*ViewerPush) Drain ¶ added in v0.3.0
func (p *ViewerPush) Drain(ctx context.Context) error
Drain claims recent alerts once per destination across nodes. Claims are intentionally at-most-once: a crash or send failure does not replay a push. Old alerts and alerts preceding subscription or opt-in are never sent.
func (*ViewerPush) PurgeViewer ¶ added in v0.3.0
func (p *ViewerPush) PurgeViewer(ctx context.Context, viewerID int64) error
PurgeViewer removes all destinations after membership deactivation or revocation.
func (*ViewerPush) Register ¶ added in v0.3.0
func (p *ViewerPush) Register(ctx context.Context, viewer *core.User, subscription PushSubscription, grantHash string) error
Register associates a browser endpoint with its current viewer only.
func (*ViewerPush) Registered ¶ added in v0.3.0
func (p *ViewerPush) Registered(ctx context.Context, viewer *core.User, endpoint string) (bool, error)
Registered reports whether this exact browser endpoint belongs to the viewer.