notification

package
v0.32.0 Latest Latest
Warning

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

 Go to latest Published: Feb 9, 2024 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrStatusUnsupported = errors.New("status check unsupported by provider")

ErrStatusUnsupported should be returned when a Status() check is not supported by the provider.

Functions

This section is empty.

Types

type Alert 

type Alert struct {
	Dest        Dest
	CallbackID  string // CallbackID is the identifier used to communicate a response to the notification
	AlertID     int    // The global alert number
	Summary     string
	Details     string
	ServiceID   string
	ServiceName string

	// OriginalStatus is the status of the first Alert notification to this Dest for this AlertID.
	OriginalStatus *SendResult
}

Alert represents outgoing notifications for alerts.

func (Alert) Body 

func (a Alert) Body() string

func (Alert) Destination 

func (a Alert) Destination() Dest

func (Alert) ExtendedBody 

func (a Alert) ExtendedBody() string

func (Alert) ID 

func (a Alert) ID() string

func (Alert) SubjectID 

func (a Alert) SubjectID() int

func (Alert) Type 

func (a Alert) Type() MessageType

type AlertBundle added in v0.24.0 

type AlertBundle struct {
	Dest        Dest
	CallbackID  string // CallbackID is the identifier used to communicate a response to the notification
	ServiceID   string
	ServiceName string // The service being notified for
	Count       int    // Number of unacked alerts
}

AlertBundle represents a bundle of outgoing alert notifications for a single service.

func (AlertBundle) Destination added in v0.24.0 

func (b AlertBundle) Destination() Dest

func (AlertBundle) ID added in v0.24.0 

func (b AlertBundle) ID() string

func (AlertBundle) Type added in v0.24.0 

func (b AlertBundle) Type() MessageType

type AlertPendingNotification added in v0.29.0 

type AlertPendingNotification struct {
	DestName string
	DestType string
}

type AlertState added in v0.29.0 

type AlertState int

AlertState is the current state of an Alert. 

const (
	AlertStateUnknown AlertState = iota
	AlertStateUnacknowledged
	AlertStateAcknowledged
	AlertStateClosed
)

All alert states

type AlertStatus 

type AlertStatus struct {
	Dest       Dest
	CallbackID string
	AlertID    int
	LogEntry   string
	ServiceID  string

	// Summary of the alert that this status is in regards to.
	Summary string
	// Details of the alert that this status is in regards to.
	Details string

	// OriginalStatus is the status of the first Alert notification to this Dest for this AlertID.
	OriginalStatus SendResult

	// NewAlertState contains the most recent state of the alert.
	NewAlertState AlertState
}

func (AlertStatus) Destination 

func (s AlertStatus) Destination() Dest

func (AlertStatus) ID 

func (s AlertStatus) ID() string

func (AlertStatus) Type 

func (s AlertStatus) Type() MessageType

type Dest 

type Dest struct {
	ID    string
	Type  DestType
	Value string
}

func DestFromPair added in v0.30.0 

func DestFromPair(cm *contactmethod.ContactMethod, nc *notificationchannel.Channel) Dest

DestFromPair will return a Dest for a notification channel/contact method pair.

func (Dest) String added in v0.28.0 

func (d Dest) String() string

type DestType 

type DestType int

DestType represents the type of destination, it is a combination of available contact methods and notification channels. 

const (
	DestTypeUnknown DestType = iota
	DestTypeVoice
	DestTypeSMS
	DestTypeSlackChannel
	DestTypeSlackDM
	DestTypeUserEmail
	DestTypeUserWebhook
	DestTypeChanWebhook
	DestTypeSlackUG
)

func (DestType) CMType added in v0.28.0 

func (t DestType) CMType() contactmethod.Type

CMType returns the contactmethod.Type associated with the DestType.

func (DestType) IsUserCM 

func (t DestType) IsUserCM() bool

IsUserCM returns true if the DestType represents a user contact method.

func (DestType) NCType added in v0.28.0 

