notifications

package
v1.21.1 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package notifications provides the notification client for sending Watchtower update messages. It integrates with Shoutrrr for service delivery, supporting custom templates, batching, and JSON marshaling.

Key components:

  • NewNotifier: Constructs the client from a *zerolog.Logger and internal/config/notify.Notify (notifier.go).
  • NewNotifierFromFlags: Test helper that reads Cobra flags then calls NewNotifier.
  • RegisterHook: Attaches the notifier as a zerolog.Hook on the process logger (shoutrrr.go).
  • Shoutrrr Integration: Handles message sending and batching (shoutrrr.go).
  • JSON Marshaling: Formats notification data (json.go).

Note: The legacy notification types (email, slack, msteams, gotify) and their individual flags (e.g., --notification-email-from, --notification-slack-hook-url) are deprecated. Use --notification-url with the appropriate shoutrrr URL scheme instead. See the deprecation notices on specific types and functions for details.

Usage example (after config.Load): 

notifier := notifications.NewNotifier(log, cfg.Notify)
notifier.RegisterHook(log) // updates *log in place to the hooked logger
notifier.StartNotification(false)
// ... application logging via the hooked logger is batched ...
notifier.SendNotification(report)
notifier.Close()

The package uses Shoutrrr for service abstraction and custom templates. Logging uses *zerolog.Logger passed from the composition root (no global logger).

RegisterHook captures zerolog events for notification batching. All process logging uses github.com/rs/zerolog. There is no dual-logger hook shim.

Index

Constants

View Source 
const ColorHex = "#406170"

ColorHex is the default notification color used for services that support it (formatted as a CSS hex string).

View Source 
const ColorInt = 0x406170

ColorInt is the default notification color used for services that support it (as an int value).

Variables

View Source 
var Funcs = template.FuncMap{
	"ToUpper":         strings.ToUpper,
	"ToLower":         strings.ToLower,
	"ToJSON":          toJSON,
	"ToPorcelainJSON": ToPorcelainJSON,
	"Title":           cases.Title(language.AmericanEnglish).String,
	"RFC1123":         formatRFC1123,
}

Funcs defines utility functions for notification templates.

Functions

func AppendLegacyUrls deprecated 

func AppendLegacyUrls(log *zerolog.Logger, urls []string, cmd *cobra.Command) ([]string, time.Duration)

AppendLegacyUrls adds shoutrrr URLs from legacy notification flags.

Parameters:

  • log: Logger for diagnostics.
  • urls: Initial URL list.
  • cmd: Cobra command with flags.

Returns:

  • []string: Updated URL list.
  • time.Duration: Notification delay (legacy delay notifier or --notifications-delay).

Deprecated: Legacy notification types are deprecated. Use --notification-url instead. Prefer NewNotifier with Config.Notify from config.Load.

TODO: Remove AppendLegacyUrls for the v2 release.

func BuildURLs 

func BuildURLs(log *zerolog.Logger, cfg notifyConfig.Notify) ([]string, error)

BuildURLs builds Shoutrrr notification URLs from resolved notification settings without initializing a notifier.

It returns configured URLs plus any legacy Shoutrrr URLs generated from deprecated notification types. Errors are returned instead of causing a fatal exit.

Parameters:

  • log: Logger for legacy notifier construction diagnostics.
  • cfg: Notification settings from config.Load (Config.Notify).

Returns:

  • []string: Shoutrrr URLs ready for output or notification use.
  • error: Non-nil if an unknown legacy notification type is specified or if a legacy notifier fails to generate its URL.

TODO: Remove BuildURLs after the v2 release.

func FlushSplitByContainer 

func FlushSplitByContainer(notifier types.Notifier)

FlushSplitByContainer sends one notification per distinct container value in the queued entries, then clears the queue.

Used by the check API split path. This is intentionally a package-level helper (not on types.Notifier): the only production Notifier is *shoutrrrTypeNotifier. Adding a split method to the interface would force every mock or stub to implement it. Non-shoutrrr values fall back to a single SendNotification(nil).

Parameters:

  • notifier: Active notifier instance (typically *shoutrrrTypeNotifier).

func GetDelay deprecated 

func GetDelay(log *zerolog.Logger, delaySeconds int, legacyDelay time.Duration) time.Duration

GetDelay selects the notification delay from a legacy value or configured seconds.

Parameters:

  • log: Logger for diagnostics.
  • delaySeconds: Configured delay in seconds (from Config.Notify.DelaySeconds).
  • legacyDelay: Delay from a legacy notifier type, preferred when non-zero.

