notify

package
v0.15.1 Latest Latest
Warning

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

 Go to latest Published: Feb 27, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package notify provides notification services for backup operations. It supports multiple notification channels (Telegram, Email) with configurable delivery methods and comprehensive error handling.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultCloudRelayConfig = CloudRelayConfig{
	WorkerURL:   "https://relay-tis24.weathered-hill-5216.workers.dev/send",
	WorkerToken: "v1_public_20251024",
	HMACSecret:  "4cc8946c15338082674d7213aee19069571e1afe60ad21b44be4d68260486fb2",
	Timeout:     30,
	MaxRetries:  2,
	RetryDelay:  2,
}

Default cloud relay configuration (hardcoded for compatibility with Bash script)

Functions

func BuildEmailHTML 

func BuildEmailHTML(data *NotificationData) string

BuildEmailHTML builds an HTML email body matching Bash template exactly

func BuildEmailPlainText 

func BuildEmailPlainText(data *NotificationData) string

BuildEmailPlainText builds a plain text email body

func BuildEmailSubject 

func BuildEmailSubject(data *NotificationData) string

BuildEmailSubject builds the email subject line matching Bash output

func FormatDuration 

func FormatDuration(d time.Duration) string

FormatDuration formats a duration in human-readable format (e.g., "2h 15m 30s")

func GetStatusEmoji 

func GetStatusEmoji(status NotificationStatus) string

GetStatusEmoji returns the emoji for a given status

func GetStorageEmoji 

func GetStorageEmoji(status string) string

GetStorageEmoji returns the emoji for a storage status string

Types

type CloudRelayConfig 

type CloudRelayConfig struct {
	WorkerURL   string
	WorkerToken string
	HMACSecret  string
	Timeout     int // seconds
	MaxRetries  int
	RetryDelay  int // seconds
}

CloudRelayConfig holds configuration for email cloud relay

type EmailConfig 

type EmailConfig struct {
	Enabled          bool
	DeliveryMethod   EmailDeliveryMethod
	FallbackSendmail bool
	AttachLogFile    bool
	SubjectOverride  string
	Recipient        string // Empty = auto-detect
	From             string
	CloudRelayConfig CloudRelayConfig
}

EmailConfig holds email notification configuration

type EmailDeliveryMethod 

type EmailDeliveryMethod string

EmailDeliveryMethod represents the email delivery method 

const (
	EmailDeliveryRelay    EmailDeliveryMethod = "relay"
	EmailDeliverySendmail EmailDeliveryMethod = "sendmail"
	EmailDeliveryPMF      EmailDeliveryMethod = "pmf"
)

type EmailNotifier 

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

EmailNotifier implements the Notifier interface for Email

func NewEmailNotifier 

func NewEmailNotifier(config EmailConfig, proxmoxType types.ProxmoxType, logger *logging.Logger) (*EmailNotifier, error)

NewEmailNotifier creates a new Email notifier

func (*EmailNotifier) IsCritical 

func (e *EmailNotifier) IsCritical() bool

IsCritical returns whether email failures should abort backup (always false)

func (*EmailNotifier) IsEnabled 

func (e *EmailNotifier) IsEnabled() bool

IsEnabled returns whether email notifications are enabled

func (*EmailNotifier) Name 

func (e *EmailNotifier) Name() string

Name returns the notifier name

func (*EmailNotifier) Send 

func (e *EmailNotifier) Send(ctx context.Context, data *NotificationData) (*NotificationResult, error)

Send sends an email notification

type EmailRelayPayload 

type EmailRelayPayload struct {
	To        string                 `json:"to"`
	Subject   string                 `json:"subject"`
	Report    map[string]interface{} `json:"report"`
	Timestamp int64                  `json:"t"`
	ServerMAC string                 `json:"server_mac"`

	// Metadata not serialized but needed for headers
	ScriptVersion string `json:"-"`
	ServerID      string `json:"-"`
}

EmailRelayPayload represents the JSON payload sent to the cloud worker

type EmailRelayResponse 

type EmailRelayResponse struct {
	Success bool   `json:"success"`
	Message string `json:"message,omitempty"`
	Error   string `json:"error,omitempty"`
}

EmailRelayResponse represents the response from the cloud worker

type GotifyConfig 

type GotifyConfig struct {
	Enabled         bool
	ServerURL       string
	Token           string
	PrioritySuccess int
	PriorityWarning int
	PriorityFailure int
}

GotifyConfig holds configuration for Gotify notifications.

type GotifyNotifier 

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

GotifyNotifier implements the Notifier interface for Gotify.

func NewGotifyNotifier 