func (t DestType) NCType() notificationchannel.Type

NCType returns the notificationchannel.Type associated with the DestType.

func (DestType) String 

func (i DestType) String() string

type FriendlyValuer added in v0.28.0 

type FriendlyValuer interface {
	FriendlyValue(context.Context, string) (string, error)
}

A FriendlyValuer is an optional interface a Sender can implement that allows retrieving a friendly name for a destination value.

For example, a formatted phone number or username for a Slack ID.

type Manager 

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

Manager is used as an intermediary between Senders and Receivers. It should be constructed first (with NewManager()) and passed to Senders and Receivers that require it.

func NewManager 

func NewManager() *Manager

NewManager initializes a new Manager.

func (*Manager) FormatDestValue added in v0.28.0 

func (mgr *Manager) FormatDestValue(ctx context.Context, destType DestType, value string) string

FormatDestValue will format the destination value if an available FriendlyValuer exists for the destType or return the original.

func (*Manager) MessageStatus added in v0.28.0 

func (mgr *Manager) MessageStatus(ctx context.Context, providerMsgID ProviderMessageID) (*Status, DestType, error)

MessageStatus will return the current status of a message.

func (*Manager) RegisterSender 

func (mgr *Manager) RegisterSender(t DestType, name string, s Sender)

RegisterSender will register a sender under a given DestType and name. A sender for the same name and type will replace an existing one, if any.

func (*Manager) SendMessage added in v0.28.0 

func (mgr *Manager) SendMessage(ctx context.Context, msg Message) (*SendResult, error)

SendMessage tries all registered senders for the type given in Notification. An error is returned if there are no registered senders for the type or if an error is returned from all of them.

func (*Manager) SetResultReceiver added in v0.28.0 

func (mgr *Manager) SetResultReceiver(p ResultReceiver)

SetResultReceiver will set the ResultReceiver as the target for all Receiver calls. It will panic if called multiple times.

func (*Manager) SetStubNotifiers 

func (mgr *Manager) SetStubNotifiers()

SetStubNotifiers will cause all notifications senders to be stubbed out.

This causes all notifications to be marked as delivered, but not actually sent.

type Message 

type Message interface {
	ID() string
	Type() MessageType
	Destination() Dest
}

A Message contains information that can be provided to a user for notification.

type MessageLog added in v0.30.1 

type MessageLog struct {
	ID           string
	CreatedAt    time.Time
	LastStatusAt time.Time
	MessageType  MessageType

	LastStatus    State
	StatusDetails string
	SrcValue      string

	AlertID       int
	ProviderMsgID *ProviderMessageID

	UserID   string
	UserName string

	ContactMethodID string

	ChannelID uuid.UUID

	ServiceID   string
	ServiceName string

	SentAt     *time.Time
	RetryCount int
}

type MessageType 

type MessageType int

MessageType indicates the type of notification message. 

const (
	MessageTypeUnknown MessageType = iota
	MessageTypeAlert
	MessageTypeAlertStatus
	MessageTypeTest
	MessageTypeVerification
	MessageTypeAlertBundle

	// MessageTypeAlertStatusBundle is used for bundled status messages.
	//
	// Deprecated: Alert status messages are no longer bundled, status bundle
	// messages are now dropped.
	MessageTypeAlertStatusBundle
	MessageTypeScheduleOnCallUsers
)

Allowed types

func (*MessageType) Scan added in v0.26.0 

func (s *MessageType) Scan(value interface{}) error

func (MessageType) String 

func (i MessageType) String() string

func (MessageType) Value added in v0.26.0 

func (s MessageType) Value() (driver.Value, error)

type ProviderMessageID added in v0.28.0 

type ProviderMessageID struct {
	// ExternalID is the provider-specific identifier for the message.
	ExternalID   string
	ProviderName string
}

ProviderMessageID is a provider-specific identifier for a message.

func ParseProviderMessageID added in v0.29.0 

