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

Constants

This section is empty.

Variables

View Source
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

    Functions

    This section is empty.

    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

                                                  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.