notifications

type Enqueuer ¶

type Enqueuer interface {
	Enqueue(ctx context.Context, userID, templateID uuid.UUID, labels map[string]string, createdBy string, targets ...uuid.UUID) ([]uuid.UUID, error)
	EnqueueWithData(ctx context.Context, userID, templateID uuid.UUID, labels map[string]string, data map[string]any, createdBy string, targets ...uuid.UUID) ([]uuid.UUID, error)
}

Enqueuer enqueues a new notification message in the store and returns its ID, should it enqueue without failure.

type Handler ¶

type Handler interface {
	// Dispatcher constructs a DeliveryFunc to be used for delivering a notification via the chosen method.
	Dispatcher(payload types.MessagePayload, title, body string, helpers template.FuncMap) (dispatch.DeliveryFunc, error)
}

Handler is responsible for preparing and delivering a notification by a given method.

type InvalidDefaultNotificationMethodError ¶ added in v2.21.0

type InvalidDefaultNotificationMethodError struct {
	Method string
}

func (e InvalidDefaultNotificationMethodError) Error() string

type Manager ¶

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

Manager manages all notifications being enqueued and dispatched.

Manager maintains a notifier: this consumes the queue of notification messages in the store.

The notifier dequeues messages from the store _CODER_NOTIFICATIONS_LEASE_COUNT_ at a time and concurrently "dispatches" these messages, meaning they are sent by their respective methods (email, webhook, etc).

To reduce load on the store, successful and failed dispatches are accumulated in two separate buffers (success/failure) of size CODER_NOTIFICATIONS_STORE_SYNC_INTERVAL in the Manager, and updates are sent to the store about which messages succeeded or failed every CODER_NOTIFICATIONS_STORE_SYNC_INTERVAL seconds. These buffers are limited in size, and naturally introduce some backpressure; if there are hundreds of messages to be sent but they start failing too quickly, the buffers (receive channels) will fill up and block senders, which will slow down the dispatch rate.

NOTE: The above backpressure mechanism only works within the same process, which may not be true forever, such as if we split notifiers out into separate targets for greater processing throughput; in this case we will need an alternative mechanism for handling backpressure.

func NewManager(cfg codersdk.NotificationsConfig, store Store, ps pubsub.Pubsub, helpers template.FuncMap, metrics *Metrics, log slog.Logger, opts ...ManagerOption) (*Manager, error)

func (m *Manager) BufferedUpdatesCount() (success int, failure int)

func (m *Manager) Run(ctx context.Context)

func (m *Manager) Stop(ctx context.Context) error

func (m *Manager) WithHandlers(reg map[database.NotificationMethod]Handler)

type ManagerOption ¶ added in v2.16.0

type ManagerOption func(*Manager)

func WithTestClock(clock quartz.Clock) ManagerOption

type Metrics ¶

type Metrics struct {
	DispatchAttempts *prometheus.CounterVec
	RetryCount       *prometheus.CounterVec

	QueuedSeconds *prometheus.HistogramVec

	InflightDispatches    *prometheus.GaugeVec
	DispatcherSendSeconds *prometheus.HistogramVec

	PendingUpdates prometheus.Gauge
	SyncedUpdates  prometheus.Counter
}

func NewMetrics(reg prometheus.Registerer) *Metrics

type NoopEnqueuer ¶

type NoopEnqueuer struct{}

NoopEnqueuer implements the Enqueuer interface but performs a noop.

func NewNoopEnqueuer() *NoopEnqueuer

func (*NoopEnqueuer) Enqueue(context.Context, uuid.UUID, uuid.UUID, map[string]string, string, ...uuid.UUID) ([]uuid.UUID, error)

func (*NoopEnqueuer) EnqueueWithData(context.Context, uuid.UUID, uuid.UUID, map[string]string, map[string]any, string, ...uuid.UUID) ([]uuid.UUID, error)

type Store ¶

type Store interface {
	AcquireNotificationMessages(ctx context.Context, params database.AcquireNotificationMessagesParams) ([]database.AcquireNotificationMessagesRow, error)
	BulkMarkNotificationMessagesSent(ctx context.Context, arg database.BulkMarkNotificationMessagesSentParams) (int64, error)
	BulkMarkNotificationMessagesFailed(ctx context.Context, arg database.BulkMarkNotificationMessagesFailedParams) (int64, error)
	EnqueueNotificationMessage(ctx context.Context, arg database.EnqueueNotificationMessageParams) error
	FetchNewMessageMetadata(ctx context.Context, arg database.FetchNewMessageMetadataParams) (database.FetchNewMessageMetadataRow, error)
	GetNotificationMessagesByStatus(ctx context.Context, arg database.GetNotificationMessagesByStatusParams) ([]database.NotificationMessage, error)
	GetNotificationsSettings(ctx context.Context) (string, error)
	GetApplicationName(ctx context.Context) (string, error)
	GetLogoURL(ctx context.Context) (string, error)

	InsertInboxNotification(ctx context.Context, arg database.InsertInboxNotificationParams) (database.InboxNotification, error)
}

Store defines the API between the notifications system and the storage. This abstraction is in place so that we can intercept the direct database interactions, or (later) swap out these calls with dRPC calls should we want to split the notifiers out into their own component for high availability/throughput. TODO: don't use database types here

type StoreEnqueuer ¶

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

func NewStoreEnqueuer(cfg codersdk.NotificationsConfig, store Store, helpers template.FuncMap, log slog.Logger, clock quartz.Clock) (*StoreEnqueuer, error)

func (s *StoreEnqueuer) Enqueue(ctx context.Context, userID, templateID uuid.UUID, labels map[string]string, createdBy string, targets ...uuid.UUID) ([]uuid.UUID, error)

func (s *StoreEnqueuer) EnqueueWithData(ctx context.Context, userID, templateID uuid.UUID, labels map[string]string, data map[string]any, createdBy string, targets ...uuid.UUID) ([]uuid.UUID, error)