func ParseProviderMessageID(id string) (ProviderMessageID, error)

ParseProviderMessageID parses a provider-specific identifier for a message.

func (*ProviderMessageID) Scan added in v0.28.0 

func (p *ProviderMessageID) Scan(value interface{}) error

func (ProviderMessageID) String added in v0.29.0 

func (p ProviderMessageID) String() string

String returns a parseable string representation of the provider-specific identifier for a message.

func (ProviderMessageID) Value added in v0.28.0 

func (p ProviderMessageID) Value() (driver.Value, error)

type Receiver 

type Receiver interface {
	// SetMessageStatus can be used to update the state of a message.
	SetMessageStatus(ctx context.Context, externalID string, status *Status) error

	// Receive records a response to a previously sent message.
	Receive(ctx context.Context, callbackID string, result Result) error

	// ReceiveSubject records a response to a previously sent message from a provider/subject (e.g. Slack user).
	ReceiveSubject(ctx context.Context, providerID, subjectID, callbackID string, result Result) error

	// AuthLinkURL will generate a URL to link a provider and subject to a GoAlert user.
	AuthLinkURL(ctx context.Context, providerID, subjectID string, meta authlink.Metadata) (string, error)

	// Start indicates a user has opted-in for notifications to this contact method.
	Start(context.Context, Dest) error

	// Stop indicates a user has opted-out of notifications from a contact method.
	Stop(context.Context, Dest) error

	// IsKnownDest checks if the given destination is known/not disabled.
	IsKnownDest(ctx context.Context, value string) (bool, error)
}

A Receiver processes incoming messages and responses.

type ReceiverSetter added in v0.27.0 

type ReceiverSetter interface {
	SetReceiver(Receiver)
}

ReceiverSetter is an optional interface a Sender can implement for use with two-way interactions.

type Result 

type Result int

Result specifies a response to a notification. 

const (
	ResultAcknowledge Result = iota
	ResultResolve
	ResultEscalate
)

Possible notification responses.

func (Result) String 

func (i Result) String() string

type ResultReceiver added in v0.28.0 

type ResultReceiver interface {
	SetSendResult(ctx context.Context, res *SendResult) error

	Receive(ctx context.Context, callbackID string, result Result) error
	ReceiveSubject(ctx context.Context, providerID, subjectID, callbackID string, result Result) error
	AuthLinkURL(ctx context.Context, providerID, subjectID string, meta authlink.Metadata) (string, error)
	Start(context.Context, Dest) error
	Stop(context.Context, Dest) error

	IsKnownDest(ctx context.Context, destType DestType, destValue string) (bool, error)
}

A ResultReceiver processes notification responses.

type ScannableDestType added in v0.28.0 

type ScannableDestType struct {
	// CM is the contactmethod.Type and should be scanned from the `type` column from `user_contact_methods`.
	CM contactmethod.Type

	// NC is the notificationchannel.Type and should be scanned from the `type` column from `notification_channels`.
	NC notificationchannel.Type
}

ScannableDestType allows scanning a DestType from separate columns for user contact methods and notification channels.

func (ScannableDestType) DestType added in v0.28.0 

func (t ScannableDestType) DestType() DestType

DestType returns a DestType from the scanned values.

type ScheduleOnCallUsers added in v0.28.0 

type ScheduleOnCallUsers struct {
	Dest       Dest
	CallbackID string

	ScheduleID   string
	ScheduleName string
	ScheduleURL  string

	Users []User
}

ScheduleOnCallUsers is a Message that indicates which users are currently on-call for a Schedule

func (ScheduleOnCallUsers) Destination added in v0.28.0 

func (s ScheduleOnCallUsers) Destination() Dest

func (ScheduleOnCallUsers) ID added in v0.28.0 

func (s ScheduleOnCallUsers) ID() string

func (ScheduleOnCallUsers) Type added in v0.28.0 

func (s ScheduleOnCallUsers) Type() MessageType

