notification

Documentation

Overview

Package notification provides a way to send notifications to users.

Index

• Constants
• Variables
• func LoadNotification(ctx context.Context, t openapi.NotificationType) (openapi.NotificationMessage, error)
• type ConfigError
  • func (e ConfigError) Error() string
  • func (e ConfigError) Unwrap() error
• type EmailNotificationConfig
• type EmailService
  • func NewEmailService(config e2clickermodule.Notification, logger *slog.Logger, lc fx.Lifecycle) (*EmailService, error)
  • func (s EmailService) Notify(ctx context.Context, n Notification, config EmailNotificationConfig) error
• type GotifyNotificationConfig
  • func (c *GotifyNotificationConfig) Validate() error
• type GotifyService
  • func NewGotifyService(c *http.Client) *GotifyService
  • func (s GotifyService) Notify(ctx context.Context, n Notification, config GotifyNotificationConfig) error
• type HTTPUnknownStatusError
  • func (e HTTPUnknownStatusError) Error() string
• type Notification
• type NotificationConfigs
  • func (c NotificationConfigs) IsEmpty() bool
• type NotificationMethodSupports
• type NotificationService
  • func NewNotificationService(s NotificationServiceConfig, logger *slog.Logger) NotificationService
• type NotificationServiceConfig
  • func (c NotificationServiceConfig) Supports() NotificationMethodSupports
• type PushoverNotificationConfig
  • func (c *PushoverNotificationConfig) Validate() error
• type PushoverService
  • func NewPushoverService(c *http.Client) *PushoverService
  • func (s PushoverService) Notify(ctx context.Context, n Notification, config PushoverNotificationConfig) error
• type UnknownServiceError
  • func (e UnknownServiceError) Error() string
• type UserNotificationService
  • func NewUserNotificationService(s UserNotificationServiceConfig) UserNotificationService
• type UserNotificationServiceConfig
• type UserNotificationStorage
• type UserPreferences
• type WebPushNotificationConfig
• type WebPushService
  • func NewWebPushSevice(config e2clickermodule.Notification) (*WebPushService, error)
  • func (s WebPushService) Notify(ctx context.Context, n Notification, config WebPushNotificationConfig) error
  • func (s WebPushService) VAPIDPublicKey() string
• type WebPushSubscriptionExpired
  • func (e WebPushSubscriptionExpired) Error() string

Constants

const HTTPErrorMaxBodySize = 1024

Variables

var ErrUnknownNotificationType = errors.New("unknown notification type")

ErrUnknownNotificationType is returned when the notification type is unknown.

var ErrWebPushNotAvailable = fmt.Errorf("WebPush is not available")

ErrWebPushNotAvailable is returned when WebPush is not available.

var Module = fx.Module("notification",
	fx.Decorate(func(slog *slog.Logger) *slog.Logger {
		return slog.With("module", "notification")
	}),
	fx.Provide(
		NewNotificationService,
		NewUserNotificationService,
		NewGotifyService,
		NewPushoverService,
		NewWebPushSevice,
		NewEmailService,
	),
)

Functions

func LoadNotification

func LoadNotification(ctx context.Context, t openapi.NotificationType) (openapi.NotificationMessage, error)

LoadNotification loads a notification message of the given type.

Types

type ConfigError

type ConfigError struct {
	Service string `json:"service"`
	// contains filtered or unexported fields
}

ConfigError is returned when a notification service is given an invalid configuration or the configuration fails validation.

func (ConfigError) Error

func (e ConfigError) Error() string

func (ConfigError) Unwrap

func (e ConfigError) Unwrap() error

type EmailNotificationConfig

type EmailNotificationConfig = openapi.EmailSubscription

EmailNotificationConfig is a user configuration for the email service.

type EmailService

type EmailService struct {
	// contains filtered or unexported fields
}

EmailService is a service for sending notifications via email.

func NewEmailService

