notifications

Documentation

Overview

COPYRIGHT 2024 FERMI NATIONAL ACCELERATOR LABORATORY

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package notifications contains functions needed to send notifications to the relevant stakeholders for the FIFE Managed Tokens Utilities

The two EmailManager funcs here, NewServiceEmailManager, and NewAdminEmailManager, are the primary interfaces by which calling code should send notifications that need to eventually be send via email. Either of these will sort error notifications properly.const

We expect callers to call NewServiceEmailManager if they are running any of the utilities for a service, and want to abstract away the notification sorting and sending.

NewAdminEmailManager can be called if the notifications will only be sent to admins. In this case, the calling code is expected to separately run SendAdminNotifications to actually send the accumulated data.

Both of these EmailManagers require a configured *email object to be passed in. The implication, then, is that using this package to collect and send notifications pre-supposes that one of these notifications will be of the email type.

Index

• func NewEmail(from string, to []string, subject, smtpHost string, smtpPort int) *email
• func NewPushError(message, service, node string) *pushError
• func NewSetupError(message, service string) *setupError
• func NewSlackMessage(url string) *slackMessage
• func PrepareTableStringFromMap(m map[string]string, helpMessage string, header []string) string
• func SendAdminNotifications(ctx context.Context, operation string, isTest bool, ...) error
• func SendMessage(ctx context.Context, s SendMessager, msg string) error
• type AdminDataFinal
• type AdminNotificationManager
  • func NewAdminNotificationManager(ctx context.Context, opts ...AdminNotificationManagerOption) *AdminNotificationManager
  • func (a *AdminNotificationManager) RegisterNotificationSource(ctx context.Context) chan<- SourceNotification
  • func (a *AdminNotificationManager) RequestToCloseReceiveChan(ctx context.Context)
• type AdminNotificationManagerOption
  • func SetAdminNotificationManagerDatabase(database *db.ManagedTokensDatabase) AdminNotificationManagerOption
  • func SetAdminNotificationManagerNotificationMinimum(notificationMinimum int) AdminNotificationManagerOption
  • func SetDatabaseReadOnlyToTrue() AdminNotificationManagerOption
  • func SetTrackErrorCountsToTrue() AdminNotificationManagerOption
• type Notification
• type SendMessageError
  • func (s *SendMessageError) Error() string
• type SendMessager
• type ServiceEmailManager
  • func NewServiceEmailManager(ctx context.Context, wg *sync.WaitGroup, service string, e *email, ...) *ServiceEmailManager
• type ServiceEmailManagerOption
  • func SetAdminNotificationManager(a *AdminNotificationManager) ServiceEmailManagerOption
  • func SetReceiveChan(c chan Notification) ServiceEmailManagerOption
  • func SetServiceEmailManagerNotificationMinimum(notificationMinimum int) ServiceEmailManagerOption
• type SourceNotification

Functions

func NewEmail

func NewEmail(from string, to []string, subject, smtpHost string, smtpPort int) *email

NewEmail returns an *email that can be used to send a message using SendMessage()

func NewPushError

func NewPushError(message, service, node string) *pushError

NewPushError returns a *pushError that can be populated and then sent through an EmailManager

func NewSetupError

func NewSetupError(message, service string) *setupError

NewSetupError returns a *setupError that can be populated and then sent through an EmailManager

func NewSlackMessage

func NewSlackMessage(url string) *slackMessage

NewSlackMessage returns a configured *slackMessage that can be used to send a message using SendMessage()

func PrepareTableStringFromMap

func PrepareTableStringFromMap(m map[string]string, helpMessage string, header []string) string

PrepareTableStringFromMap formats a map[string]string and appends a message onto the beginning

func SendAdminNotifications

func SendAdminNotifications(ctx context.Context, operation string, isTest bool, sendMessagers ...SendMessager) error

SendAdminNotifications sends admin messages via email and Slack that have been collected in adminErrors. It expects a valid template file configured at adminTemplatePath

func SendMessage

func SendMessage(ctx context.Context, s SendMessager, msg string) error

SendMessage sends a message (msg). The kind of message and how that message is sent is determined by the SendMessager, which should be configured before passing into SendMessage

Types

type AdminDataFinal

type AdminDataFinal struct {
	SetupErrors     []string
	PushErrorsTable string
}

AdminDataFinal stores the same information as adminData, but with the PushErrors converted to string form, as a table. The PushErrorsTable field is meant to be read as is and used directly in an admin message

type AdminNotificationManager

type AdminNotificationManager struct {

	// Database is the underlying *db.ManagedTokensDatabase that will be queried by the AdminNotificationManager to determine whether
	// or not to send a particular Notification received on the ReceiveChan to administrators
	Database *db.ManagedTokensDatabase
	// NotificationMinimum is the minimum number of prior similar Notifications required for an AdminNotificationManager to determine that it should
	// send a Notification to administrators
	NotificationMinimum int
	// TrackErrorCounts determines whether or not the AdminNotificationManager should consult the Database or not when deciding whether to send a
	// Notification sent on its ReceiveChan.  If set to false, all received Notifications will be sent to administrators.
	// This should only be set to true if there are no other possible decision-makers like callers that call registerNotificationSource
	TrackErrorCounts bool
	// DatabaseReadOnly determines whether the AdminNotificationManager should write its error counts to the db.ManagedTokensDatabase after finishing
	// all processing.  This should only be set to false if there are no other possible database writers (like ServiceEmailManager), to avoid double-counting
	// of errors
	DatabaseReadOnly bool
	// contains filtered or unexported fields
}