type SearchCursor added in v0.30.1 

type SearchCursor struct {
	ID        string    `json:"i,omitempty"`
	CreatedAt time.Time `json:"n,omitempty"`
}

SearchCursor is used to indicate a position in a paginated list.

type SearchOptions added in v0.30.1 

type SearchOptions struct {
	Search string       `json:"s,omitempty"`
	After  SearchCursor `json:"a,omitempty"`

	CreatedAfter  time.Time `json:"ca,omitempty"`
	CreatedBefore time.Time `json:"cb,omitempty"`

	// Omit specifies a list of message IDs to exclude from the results
	Omit []string `json:"o,omitempty"`

	Limit int `json:"-"`
}

SearchOptions allow filtering and paginating the list of messages.

type SendResult added in v0.28.0 

type SendResult struct {
	// ID is the GoAlert message ID.
	ID string

	// ProviderMessageID is an identifier that represents the provider-specific ID
	// of the message (e.g. Twilio SID).
	ProviderMessageID ProviderMessageID

	Status

	DestType DestType
}

SendResult represents the result of a sent message.

type Sender 

type Sender interface {
	// Send should return nil error if the notification was sent successfully. It should be expected
	// that a returned error means that the notification should be attempted again.
	//
	// If the sent message can have its status tracked, a unique externalID should be returned.
	Send(context.Context, Message) (*SentMessage, error)
}

A Sender can send notifications.

type SentMessage added in v0.28.0 

type SentMessage struct {
	ExternalID   string
	State        State
	StateDetails string
	SrcValue     string
}

SentMessage contains information about a message that was sent to a remote system.

type State added in v0.28.0 

type State int

State represents the current state of an outgoing message. 

const (
	// StateUnknown is returned when the message has not yet been sent.
	StateUnknown State = iota

	// StateSending should be specified when a message is sending but has not been sent.
	// This includes things like remotely queued, ringing, or in-progress calls.
	StateSending

	// StatePending indicates a message waiting to be sent.
	StatePending

	// StateSent means the message has been sent completely, but may not
	// have been delivered (or delivery confirmation is not supported.). For
	// example, an SMS on the carrier network (but not device) or a voice call
	// that rang but got `no-answer`.
	StateSent

	// StateDelivered means the message is completed and was received
	// by the end device. SMS delivery confirmation, or a voice call was
	// completed (including if it was voice mail).
	StateDelivered

	// StateFailedTemp should be set when a message was not sent (no SMS or ringing phone)
	// but a subsequent try later may succeed. (e.g. voice call with busy signal).
	StateFailedTemp

	// StateFailedPerm should be set when a message was not sent (no SMS or ringing phone)
	// but a subsequent attempt will not be expected to succeed. For messages that fail due to
	// invalid config, they should set this state, as without manual intervention, a retry
	// will also fail.
	StateFailedPerm

	// StateBundled indicates that the message has been bundled into another message.
	StateBundled
)

func (State) IsOK added in v0.28.0 

func (s State) IsOK() bool

IsOK returns true if the message has passed successfully to a remote system (StateSending, StateSent, or StateDelivered).

func (*State) Scan added in v0.30.0 

func (s *State) Scan(value interface{}) error

type Status added in v0.28.0 

type Status struct {

	// State is the current state.
	State State

	// Details can contain any additional information about the State (e.g. "ringing", "no-answer" etc..).
	Details string

	// Sequence can be used when the provider sends updates out-of order (e.g. Twilio).
	// The Sequence number defaults to 0, and a status update is ignored unless its
	// Sequence number is >= the current one.
	Sequence int

	// SrcValue can be used to set/update the source value of the message.
	SrcValue string
	// contains filtered or unexported fields
}

Status describes the current state of an outgoing message.

func (Status) Age added in v0.31.0 

func (s Status) Age() time.Duration

Age returns the amount of time from the message creation until the last status update, if available.

type StatusChecker added in v0.27.0 

