notify

Documentation

Overview

Package notify sends the watch's events that need a person to the desktop notification service, once per event however many watches share the state directory: each event is claimed in notify.json under notify.lock, and only the watch whose claim is first sends it. A lasting condition (the GitHub budget under the floor) is one notification per Repeat; quiet hours hold every kind but a critical one until they end, then send what they held as one notification. The machine's lines (memory, swap, OOM kills, load) are never among them: the supervisor acts on those, through its watch.

Index

• Constants
• Variables
• func DefaultUrgency(kind string) string
• type Delivery
• type Ledger
  • func NewLedger(dir string) *Ledger
  • func (l *Ledger) Path() string
• type Message
• type Notifier
  • func New(p Policy, dir string, s Sender, say func(string)) *Notifier
  • func (n *Notifier) Claim(ctx context.Context, now time.Time, kind string, keys ...string) []string
  • func (n *Notifier) Flush(ctx context.Context, now time.Time)
  • func (n *Notifier) Notify(ctx context.Context, now time.Time, kind, key, summary, body string)
  • func (n *Notifier) Send(ctx context.Context, now time.Time, kind, summary, body string)
• type Policy
• type QuietHours
  • func ParseQuietHours(s string) (*QuietHours, error)
  • func (q *QuietHours) Covers(t time.Time) bool
• type Sender

Constants

const (
	// Due is a note or a timer falling due.
	Due = "due"
	// Budget is the GitHub budget under the floor.
	Budget = "budget"
	// StaleLease is a lease whose holder's session is gone.
	StaleLease = "stale-lease"
	// NoSupervisor is a supervisor whose CLI stayed gone past the restart
	// grace with no successor: claims wait for one.
	NoSupervisor = "no-supervisor"
	// PageUnowned is a page no session has owned for alerts.ownerGrace.
	PageUnowned = "page-unowned"
)

The kinds of events that notify.

const (
	Low      = "low"
	Normal   = "normal"
	Critical = "critical"
)

The urgency levels of the Desktop Notifications Specification.

Variables

var Kinds = []string{Due, Budget, StaleLease, NoSupervisor, PageUnowned}

Kinds are every kind, the default of notify.kinds.

var Urgencies = []string{Low, Normal, Critical}

Urgencies are the urgency levels, lowest first.

Functions

func DefaultUrgency

func DefaultUrgency(kind string) string

DefaultUrgency is the urgency of a kind notify.urgency does not set: critical for a machine without a supervisor and an unowned page, which quiet hours do not hold, else normal.

Types

type Delivery

type Delivery struct {
	At      time.Time `json:"at"`
	Kind    string    `json:"kind"`
	Summary string    `json:"summary"`
	Body    string    `json:"body,omitempty"`
	Urgency string    `json:"urgency"`
	ID      uint32    `json:"id,omitempty"`
	Held    bool      `json:"held,omitempty"`
	Error   string    `json:"error,omitempty"`
}

Delivery is one notification: sent (with the id the service gave it), failed, or held for the end of the quiet hours.

type Ledger

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

Ledger keeps notify.json in beekeeper's state directory, changed only under notify.lock.

func NewLedger

func NewLedger(dir string) *Ledger

NewLedger returns the ledger kept in dir.

func (*Ledger) Path

func (l *Ledger) Path() string

Path is the ledger file.

type Message

type Message struct {
	Summary string
	Body    string
	// Urgency is low, normal or critical.
	Urgency string
}

Message is one desktop notification.

type Notifier

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

Notifier sends one watch's events.

func New

func New(p Policy, dir string, s Sender, say func(string)) *Notifier

New returns a notifier that claims events in dir and sends them with s.

func (*Notifier) Claim

func (n *Notifier) Claim(ctx context.Context, now time.Time, kind string, keys ...string) []string

Claim records the events of kind identified by keys and returns the keys no watch had claimed before, or claimed longer than Repeat ago for a repeating kind; a lasting kind is claimed as the kind itself and takes no keys. A kind notify.kinds leaves out claims nothing.

func (*Notifier) Flush

func (n *Notifier) Flush(ctx context.Context, now time.Time)

Flush sends what the quiet hours held, as one notification, once they have ended; the watch that takes the held events first sends them.

func (*Notifier) Notify

func (n *Notifier) Notify(ctx context.Context, now time.Time, kind, key, summary, body string)

Notify claims one event and sends it if the claim is this watch's.

func (*Notifier) Send

func (n *Notifier) Send(ctx context.Context, now time.Time, kind, summary, body string)

Send delivers a claimed event, or holds it in quiet hours unless its urgency is critical.

type Policy

type Policy struct {
	Kinds   []string
	Quiet   *QuietHours
	Urgency map[string]string
	// Repeat is how often a lasting condition notifies again.
	Repeat time.Duration
}

Policy is what notifies, when and how urgently.

type QuietHours

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

QuietHours is a daily span of local time, "22:00-07:00"; it may wrap around midnight.

func ParseQuietHours

func ParseQuietHours(s string) (*QuietHours, error)

ParseQuietHours reads "HH:MM-HH:MM"; empty is none.

func (*QuietHours) Covers

func (q *QuietHours) Covers(t time.Time) bool

Covers reports whether t falls in the quiet hours.

type Sender

type Sender interface {
	Send(ctx context.Context, m Message) (uint32, error)
}

Sender delivers a message and returns the id the notification service gave it.