AdminNotificationManager holds information needed to receive and handle notifications meant to be sent to the administrators of the managed tokens utilities.

func NewAdminNotificationManager

func NewAdminNotificationManager(ctx context.Context, opts ...AdminNotificationManagerOption) *AdminNotificationManager

NewAdminNotificationManager returns an EmailManager channel for callers to send Notifications on. It will collect messages and sort them according to the underlying type of the Notification. Calling code is expected to run SendAdminNotifications separately to send the accumulated data via email (or otherwise). Functional options should be specified to set the fields (see AdminNotificationManagerOption documentation). This function should never be called more than once concurrently.

func (*AdminNotificationManager) RegisterNotificationSource

func (a *AdminNotificationManager) RegisterNotificationSource(ctx context.Context) chan<- SourceNotification

registerNotificationSource will return a channel on which callers can send SourceNotifications. It also spins up a listener goroutine that forwards these Notifications to the AdminNotificationManager's ReceiveChan as long as the context is alive

func (*AdminNotificationManager) RequestToCloseReceiveChan

func (a *AdminNotificationManager) RequestToCloseReceiveChan(ctx context.Context)

RequestToCloseReceiveChan will wait until either all notificationSources have finished sending Notifications, or until the context expires. If the former happens, then the AdminNotificationsManager's ReceiveChan will be closed. Otherwise, the function will return without closing the channel (allowing the program to exit without sending notifications). In the case of multiple goroutines sending notifications to the AdminNotificationManager, this method is how the ReceiveChan should be closed.

type AdminNotificationManagerOption

type AdminNotificationManagerOption func(*AdminNotificationManager) error

AdminNotificationManagerOption is a functional option that should be used as an argument to NewAdminNotificationManager to set various fields of the AdminNotificationManager For example:

 f := func(a *AdminNotificationManager) error {
	  a.NotificationMinimum = 42
   return nil
 }
 g := func(a *AdminNotificationManager) error {
	  a.DatabaseReadOnly = false
   return nil
 }
 manager := NewAdminNotificationManager(context.Background(), f, g)

func SetAdminNotificationManagerDatabase

func SetAdminNotificationManagerDatabase(database *db.ManagedTokensDatabase) AdminNotificationManagerOption

func SetAdminNotificationManagerNotificationMinimum

func SetAdminNotificationManagerNotificationMinimum(notificationMinimum int) AdminNotificationManagerOption

func SetDatabaseReadOnlyToTrue

func SetDatabaseReadOnlyToTrue() AdminNotificationManagerOption

func SetTrackErrorCountsToTrue

func SetTrackErrorCountsToTrue() AdminNotificationManagerOption

type Notification

type Notification interface {
	GetMessage() string
	GetService() string
}

Notification is an interface to various types of notifications sent by a caller to

type SendMessageError

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

SendMessageError indicates that an error occurred sending a message

func (*SendMessageError) Error

func (s *SendMessageError) Error() string

type SendMessager

type SendMessager interface {
	// contains filtered or unexported methods
}

SendMessager wraps the SendMessage method

type ServiceEmailManager

type ServiceEmailManager struct {
	ReceiveChan chan Notification
	Service     string
	Email       SendMessager
	// AdminNotificationsManager is a pointer to an AdminNotificationManager that carries with it, among other things, the db.ManagedTokensDatabase
	// that the ServiceEmailManager should read from and write to
	*AdminNotificationManager

	NotificationMinimum int
	// contains filtered or unexported fields
}

ServiceEmailManager contains all the information needed to receive Notifications for services and ensure they get sent in the correct email

func NewServiceEmailManager

func NewServiceEmailManager(ctx context.Context, wg *sync.WaitGroup, service string, e *email, opts ...ServiceEmailManagerOption) *ServiceEmailManager

NewServiceEmailManager returns an EmailManager channel for callers to send Notifications on. It will collect messages and sort them according to the underlying type of the Notification, and when EmailManager is closed, will send emails. Set up the ManagedTokensDatabase and the NotificationMinimum via EmailManagerOptions passed in. If a ManagedTokensDatabase is not passed in via an EmailManagerOption, then the EmailManager will send all notifications

type ServiceEmailManagerOption

type ServiceEmailManagerOption func(*ServiceEmailManager) error

ServiceEmailManagerOption is a functional option that should be used as an argument to NewServiceEmailManager to set various fields of the ServiceEmailManager For example:

var wg sync.WaitGroup

f := func(a *ServiceEmailManager) error {
	 a.NotificationMinimum = 42
	 return nil
}

manager := NewServiceEmailManager(context.Background(), &wg, e, f)

func SetAdminNotificationManager

func SetAdminNotificationManager(a *AdminNotificationManager) ServiceEmailManagerOption

func SetReceiveChan

func SetReceiveChan(c chan Notification) ServiceEmailManagerOption

func SetServiceEmailManagerNotificationMinimum

func SetServiceEmailManagerNotificationMinimum(notificationMinimum int) ServiceEmailManagerOption

type SourceNotification

type SourceNotification struct {
	Notification
}

SourceNotification is a type containing a Notification. It should be used to send notifications from callers that are sending Notifications to the AdminNotificationManager via a channel gotten via registerNotificationSource. The notifications/admin package will send all of these types of Notifications - that is, it will not run any checks to determine whether a SourceNotification should be sent.