notifications

Documentation

Overview

Package notifications provides a notification system.

Notification Lifecycle

1. Create Notification with an ID and Message. 2. Set possible actions and save it. 3. When the user responds, the action is executed.

Example

// create notification
n := notifications.New("update-available", "A new update is available. Restart to upgrade.")
// set actions and save
n.AddAction("later", "Later").AddAction("restart", "Restart now!").Save()

// wait for user action
selectedAction := <-n.Response()
switch selectedAction {
case "later":
  log.Infof("user wants to upgrade later.")
case "restart":
  log.Infof("user wants to restart now.")
}

Index

• Variables
• type Action
• type Notification
  • func EnsureNotification(r record.Record) (*Notification, error)
  • func Get(id string) *Notification
  • func Notify(n *Notification) *Notification
  • func NotifyInfo(id, msg string, actions ...Action) *Notification
  • func NotifyPrompt(id, msg string, actions ...Action) *Notification
  • func NotifyWarn(id, msg string, actions ...Action) *Notification
  • func (n *Notification) Delete() error
  • func (n *Notification) Expired() <-chan struct{}
  • func (n *Notification) Lock()
  • func (n *Notification) Response() <-chan string
  • func (n *Notification) Save()
  • func (n *Notification) SetActionFunction(fn NotificationActionFn) *Notification
  • func (n *Notification) Unlock()
  • func (n *Notification) Update(expires int64)
• type NotificationActionFn
• type State
• type StorageInterface
  • func (s *StorageInterface) Delete(key string) error
  • func (s *StorageInterface) Get(key string) (record.Record, error)
  • func (s *StorageInterface) Put(r record.Record) (record.Record, error)
  • func (s *StorageInterface) Query(q *query.Query, local, internal bool) (*iterator.Iterator, error)
  • func (s *StorageInterface) ReadOnly() bool
• type Type

Variables

var (
	ErrInvalidData = errors.New("invalid data, must be a notification object")
	ErrInvalidPath = errors.New("invalid path")
	ErrNoDelete    = errors.New("notifications may not be deleted, they must be handled")
)

Storage interface errors

Types

type Action

type Action struct {
	ID   string
	Text string
}

Action describes an action that can be taken for a notification.

type Notification

type Notification struct {
	record.Base
	// EventID is used to identify a specific notification. It consists of
	// the module name and a per-module unique event id.
	// The following format is recommended:
	// 	<module-id>:<event-id>
	EventID string
	// GUID is a unique identifier for each notification instance. That is
	// two notifications with the same EventID must still have unique GUIDs.
	// The GUID is mainly used for system (Windows) integration and is
	// automatically populated by the notification package. Average users
	// don't need to care about this field.
	GUID string
	// Type is the notification type. It can be one of Info, Warning or Prompt.
	Type Type
	// Title is an optional and very short title for the message that gives a
	// hint about what the notification is about.
	Title string
	// Category is an optional category for the notification that allows for
	// tagging and grouping notifications by category.
	Category string
	// Message is the default message shown to the user if no localized version
	// of the notification is available. Note that the message should already
	// have any paramerized values replaced.
	Message string
	// EventData contains an additional payload for the notification. This payload
	// may contain contextual data and may be used by a localization framework
	// to populate the notification message template.
	// If EventData implements sync.Locker it will be locked and unlocked together with the
	// notification. Otherwise, EventData is expected to be immutable once the
	// notification has been saved and handed over to the notification or database package.
	EventData interface{}
	// Expires holds the unix epoch timestamp at which the notification expires
	// and can be cleaned up.
	// Users can safely ignore expired notifications and should handle expiry the
	// same as deletion.
	Expires int64
	// State describes the current state of a notification. See State for
	// a list of available values and their meaning.
	State State
	// AvailableActions defines a list of actions that a user can choose from.
	AvailableActions []*Action
	// SelectedActionID is updated to match the ID of one of the AvailableActions
	// based on the user selection.
	SelectedActionID string
	// contains filtered or unexported fields
}

