Debian Codegraph @

pkg/services/standard/doc.go

raw
1 // Package standard provides standard implementations for core Shoutrrr service functionality.
2 //
3 // The standard package offers reusable components that notification services can embed
4 // to implement common functionality required by the Shoutrrr framework. Rather than
5 // implementing logging, templating, and error handling from scratch, services can embed
6 // the Standard type to get these capabilities out of the box.
7 //
8 // # Overview
9 //
10 // The package provides three main components:
11 //
12 // - Standard: A composable type that embeds Logger and Templater
13 // - Logger: Standard logging implementation for services
14 // - Templater: Template management using Go's text/template package
15 //
16 // In addition, the package provides utility types and functions for error handling
17 // and configuration management that are commonly needed across different services.
18 //
19 // # Usage
20 //
21 // Services typically embed standard.Standard in their Service struct:
22 //
23 // type Service struct {
24 // standard.Standard
25 // // service-specific fields
26 // }
27 //
28 // This gives the Service access to all logging and templating methods through
29 // composition. The Standard type implements the types.StdLogger and types.Templater
30 // interfaces required by the shoutrrr.Service interface.
31 //
32 // # Key Types
33 //
34 // ## Standard
35 //
36 // The Standard type embeds both Logger and Templater, providing a convenient way
37 // to include all standard functionality in a single embed:
38 //
39 // var service Service
40 // service.Standard = standard.Standard{}
41 // service.SetLogger(logger)
42 // service.Log("Service initialized")
43 //
44 // ## Logger
45 //
46 // Logger provides methods for outputting non-fatal log information. It wraps the
47 // types.StdLogger interface and provides Log and Logf methods:
48 //
49 // logger := &standard.Logger{}
50 // logger.SetLogger(myLogger)
51 // logger.Log("Message without formatting")
52 // logger.Logf("Formatted message: %s", argument)
53 //
54 // When SetLogger is called with nil, a discard logger is used to prevent nil
55 // pointer dereferences.
56 //
57 // ## Templater
58 //
59 // Templater provides template management using Go's text/template package. Services
60 // can use it to store and retrieve templates by ID:
61 //
62 // templater := &standard.Templater{}
63 // templater.SetTemplateString("welcome", "Hello, {{.Name}}!")
64 //
65 // tpl, found := templater.GetTemplate("welcome")
66 // if found {
67 // // Use tpl.Execute() to render the template
68 // }
69 //
70 // Templates can be loaded from strings or files:
71 //
72 // err := templater.SetTemplateString("my-template", "Template content")
73 // err := templater.SetTemplateFile("my-template", "/path/to/template.txt")
74 //
75 // # Error Handling
76 //
77 // The package provides failure types and helper functions for common error scenarios:
78 //
79 // const (
80 // FailTestSetup failures.FailureID = -1 // Test setup errors
81 // FailParseURL failures.FailureID = -2 // URL parsing errors
82 // FailServiceInit failures.FailureID = -3 // Service initialization errors
83 // FailUnknown failures.FailureID = 0 // Default/unknown errors
84 // )
85 //
86 // The Failure function creates a Failure instance with a specific failure ID:
87 //
88 // fail := standard.Failure(standard.FailParseURL, err, "invalid URL format")
89 //
90 // The IsTestSetupFailure helper checks if a failure is due to test setup issues:
91 //
92 // if msg, isSetupFailure := standard.IsTestSetupFailure(fail); isSetupFailure {
93 // // Handle test setup failure
94 // }
95 //
96 // # Configuration
97 //
98 // EnumlessConfig provides a minimal implementation of types.ServiceConfig for
99 // services that don't use enumerated configuration fields:
100 //
101 // type Config struct {
102 // standard.EnumlessConfig
103 // // service-specific config fields
104 // }
105 //
106 // func (c *Config) Enums() map[string]types.EnumFormatter {
107 // return map[string]types.EnumFormatter{} // Empty - no enum fields
108 // }
109 //
110 // # Examples
111 //
112 // ## Basic Service Setup
113 //
114 // func NewService() *Service {
115 // return &Service{
116 // Standard: standard.Standard{},
117 // }
118 // }
119 //
120 // func (s *Service) Initialize(serviceURL *url.URL, logger types.StdLogger) error {
121 // s.SetLogger(logger)
122 // s.Log("Initializing service")
123 // // service-specific initialization
124 // return nil
125 // }
126 //
127 // ## Using Templates
128 //
129 // func (s *Service) Send(ctx context.Context, params *types.Params) error {
130 // // Load template if not already present
131 // if _, found := s.GetTemplate("message"); !found {
132 // s.SetTemplateString("message", "Title: {{.Title}}\n{{.Body}}")
133 // }
134 //
135 // // Render template
136 // tpl, _ := s.GetTemplate("message")
137 // var buf bytes.Buffer
138 // if err := tpl.Execute(&buf, params); err != nil {
139 // return standard.Failure(standard.FailUnknown, err)
140 // }
141 //
142 // return s.sendToProvider(buf.String())
143 // }
144 //
145 // ## Error Handling
146 //
147 // func (s *Service) parseURL(rawURL string) (*url.URL, error) {
148 // parsed, err := url.Parse(rawURL)
149 // if err != nil {
150 // return nil, standard.Failure(standard.FailParseURL, err)
151 // }
152 //
153 // if parsed.Host == "" {
154 // return nil, standard.Failure(standard.FailParseURL, errors.New("empty host"))
155 // }
156 //
157 // return parsed, nil
158 // }
159 //
160 // # Integration with Services
161 //
162 // The standard package is designed to be embedded by notification service implementations.
163 // All built-in Shoutrrr services use this pattern:
164 //
165 // - Chat services: Discord, Slack, Mattermost, Telegram, Teams, etc.
166 // - Push services: Gotify, ntfy, Pushover, Pushbullet, etc.
167 // - Email services: SMTP
168 // - Incident services: PagerDuty, OpsGenie
169 // - Specialized services: Generic, Logger, Notifiarr
170 //
171 // By embedding standard.Standard, services automatically get:
172 //
173 // - Logging via Log() and Logf() methods
174 // - Template management via GetTemplate(), SetTemplateString(), SetTemplateFile()
175 // - Integration with shoutrrr's service discovery and URL parsing
176 //
177 // This approach promotes code reuse and consistency across different notification
178 // service implementations while allowing each service to focus on its specific
179 // provider integration.
180 package standard