Returns:

  • time.Duration: Selected delay (legacy delay if set, otherwise delaySeconds, otherwise zero).

Deprecated: Prefer NewNotifier with Config.Notify from config.Load.

TODO: Simplify GetDelay to only use configured delay seconds when legacy types are removed.

func GetScheme 

func GetScheme(url string) string

GetScheme extracts the scheme from a Shoutrrr URL.

Parameters:

  • url: URL to parse.

Returns:

  • string: Scheme or "invalid" if none found.

func GetTitle 

func GetTitle(log *zerolog.Logger, hostname, tag string) string

GetTitle formats the notification title with hostname and tag.

Parameters:

  • log: Logger for diagnostics.
  • hostname: Hostname to include.
  • tag: Optional tag prefix.

Returns:

  • string: Formatted title.

func LogLegacyDeprecationWarnings 

func LogLegacyDeprecationWarnings(log *zerolog.Logger, notificationTypes []string)

LogLegacyDeprecationWarnings logs deprecation warnings for legacy notification types.

It iterates over the provided notification types and logs a warning for each legacy type, advising users to migrate to the notification-url configuration option.

Parameters:

  • log: Logger for warnings.
  • notificationTypes: List of notification type strings to check.

func NewNotifier 

func NewNotifier(log *zerolog.Logger, cfg notifyConfig.Notify) types.Notifier

NewNotifier constructs the notification client from resolved process settings.

It parses the notification log level, loads an optional template file, builds static template data, appends legacy Shoutrrr URLs when configured, and creates the client.

Parameters:

  • log: Process logger for configuration-time diagnostics (required and non-nil).
  • cfg: Notification settings from config.Load (Config.Notify).

Returns:

  • types.Notifier: Configured notifier instance.

func NewNotifierFromFlags 

func NewNotifierFromFlags(log *zerolog.Logger, c *cobra.Command) types.Notifier

NewNotifierFromFlags creates a notification client from Cobra flags.

Prefer config.Load plus NewNotifier in production. This entry point is for tests that configure notifications via flags only.

Parameters:

  • log: Process logger for configuration-time diagnostics.
  • c: Cobra command with flags.

Returns:

  • types.Notifier: Configured notification client.

func ToPorcelainJSON 

func ToPorcelainJSON(sourceReport types.Report) string

ToPorcelainJSON marshals a types.Report to an indented JSON string for templates.

Parameters:

  • sourceReport: Source report.

Returns:

  • string: Indented JSON or error string if marshaling fails.

Types

type Data 

type Data struct {
	StaticData

	Entries []*notificationEntry
	Report  types.Report
}

Data is the notification template data model.

func (Data) MarshalJSON 

func (d Data) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for Data.

Returns:

  • []byte: JSON-encoded data.
  • error: Non-nil if marshaling fails, nil on success.

type PorcelainContainer 

type PorcelainContainer struct {
	Name            string `json:"name"`
	Image           string `json:"image"`
	ImageID         string `json:"image_id"`
	LatestImageID   string `json:"latest_image_id"`
	State           string `json:"state"`
	UpdateAvailable bool   `json:"update_available"`
	Error           string `json:"error,omitempty"`
}

PorcelainContainer represents a single container in the porcelain JSON report.

type PorcelainReport 

type PorcelainReport struct {
	Containers []PorcelainContainer `json:"containers"`
}

PorcelainReport is the top-level JSON structure for --porcelain json.

func ToPorcelainReport 

func ToPorcelainReport(sourceReport types.Report) PorcelainReport

ToPorcelainReport converts a types.Report into a PorcelainReport.

Parameters:

  • sourceReport: Source report.

Returns:

  • PorcelainReport: JSON-ready report.

type StaticData 

type StaticData struct {
	Title string
	Host  string
}

StaticData is the part of the notification template data model set upon initialization.

func GetTemplateData deprecated 

func GetTemplateData(log *zerolog.Logger, c *cobra.Command) StaticData

GetTemplateData populates static notification data from Cobra flags.

Prefer config.Load plus NewNotifier in production. This helper remains for tests and deprecated call paths that still configure notifications via flags.

Parameters:

  • log: Logger for diagnostics.
  • c: Cobra command with flags.

Returns:

  • StaticData: Populated data (hostname from flag or system, title unless skip-title).

Deprecated: Prefer NewNotifier with Config.Notify from config.Load.

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.