func NewEmailService(config e2clickermodule.Notification, logger *slog.Logger, lc fx.Lifecycle) (*EmailService, error)

NewEmailService creates a new email service.

func (EmailService) Notify

func (s EmailService) Notify(ctx context.Context, n Notification, config EmailNotificationConfig) error

type GotifyNotificationConfig

type GotifyNotificationConfig struct {
	BaseURL  string         `json:"base_url"`
	Token    string         `json:"token"`
	Priority int            `json:"priority,omitempty"`
	Extras   map[string]any `json:"extras,omitempty"`
}

func (*GotifyNotificationConfig) Validate

func (c *GotifyNotificationConfig) Validate() error

type GotifyService

type GotifyService struct {
	// contains filtered or unexported fields
}

GotifyService is a service for sending notifications via Gotify.

func NewGotifyService

func NewGotifyService(c *http.Client) *GotifyService

NewGotifyService creates a new Gotify service.

func (GotifyService) Notify

func (s GotifyService) Notify(ctx context.Context, n Notification, config GotifyNotificationConfig) error

type HTTPUnknownStatusError

type HTTPUnknownStatusError struct {
	// StatusCode is the HTTP status code of the API response.
	StatusCode int `json:"statusCode"`
	// Body is the body of the API response.
	// It is truncated to [HTTPErrorMaxBodySize] bytes.
	Body string `json:"body"`
}

HTTPUnknownStatusError is returned when an unknown HTTP status code is returned by an API.

func (HTTPUnknownStatusError) Error

func (e HTTPUnknownStatusError) Error() string

type Notification

type Notification = openapi.Notification

Notification describes a notification message to be sent to the user.

type NotificationConfigs

type NotificationConfigs struct {
	Gotify   []GotifyNotificationConfig   `json:"gotify,omitempty"`
	Pushover []PushoverNotificationConfig `json:"pushover,omitempty"`
	WebPush  []openapi.PushSubscription   `json:"webPush,omitempty"`
	Email    []EmailNotificationConfig    `json:"email,omitempty"`
}

NotificationConfigs contains all the configurations for a notification.

func (NotificationConfigs) IsEmpty

func (c NotificationConfigs) IsEmpty() bool

IsEmpty returns true if the notification configs are empty.

type NotificationMethodSupports

type NotificationMethodSupports struct {
	Gotify   bool `json:"gotify"`
	Pushover bool `json:"pushover"`
	WebPush  bool `json:"webPush"`
	Email    bool `json:"email"`
}

NotificationMethodSupports lists the supported notification services.

type NotificationService

type NotificationService interface {
	// Notify sends a notification to all the services.
	Notify(ctx context.Context, n Notification, c NotificationConfigs) error
	// Config returns the configuration for the notification service.
	Config() NotificationServiceConfig
}

NotificationService is a collection of NotificationServices. It implements the [Notifier] interface.

func NewNotificationService

func NewNotificationService(s NotificationServiceConfig, logger *slog.Logger) NotificationService

NewNotificationService creates a new notification service.

type NotificationServiceConfig

type NotificationServiceConfig struct {
	fx.In
	Gotify   *GotifyService   `optional:"true"`
	Pushover *PushoverService `optional:"true"`
	WebPush  *WebPushService  `optional:"true"`
	Email    *EmailService    `optional:"true"`
}

NotificationServiceConfig is the configuration for the notification service.

func (NotificationServiceConfig) Supports

func (c NotificationServiceConfig) Supports() NotificationMethodSupports

Supports returns the supported notification services.

type PushoverNotificationConfig

type PushoverNotificationConfig struct {
	Endpoint string `json:"endpoint"`
	User     string `json:"user"`
	Token    string `json:"token"`
	Priority int    `json:"priority,omitempty"`
	Sound    string `json:"sound,omitempty"`
	Device   string `json:"device,omitempty"`
}

func (*PushoverNotificationConfig) Validate

func (c *PushoverNotificationConfig) Validate() error

