notifications

package
v0.12.3 Latest Latest
Warning

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

 Go to latest Published: Oct 15, 2021 License: GPL-3.0 Imports: 15 Imported by: 2

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

View Source 
const (
	ActionTypeNone        = ""             // Report selected ID back to backend.
	ActionTypeOpenURL     = "open-url"     // Open external URL
	ActionTypeOpenPage    = "open-page"    // Payload: Page ID
	ActionTypeOpenSetting = "open-setting" // Payload: See struct definition below.
	ActionTypeOpenProfile = "open-profile" // Payload: Scoped Profile ID
	ActionTypeInjectEvent = "inject-event" // Payload: Event ID
	ActionTypeWebhook     = "call-webhook" // Payload: See struct definition below.
)

Action Types.

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

View Source 
var (
	CfgUseSystemNotificationsKey = "core/useSystemNotifications"
)

Configuration Keys.

Functions

func Delete added in v0.10.0 

func Delete(id string)

Delete deletes the notification with the given id.

Types

type Action 

type Action struct {
	// ID specifies a unique ID for the action. If an action is selected, the ID
	// is written to SelectedActionID and the notification is saved.
	// If the action type is not ActionTypeNone, the ID may be empty, signifying
	// that this action is merely additional and selecting it does not dismiss the
	// notification.
	ID string
	// Text on the button.
	Text string
	// Type specifies the action type. Implementing interfaces should only
	// display action types they can handle.
	Type ActionType
	// Payload holds additional data for special action types.
	Payload interface{}
}

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

type ActionType added in v0.10.0 

type ActionType string

ActionType defines a specific type of action.

type ActionTypeOpenSettingPayload added in v0.10.0 

type ActionTypeOpenSettingPayload struct {
	// Key is the key of the setting.
	Key string
	// Profile is the scoped ID of the profile.
	// Leaving this empty opens the global settings.
	Profile string
}

ActionTypeOpenSettingPayload defines the payload for the OpenSetting Action Type.

type ActionTypeWebhookPayload added in v0.10.0 

type ActionTypeWebhookPayload struct {
	// HTTP Method to use. Defaults to "GET", or "POST" if a Payload is supplied.
	Method string
	// URL to call.
	// If the URL is relative, prepend the current API endpoint base path.
	// If the URL is absolute, send request to the Portmaster.
	URL string
	// Payload holds arbitrary payload data.
	Payload interface{}
	// ResultAction defines what should be done with successfully returned data.
	// Must one of:
	// - `ignore`: do nothing (default)
	// - `display`: the result is a human readable message, display it in a success message.
	ResultAction string
}

ActionTypeWebhookPayload defines the payload for the WebhookPayload Action Type.

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
	// ShowOnSystem specifies if the notification should be also shown on the
	// operating system. Notifications shown on the operating system level are
	// more focus-intrusive and should only be used for important notifications.
	// If the configuration option "Desktop Notifications" is switched off, this
	// will be forced to false on the first save.
	ShowOnSystem bool
	// 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 added in v0.9.0 

func Notify(n *Notification) *Notification

Notify sends the given notification.

func NotifyError added in v0.10.0 

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

NotifyError is a helper method for quickly showing an error notification. The notification will be activated immediately. If the provided id is empty, an id will derived from msg. ShowOnSystem is enabled. If no actions are defined, a default "OK" (ID:"ack") action will be added.

func NotifyInfo added in v0.5.2 

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

NotifyInfo is a helper method for quickly showing an info notification. The notification will be activated immediately. If the provided id is empty, an id will derived from msg. ShowOnSystem is disabled. If no actions are defined, a default "OK" (ID:"ack") action will be added.

func NotifyPrompt added in v0.5.2 

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

NotifyPrompt is a helper method for quickly showing a prompt notification. The notification will be activated immediately. If the provided id is empty, an id will derived from msg. ShowOnSystem is disabled. If no actions are defined, a default "OK" (ID:"ack") action will be added.

func NotifyWarn added in v0.5.2 

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

NotifyWarn is a helper method for quickly showing a warning notification The notification will be activated immediately. If the provided id is empty, an id will derived from msg. ShowOnSystem is enabled. If no actions are defined, a default "OK" (ID:"ack") action will be added.

func (*Notification) AttachToModule added in v0.10.0 

func (n *Notification) AttachToModule(m *modules.Module)

AttachToModule attaches the notification to a module and changes to the notification will be reflected on the module failure status.

func (*Notification) Delete added in v0.3.0 

func (n *Notification) Delete()

Delete (prematurely) cancels and deletes a notification.

func (*Notification) Expired added in v0.3.0 

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 added in v0.3.0 

func (n *Notification) Update(expires int64)

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

type NotificationActionFn added in v0.9.0 

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

NotificationActionFn defines the function signature for notification action functions.

type State added in v0.9.0 

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 added in v0.9.0 

type Type uint8

Type describes the type of a notification. 

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

Notification types.

Source Files

View all Source files

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.