type StatusChecker interface {
	Status(ctx context.Context, externalID string) (*Status, error)
}

A StatusChecker is an optional interface a Sender can implement that allows checking the status of a previously sent message by it's externalID.

type Store 

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

func NewStore added in v0.30.0 

func NewStore(ctx context.Context, db *sql.DB) (*Store, error)

func (*Store) Code 

func (s *Store) Code(ctx context.Context, id string) (int, error)

func (*Store) FindManyMessageStatuses added in v0.25.0 

func (s *Store) FindManyMessageStatuses(ctx context.Context, ids []string) ([]SendResult, error)

func (*Store) LastMessageStatus added in v0.26.0 

func (s *Store) LastMessageStatus(ctx context.Context, typ MessageType, cmID string, from time.Time) (*SendResult, time.Time, error)

LastMessageStatus will return the MessageStatus and creation time of the most recent message of the requested type for the provided contact method ID, if one was created from the provided from time.

func (*Store) OriginalMessageStatus added in v0.28.0 

func (s *Store) OriginalMessageStatus(ctx context.Context, alertID int, dst Dest) (*SendResult, error)

OriginalMessageStatus will return the status of the first alert notification sent to `dest` for the given `alertID`.

func (*Store) Search added in v0.30.1 

func (s *Store) Search(ctx context.Context, opts *SearchOptions) ([]MessageLog, error)

func (*Store) SendContactMethodTest 

func (s *Store) SendContactMethodTest(ctx context.Context, id string) error

func (*Store) SendContactMethodVerification 

func (s *Store) SendContactMethodVerification(ctx context.Context, cmID string) error

func (*Store) TimeSeries added in v0.31.0 

func (s *Store) TimeSeries(ctx context.Context, opts TimeSeriesOpts) ([]TimeSeriesBucket, error)

TimeSeries returns a list of time series buckets for the given search options.

func (*Store) VerifyContactMethod 

func (s *Store) VerifyContactMethod(ctx context.Context, cmID string, code int) error

type Test 

type Test struct {
	Dest       Dest
	CallbackID string // CallbackID is the identifier used to communicate a response to the notification
}

Test represents outgoing test notification.

func (Test) Body 

func (t Test) Body() string

func (Test) Destination 

func (t Test) Destination() Dest

func (Test) ExtendedBody 

func (t Test) ExtendedBody() string

func (Test) ID 

func (t Test) ID() string

func (Test) SubjectID 

func (t Test) SubjectID() int

func (Test) Type 

func (t Test) Type() MessageType

type TimeSeriesBucket added in v0.31.0 

type TimeSeriesBucket struct {
	Start time.Time
	End   time.Time
	Count int
}

type TimeSeriesOpts added in v0.31.0 

type TimeSeriesOpts struct {
	SearchOptions
	TimeSeriesOrigin   time.Time
	TimeSeriesInterval time.Duration
}

type UnknownSubjectError added in v0.30.0 

type UnknownSubjectError struct {
	AlertID int
}

UnknownSubjectError is returned from ReceiveSubject when the subject is unknown.

func (UnknownSubjectError) Error added in v0.30.0 

func (e UnknownSubjectError) Error() string

type User added in v0.28.0 

type User struct {
	ID   string
	Name string
	URL  string
}

User provides information about a user for notifications.

type Verification 

type Verification struct {
	Dest       Dest
	CallbackID string // CallbackID is the identifier used to communicate a response to the notification
	Code       int
}

Verification represents outgoing verification code.

func (Verification) Body 

func (v Verification) Body() string

func (Verification) Destination 

func (v Verification) Destination() Dest

func (Verification) ExtendedBody 

func (v Verification) ExtendedBody() string

func (Verification) ID 

func (v Verification) ID() string

func (Verification) SubjectID 

func (v Verification) SubjectID() int

func (Verification) Type 

func (v Verification) Type() MessageType

Source Files

View all Source files

Directories

Path Synopsis

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.