feat(alerting): Add basic send mode implementation

Author: PythonGermany

alerting/alert/type.go

@@ -110,6 +110,9 @@ const (
 	// TypeTelegram is the Type for the telegram alerting provider
 	TypeTelegram Type = "telegram"
 
+	// TypeThreemaGateway is the Type for the threema-gateway alerting provider
+	TypeThreemaGateway Type = "threema-gateway"
+
 	// TypeTwilio is the Type for the twilio alerting provider
 	TypeTwilio Type = "twilio"
 

alerting/config.go

@@ -41,6 +41,7 @@ import (
 	"github.com/TwiN/gatus/v5/alerting/provider/teams"
 	"github.com/TwiN/gatus/v5/alerting/provider/teamsworkflows"
 	"github.com/TwiN/gatus/v5/alerting/provider/telegram"
+	"github.com/TwiN/gatus/v5/alerting/provider/threemagateway"
 	"github.com/TwiN/gatus/v5/alerting/provider/twilio"
 	"github.com/TwiN/gatus/v5/alerting/provider/vonage"
 	"github.com/TwiN/gatus/v5/alerting/provider/webex"
@@ -156,6 +157,9 @@ type Config struct {
 	// Telegram is the configuration for the telegram alerting provider
 	Telegram *telegram.AlertProvider `yaml:"telegram,omitempty"`
 
+	// ThreemaGateway is the configuration for the threema-gatway alerting provider
+	ThreemaGateway *threemagateway.AlertProvider `yaml:"threema-gateway,omitempty"`
+
 	// Twilio is the configuration for the twilio alerting provider
 	Twilio *twilio.AlertProvider `yaml:"twilio,omitempty"`
 

alerting/provider/provider.go

@@ -37,6 +37,7 @@ import (
 	"github.com/TwiN/gatus/v5/alerting/provider/teams"
 	"github.com/TwiN/gatus/v5/alerting/provider/teamsworkflows"
 	"github.com/TwiN/gatus/v5/alerting/provider/telegram"
+	"github.com/TwiN/gatus/v5/alerting/provider/threemagateway"
 	"github.com/TwiN/gatus/v5/alerting/provider/twilio"
 	"github.com/TwiN/gatus/v5/alerting/provider/webex"
 	"github.com/TwiN/gatus/v5/alerting/provider/zapier"
@@ -126,6 +127,7 @@ var (
 	_ AlertProvider = (*teams.AlertProvider)(nil)
 	_ AlertProvider = (*teamsworkflows.AlertProvider)(nil)
 	_ AlertProvider = (*telegram.AlertProvider)(nil)
+	_ AlertProvider = (*threemagateway.AlertProvider)(nil)
 	_ AlertProvider = (*twilio.AlertProvider)(nil)
 	_ AlertProvider = (*webex.AlertProvider)(nil)
 	_ AlertProvider = (*zapier.AlertProvider)(nil)
@@ -167,6 +169,7 @@ var (
 	_ Config[teams.Config]          = (*teams.Config)(nil)
 	_ Config[teamsworkflows.Config] = (*teamsworkflows.Config)(nil)
 	_ Config[telegram.Config]       = (*telegram.Config)(nil)
+	_ Config[threemagateway.Config] = (*threemagateway.Config)(nil)
 	_ Config[twilio.Config]         = (*twilio.Config)(nil)
 	_ Config[webex.Config]          = (*webex.Config)(nil)
 	_ Config[zapier.Config]         = (*zapier.Config)(nil)

alerting/provider/threemagateway/threemagateway.go

@@ -0,0 +1,335 @@
+package threemagateway
+
+import (
+	"errors"
+	"fmt"
+	"maps"
+	"net/http"
+	"net/url"
+	"slices"
+	"strings"
+
+	"github.com/TwiN/gatus/v5/alerting/alert"
+	"github.com/TwiN/gatus/v5/client"
+	"github.com/TwiN/gatus/v5/config/endpoint"
+	"gopkg.in/yaml.v3"
+)
+
+// TODO#1464: Add tests
+
+const (
+	defaultApiUrl = "https://msgapi.threema.ch"
+	defaultMode   = "basic"
+)
+
+var (
+	ErrModeInvalid        = fmt.Errorf("invalid mode, must be one of: %s", joinKeys(modes, ", "))
+	ErrNotImplementedMode = errors.New("the specified mode is not implemented yet")
+	modes                 = map[string]Mode{
+		"basic":     ModeBasic,
+		"e2ee":      ModeE2EE,
+		"e2ee-bulk": ModeE2EEBulk,
+	}
+
+	ErrInvalidRecipientType = fmt.Errorf("invalid recipient type, must be one of: %v", joinKeys(recipientTypes, ", "))
+	recipientTypes          = map[string]RecipientType{
+		"id":    RecipientTypeID,
+		"phone": RecipientTypePhone,
+		"email": RecipientTypeEmail,
+	}
+
+	ErrApiKeyMissing = errors.New("auth-secret is required")
+)
+
+func joinKeys[V any](m map[string]V, separator string) string {
+	return strings.Join(slices.Collect(maps.Keys(m)), separator)
+}
+
+type Mode int // TODO#1464: Maybe move to separate file in package to keep things organized
+
+const (
+	ModeInvalid Mode = iota
+	ModeBasic
+	ModeE2EE
+	ModeE2EEBulk
+)
+
+func parseMode(s string) Mode {
+	if val, ok := modes[s]; ok {
+		return val
+	}
+	return ModeInvalid
+}
+
+type RecipientType int // TODO#1464: Maybe move to separate file in package to keep things organized
+
+const (
+	RecipientTypeInvalid RecipientType = iota
+	RecipientTypeID
+	RecipientTypePhone
+	RecipientTypeEmail
+)
+
+type Config struct {
+	ApiUrl        string `yaml:"api-url"`
+	Mode          string `yaml:"mode"`
+	ApiIdentity   string `yaml:"api-identity"`
+	Recipient     string `yaml:"recipient"`
+	ApiAuthSecret string `yaml:"auth-secret"`
+
+	sendMode        Mode          `yaml:"-"`
+	recipientType   RecipientType `yaml:"-"`
+	parsedRecipient string        `yaml:"-"`
+}
+
+func parseRecipientType(s string) RecipientType {
+	if val, ok := recipientTypes[s]; ok {
+		return val
+	}
+	return RecipientTypeInvalid
+}
+
+func parseRecipient(s string) (RecipientType, string, error) {
+	parts := strings.SplitN(s, ":", 2)
+	if len(parts) != 2 {
+		return RecipientTypeInvalid, "", errors.New("recipient must be in the format '<type>:<value>'")
+	}
+	recipientType := parseRecipientType(parts[0])
+	if recipientType == RecipientTypeInvalid {
+		return RecipientTypeInvalid, "", ErrInvalidRecipientType
+	}
+	return recipientType, parts[1], nil
+}
+
+func validateRecipient(recipientType RecipientType, recipient string) error {
+	if len(recipient) == 0 {
+		return errors.New("recipient value cannot be empty")
+	}
+	switch recipientType {
+	case RecipientTypeID:
+		if len(recipient) != 8 {
+			return errors.New("recipient ID must be 8 characters long")
+		}
+	case RecipientTypePhone:
+		// Basic validation for phone number # TODO#1464: improve phone number validation
+		if !strings.HasPrefix(recipient, "+") || len(recipient) < 8 {
+			return errors.New("invalid phone number format")
+		}
+	case RecipientTypeEmail:
+		// Basic validation for email address // TODO#1464: improve email validation
+		if !strings.Contains(recipient, "@") {
+			return errors.New("invalid email address format")
+		}
+	default:
+		return ErrInvalidRecipientType
+	}
+	return nil
+}
+
+func (cfg *Config) Validate() error {
+	// Validate API URL
+	if len(cfg.ApiUrl) == 0 {
+		cfg.ApiUrl = defaultApiUrl
+	}
+
+	// Validate Mode
+	if len(cfg.Mode) == 0 {
+		cfg.Mode = defaultMode
+	}
+	cfg.sendMode = parseMode(cfg.Mode)
+	switch cfg.sendMode {
+	case ModeInvalid:
+		return ErrModeInvalid
+	case ModeE2EE, ModeE2EEBulk:
+		return ErrNotImplementedMode // TODO#1464: implement E2EE and E2EE-Bulk modes
+	}
+
+	// Validate Recipient
+	var err error
+	cfg.recipientType, cfg.parsedRecipient, err = parseRecipient(cfg.Recipient)
+	if err != nil {
+		return err
+	}
+	if err := validateRecipient(cfg.recipientType, cfg.parsedRecipient); err != nil {
+		return err
+	}
+
+	// Validate API Key
+	if len(cfg.ApiAuthSecret) == 0 {
+		return ErrApiKeyMissing
+	}
+	return nil
+}
+
+func (cfg *Config) Merge(override *Config) {
+	if len(override.ApiUrl) > 0 {
+		cfg.ApiUrl = override.ApiUrl
+	}
+	if len(override.Mode) > 0 {
+		cfg.Mode = override.Mode
+		cfg.sendMode = ModeInvalid
+	}
+	if len(override.ApiIdentity) > 0 {
+		cfg.ApiIdentity = override.ApiIdentity
+	}
+	if len(override.Recipient) > 0 {
+		cfg.Recipient = override.Recipient
+		cfg.recipientType = RecipientTypeInvalid
+	}
+	if len(override.ApiAuthSecret) > 0 {
+		cfg.ApiAuthSecret = override.ApiAuthSecret
+	}
+}
+
+type AlertProvider struct {
+	DefaultConfig Config       `yaml:",inline"`
+	DefaultAlert  *alert.Alert `yaml:"default-alert,omitempty"`
+	Overrides     []Override   `yaml:"overrides,omitempty"`
+}
+
+type Override struct {
+	Group  string `yaml:"group"`
+	Config `yaml:",inline"`
+}
+
+func (provider *AlertProvider) Validate() error {
+	return provider.DefaultConfig.Validate()
+}
+
+func (provider *AlertProvider) Send(ep *endpoint.Endpoint, alert *alert.Alert, result *endpoint.Result, resolved bool) error {
+	cfg, err := provider.GetConfig(ep.Group, alert)
+	if err != nil {
+		return err
+	}
+	body := provider.buildMessageBody(ep, alert, result, resolved)
+	request, err := provider.prepareRequest(cfg, body)
+	if err != nil {
+		return err
+	}
+	response, err := client.GetHTTPClient(nil).Do(request)
+	if err != nil {
+		return err
+	}
+	return handleResponse(cfg, response)
+}
+
+func (provider *AlertProvider) buildMessageBody(ep *endpoint.Endpoint, alert *alert.Alert, result *endpoint.Result, resolved bool) string {
+	var body string
+	if resolved {
+		body = fmt.Sprintf("✅ Alert resolved for endpoint '%s' after passing %d checks.", ep.Name, alert.SuccessThreshold)
+	} else {
+		body = fmt.Sprintf("🚨 Alert triggered for endpoint '%s' after failing %d checks.\n\nConditions:\n", ep.Name, alert.FailureThreshold)
+		for _, conditionResult := range result.ConditionResults {
+			var icon rune
+			if conditionResult.Success {
+				icon = '✓'
+			} else {
+				icon = '✗'
+			}
+			body += fmt.Sprintf("- %c %s\n", icon, conditionResult.Condition)
+		}
+		if len(result.Errors) > 0 {
+			body += "\nErrors:\n"
+			for _, err := range result.Errors {
+				body += fmt.Sprintf("- ✗ %s\n", err)
+			}
+		}
+	}
+	return body
+}
+
+func (provider *AlertProvider) prepareRequest(cfg *Config, body string) (*http.Request, error) {
+	requestUrl := cfg.ApiUrl
+	switch cfg.sendMode {
+	case ModeBasic:
+		requestUrl += "/send_simple"
+	case ModeE2EE, ModeE2EEBulk:
+		return nil, ErrNotImplementedMode // TODO#1464: implement E2EE and E2EE-Bulk modes
+	default:
+		return nil, ErrNotImplementedMode
+	}
+
+	data := url.Values{}
+	data.Add("from", cfg.ApiIdentity)
+	var toKey string
+	switch cfg.recipientType {
+	case RecipientTypeID:
+		toKey = "to"
+	case RecipientTypePhone:
+		toKey = "phone"
+	case RecipientTypeEmail:
+		toKey = "email"
+	default:
+		return nil, ErrInvalidRecipientType
+	}
+	data.Add(toKey, cfg.parsedRecipient)
+	data.Add("text", body)
+	data.Add("secret", cfg.ApiAuthSecret)
+
+	request, err := http.NewRequest(http.MethodPost, requestUrl, strings.NewReader(data.Encode()))
+	if err != nil {
+		return nil, err
+	}
+	request.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	return request, nil
+}
+
+func handleResponse(cfg *Config, response *http.Response) error {
+	switch response.StatusCode {
+	case http.StatusOK:
+		switch cfg.sendMode {
+		case ModeBasic, ModeE2EE:
+			return nil
+		case ModeE2EEBulk:
+			return nil // TODO#1464: Add correct handling once mode is implemented (check success fields in response body)
+		}
+	case http.StatusBadRequest:
+		switch cfg.sendMode {
+		case ModeBasic, ModeE2EE:
+			return fmt.Errorf("%s: Invalid recipient or Threema Account not set up for %s mode", response.Status, cfg.Mode)
+		case ModeE2EEBulk:
+			// TODO#1464: Add correct error info once mode is implemented
+		}
+	case http.StatusUnauthorized:
+		return fmt.Errorf("%s: Invalid auth-secret or api-identity", response.Status)
+	case http.StatusPaymentRequired:
+		return fmt.Errorf("%s: Insufficient credits to send message", response.Status)
+	case http.StatusNotFound:
+		if cfg.sendMode == ModeBasic {
+			return fmt.Errorf("%s: Recipient could not be found", response.Status)
+		}
+	}
+	return fmt.Errorf("Response: %s", response.Status)
+}
+
+func (provider *AlertProvider) GetDefaultAlert() *alert.Alert {
+	return provider.DefaultAlert
+}
+
+// GetConfig returns the configuration for the provider with the overrides applied
+func (provider *AlertProvider) GetConfig(group string, alert *alert.Alert) (*Config, error) {
+	cfg := provider.DefaultConfig
+	// Handle group overrides
+	if len(provider.Overrides) > 0 {
+		for _, override := range provider.Overrides {
+			if group == override.Group {
+				cfg.Merge(&override.Config)
+				break
+			}
+		}
+	}
+	// Handle alert overrides
+	if len(alert.ProviderOverride) > 0 {
+		overrideConfig := Config{}
+		if err := yaml.Unmarshal(alert.ProviderOverrideAsBytes(), &overrideConfig); err != nil {
+			return nil, err
+		}
+		cfg.Merge(&overrideConfig)
+	}
+	return &cfg, cfg.Validate()
+}
+
+func (provider *AlertProvider) ValidateOverrides(group string, alert *alert.Alert) error {
+	_, err := provider.GetConfig(group, alert)
+	return err
+}

alerting/provider/threemagateway/threemagateway_test.go

@@ -0,0 +1,3 @@
+package threemagateway
+
+// TODO#1468: Implement tests

config/config.go

@@ -628,6 +628,7 @@ func ValidateAlertingConfig(alertingConfig *alerting.Config, endpoints []*endpoi
 		alert.TypeTeams,
 		alert.TypeTeamsWorkflows,
 		alert.TypeTelegram,
+		alert.TypeThreemaGateway,
 		alert.TypeTwilio,
 		alert.TypeVonage,
 		alert.TypeWebex,