func NewGotifyNotifier(cfg GotifyConfig, logger *logging.Logger) (*GotifyNotifier, error)

NewGotifyNotifier creates a new Gotify notifier.

func (*GotifyNotifier) IsCritical 

func (g *GotifyNotifier) IsCritical() bool

IsCritical returns whether failures should abort the backup (never for notifications).

func (*GotifyNotifier) IsEnabled 

func (g *GotifyNotifier) IsEnabled() bool

IsEnabled returns whether the notifier is enabled.

func (*GotifyNotifier) Name 

func (g *GotifyNotifier) Name() string

Name returns the notifier name.

func (*GotifyNotifier) Send 

func (g *GotifyNotifier) Send(ctx context.Context, data *NotificationData) (*NotificationResult, error)

Send sends a notification to Gotify.

type LogCategory 

type LogCategory struct {
	Label   string `json:"label"`
	Type    string `json:"type"` // ERROR/WARNING
	Count   int    `json:"count"`
	Example string `json:"example,omitempty"`
}

LogCategory represents a normalized log issue classification.

type NotificationData 

type NotificationData struct {
	// Overall status
	Status        NotificationStatus
	StatusMessage string
	ExitCode      int

	// System information
	Hostname    string
	ProxmoxType types.ProxmoxType // PVE or PBS
	ServerID    string            // Server identifier
	ServerMAC   string            // MAC address for rate limiting

	// Backup metadata
	BackupDate     time.Time
	BackupDuration time.Duration
	BackupFile     string // Full path to backup file
	BackupFileName string // Just the filename (for email display)
	BackupSize     int64  // bytes
	BackupSizeHR   string // human-readable

	// Compression info
	CompressionType  string
	CompressionLevel int
	CompressionMode  string
	CompressionRatio float64

	// File counts
	FilesIncluded int
	FilesMissing  int

	// Storage status
	LocalStatus        string
	LocalStatusSummary string
	LocalCount         int
	LocalFree          string
	LocalUsed          string
	LocalPercent       string
	LocalSpaceBytes    uint64
	LocalUsagePercent  float64

	// Local retention info
	LocalRetentionPolicy   string // "simple" or "gfs"
	LocalRetentionLimit    int    // MAX_LOCAL_BACKUPS (simple mode)
	LocalGFSDaily          int    // GFS limits
	LocalGFSWeekly         int
	LocalGFSMonthly        int
	LocalGFSYearly         int
	LocalGFSCurrentDaily   int // GFS current counts
	LocalGFSCurrentWeekly  int
	LocalGFSCurrentMonthly int
	LocalGFSCurrentYearly  int
	LocalBackups           int // Total current backups

	SecondaryEnabled       bool
	SecondaryStatus        string
	SecondaryStatusSummary string
	SecondaryCount         int
	SecondaryFree          string
	SecondaryUsed          string
	SecondaryPercent       string
	SecondarySpaceBytes    uint64
	SecondaryUsagePercent  float64

	// Secondary retention info
	SecondaryRetentionPolicy   string
	SecondaryRetentionLimit    int
	SecondaryGFSDaily          int
	SecondaryGFSWeekly         int
	SecondaryGFSMonthly        int
	SecondaryGFSYearly         int
	SecondaryGFSCurrentDaily   int
	SecondaryGFSCurrentWeekly  int
	SecondaryGFSCurrentMonthly int
	SecondaryGFSCurrentYearly  int
	SecondaryBackups           int

	CloudEnabled       bool
	CloudStatus        string
	CloudStatusSummary string
	CloudCount         int

	// Cloud retention info
	CloudRetentionPolicy   string
	CloudRetentionLimit    int
	CloudGFSDaily          int
	CloudGFSWeekly         int
	CloudGFSMonthly        int
	CloudGFSYearly         int
	CloudGFSCurrentDaily   int
	CloudGFSCurrentWeekly  int
	CloudGFSCurrentMonthly int
	CloudGFSCurrentYearly  int
	CloudBackups           int

	// Email notification status (for Telegram messages)
	EmailStatus    string
	TelegramStatus string

	// Paths
	LocalPath     string
	SecondaryPath string
	CloudPath     string

	// Error/Warning summary
	ErrorCount    int
	WarningCount  int
	LogFilePath   string
	TotalIssues   int
	LogCategories []LogCategory

	// Script metadata
	ScriptVersion string

	// Version update information
	NewVersionAvailable bool
	CurrentVersion      string
	LatestVersion       string
}

NotificationData contains all information to be sent in notifications

type NotificationResult 