Notification represents a notification that is to be delivered to the user.

func EnsureNotification

func EnsureNotification(r record.Record) (*Notification, error)

EnsureNotification ensures that the given record is a Notification and returns it.

func Get

func Get(id string) *Notification

Get returns the notification identifed by the given id or nil if it doesn't exist.

func Notify

func Notify(n *Notification) *Notification

Notify sends the given notification.

func NotifyInfo

func NotifyInfo(id, msg string, actions ...Action) *Notification

NotifyInfo is a helper method for quickly showing a info notification. The notification is already shown. If id is an empty string a new UUIDv4 will be generated.

func NotifyPrompt

func NotifyPrompt(id, msg string, actions ...Action) *Notification

NotifyPrompt is a helper method for quickly showing a prompt notification. The notification is already shown. If id is an empty string a new UUIDv4 will be generated.

func NotifyWarn

func NotifyWarn(id, msg string, actions ...Action) *Notification

NotifyWarn is a helper method for quickly showing a warning notification. The notification is already shown. If id is an empty string a new UUIDv4 will be generated.

func (*Notification) Delete

func (n *Notification) Delete() error

Delete (prematurely) cancels and deletes a notification.

func (*Notification) Expired

func (n *Notification) Expired() <-chan struct{}

Expired notifies the caller when the notification has expired.

func (*Notification) Lock

func (n *Notification) Lock()

Lock locks the Notification. If EventData is set and implements sync.Locker it is locked as well. Users that want to replace the EventData on a notification must ensure to unlock the current value on their own. If the new EventData implements sync.Locker as well, it must be locked prior to unlocking the notification.

func (*Notification) Response

func (n *Notification) Response() <-chan string

Response waits for the user to respond to the notification and returns the selected action.

func (*Notification) Save

func (n *Notification) Save()

Save saves the notification.

func (*Notification) SetActionFunction

func (n *Notification) SetActionFunction(fn NotificationActionFn) *Notification

SetActionFunction sets a trigger function to be executed when the user reacted on the notification. The provided function will be started as its own goroutine and will have to lock everything it accesses, even the provided notification.

func (*Notification) Unlock

func (n *Notification) Unlock()

Unlock unlocks the Notification and the EventData, if it implements sync.Locker. See Lock() for more information on how to replace and work with EventData.

func (*Notification) Update

func (n *Notification) Update(expires int64)

Update updates/resends a notification if it was not already responded to.

type NotificationActionFn

type NotificationActionFn func(context.Context, *Notification) error

NotificationActionFn defines the function signature for notification action functions.

type State

type State string

State describes the state of a notification.

const (
	// Active describes a notification that is active, no expired and,
	// if actions are available, still waits for the user to select an
	// action.
	Active State = "active"
	// Responded describes a notification where the user has already
	// selected which action to take but that action is still to be
	// performed.
	Responded State = "responded"
	// Executes describes a notification where the user has selected
	// and action and that action has been performed.
	Executed State = "executed"
)

Possible notification states. State transitions can only happen from top to bottom.

type StorageInterface

type StorageInterface struct {
	storage.InjectBase
}

StorageInterface provices a storage.Interface to the configuration manager.

func (*StorageInterface) Delete

func (s *StorageInterface) Delete(key string) error

Delete deletes a record from the database.

func (*StorageInterface) Get

func (s *StorageInterface) Get(key string) (record.Record, error)

Get returns a database record.

func (*StorageInterface) Put

func (s *StorageInterface) Put(r record.Record) (record.Record, error)

Put stores a record in the database.

func (*StorageInterface) Query

func (s *StorageInterface) Query(q *query.Query, local, internal bool) (*iterator.Iterator, error)

Query returns a an iterator for the supplied query.

func (*StorageInterface) ReadOnly

func (s *StorageInterface) ReadOnly() bool

ReadOnly returns whether the database is read only.

type Type

type Type uint8

Type describes the type of a notification.

const (
	Info    Type = 0
	Warning Type = 1
	Prompt  Type = 2
)

Notification types.