Validate checks that the configuration is valid.

type PushoverService

type PushoverService struct {
	// contains filtered or unexported fields
}

PushoverService is a service for sending notifications via Pushover.

func NewPushoverService

func NewPushoverService(c *http.Client) *PushoverService

NewPushoverService creates a new Pushover service.

func (PushoverService) Notify

func (s PushoverService) Notify(ctx context.Context, n Notification, config PushoverNotificationConfig) error

type UnknownServiceError

type UnknownServiceError struct {
	Service string `json:"service"`
}

UnknownServiceError is returned when an unknown service is requested.

func (UnknownServiceError) Error

func (e UnknownServiceError) Error() string

type UserNotificationService

type UserNotificationService interface {
	// NotifyUser sends a notification to a user.
	NotifyUser(ctx context.Context, secret user.Secret, t openapi.NotificationType) error
	// UserPreferences returns the preferences of a user.
	UserPreferences(ctx context.Context, secret user.Secret) (UserPreferences, error)
	// SetUserPreferences sets the preferences of a user.
	SetUserPreferences(ctx context.Context, secret user.Secret, preferences *UserPreferences) error
	// SetUserPreferencesSafe sets the preferences of a user in a safer manner than
	// [SetUserPreferences]. It requires the old preferences to be passed in order
	// to prevent overwriting changes made by other clients.
	//
	// Realistically, this doesn't happen unless the user is deliberately trying to
	// cause the issue.
	SetUserPreferencesSafe(ctx context.Context, secret user.Secret, newPreferences, oldPreferences *UserPreferences) error
}

UserNotificationService is a service that sends notifications to users.

func NewUserNotificationService

func NewUserNotificationService(s UserNotificationServiceConfig) UserNotificationService

NewUserNotificationService creates a new user notification service.

type UserNotificationServiceConfig

type UserNotificationServiceConfig struct {
	fx.In

	UserNotificationStorage
	NotificationService
	*user.UserService
	*slog.Logger
}

UserNotificationServiceConfig is the configuration for the user notification service.

type UserNotificationStorage

type UserNotificationStorage interface {
	// UserPreferences returns the preferences of a user.
	UserPreferences(ctx context.Context, userSecret user.Secret) (UserPreferences, error)
	// SetUserPreferencesTx sets the preferences of a user inside a transaction.
	// The function set is called with the current preferences and should modify
	// the given preferences, all within the same transaction.
	SetUserPreferencesTx(ctx context.Context, userSecret user.Secret, set func(*UserPreferences) error) error
}

type UserPreferences

type UserPreferences struct {
	NotificationConfigs NotificationConfigs         `json:"notificationConfigs"`
	CustomNotifications openapi.CustomNotifications `json:"customNotifications,omitempty"`
}

UserPreferences is the preferences of a user. It is JSON-serializable.

type WebPushNotificationConfig

type WebPushNotificationConfig = openapi.PushSubscription

WebPushNotificationConfig is a configuration for the Push API service.

type WebPushService

type WebPushService struct {
	// contains filtered or unexported fields
}

WebPushService is a service for sending notifications via the Push API.

func NewWebPushSevice

func NewWebPushSevice(config e2clickermodule.Notification) (*WebPushService, error)

NewWebPushSevice creates a new Push API service.

func (WebPushService) Notify

func (s WebPushService) Notify(ctx context.Context, n Notification, config WebPushNotificationConfig) error

func (WebPushService) VAPIDPublicKey

func (s WebPushService) VAPIDPublicKey() string

VAPIDPublicKey returns the VAPID public key.

type WebPushSubscriptionExpired

type WebPushSubscriptionExpired struct {
	ExpiredAt time.Time `json:"expiredAt"`
}

WebPushSubscriptionExpired is returned when a WebPush subscription has expired.

func (WebPushSubscriptionExpired) Error

func (e WebPushSubscriptionExpired) Error() string