type NotificationResult struct {
	Success      bool
	UsedFallback bool   // True if fallback method was used after primary failed
	Method       string // "telegram", "email-relay", "email-sendmail"
	Error        error  // Original error (even if fallback succeeded)
	Duration     time.Duration
	Metadata     map[string]interface{} // Additional info (HTTP status, etc.)
}

NotificationResult represents the result of a notification attempt

type NotificationStatus 

type NotificationStatus int

NotificationStatus represents the overall status of a backup operation 

const (
	StatusSuccess NotificationStatus = iota
	StatusWarning
	StatusFailure
)

func StatusFromExitCode 

func StatusFromExitCode(exitCode int) NotificationStatus

StatusFromExitCode maps a process exit code to a notification status. This allows logs and notifications (email subject emoji, Telegram, etc.) to stay in sync with the actual exit code emitted by the process.

func (NotificationStatus) String 

func (s NotificationStatus) String() string

String returns the string representation of NotificationStatus

type Notifier 

type Notifier interface {
	// Name returns the notifier name (e.g., "Telegram", "Email")
	Name() string

	// IsEnabled returns whether this notifier is enabled
	IsEnabled() bool

	// Send sends a notification with the provided data
	// Returns error only for critical failures; non-critical errors are logged
	Send(ctx context.Context, data *NotificationData) (*NotificationResult, error)

	// IsCritical returns whether failures from this notifier should abort the backup
	// In practice, all notifiers should return false (notifications never abort backup)
	IsCritical() bool
}

Notifier is the interface that must be implemented by all notification providers

type StorageStatus 

type StorageStatus struct {
	Enabled        bool
	Status         string // "ok", "warning", "error", "disabled"
	BackupCount    int
	FreeSpace      string // human-readable
	FreeSpaceBytes uint64
	UsagePercent   float64
}

StorageStatus represents the status of a storage location

type TelegramConfig 

type TelegramConfig struct {
	Enabled       bool
	Mode          TelegramMode
	BotToken      string
	ChatID        string
	ServerAPIHost string // For centralized mode
	ServerID      string // Server identifier for centralized mode
}

TelegramConfig holds Telegram notification configuration

type TelegramMode 

type TelegramMode string

TelegramMode represents the Telegram bot configuration mode 

const (
	TelegramModePersonal    TelegramMode = "personal"
	TelegramModeCentralized TelegramMode = "centralized"
)

type TelegramNotifier 

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

TelegramNotifier implements the Notifier interface for Telegram

func NewTelegramNotifier 

func NewTelegramNotifier(config TelegramConfig, logger *logging.Logger) (*TelegramNotifier, error)

NewTelegramNotifier creates a new Telegram notifier

func (*TelegramNotifier) IsCritical 

func (t *TelegramNotifier) IsCritical() bool

IsCritical returns whether Telegram failures should abort backup (always false)

func (*TelegramNotifier) IsEnabled 

func (t *TelegramNotifier) IsEnabled() bool

IsEnabled returns whether Telegram notifications are enabled

func (*TelegramNotifier) Name 

func (t *TelegramNotifier) Name() string

Name returns the notifier name

func (*TelegramNotifier) Send 

func (t *TelegramNotifier) Send(ctx context.Context, data *NotificationData) (*NotificationResult, error)

Send sends a Telegram notification

type TelegramRegistrationStatus 

type TelegramRegistrationStatus struct {
	Code    int
	Message string
	Error   error
}

TelegramRegistrationStatus represents the result of the handshake with the centralized Telegram server.

func CheckTelegramRegistration 

func CheckTelegramRegistration(ctx context.Context, serverAPIHost, serverID string, logger *logging.Logger) TelegramRegistrationStatus

CheckTelegramRegistration checks the registration status on the centralized server.

type WebhookNotifier 

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

WebhookNotifier sends notifications to configured webhook endpoints

func NewWebhookNotifier 

func NewWebhookNotifier(webhookConfig *config.WebhookConfig, logger *logging.Logger) (*WebhookNotifier, error)

NewWebhookNotifier creates a new webhook notifier

func (*WebhookNotifier) IsCritical 

func (w *WebhookNotifier) IsCritical() bool

IsCritical returns false - webhook failures should not abort backup

func (*WebhookNotifier) IsEnabled 

func (w *WebhookNotifier) IsEnabled() bool

IsEnabled returns whether webhook notifications are enabled

func (*WebhookNotifier) Name 

func (w *WebhookNotifier) Name() string

Name returns the notifier name

func (*WebhookNotifier) Send 

func (w *WebhookNotifier) Send(ctx context.Context, data *NotificationData) (*NotificationResult, error)

Send sends notifications to all configured webhook endpoints

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.