Debian Codegraph @

pkg/services/push/gotify/doc.go

raw
1 // Package gotify provides a notification service for sending push notifications via Gotify servers.
2 //
3 // The Gotify service allows sending push notifications to Gotify servers, which can be received
4 // by mobile apps, web browsers, and other clients. Gotify is a self-hosted notification service
5 // that provides a simple REST API for sending messages with titles, priorities, and custom extras.
6 // It supports both token-based authentication in query parameters or HTTP headers, and offers
7 // flexible configuration for secure and reliable message delivery.
8 //
9 // # URL Format
10 //
11 // The service URL follows the format:
12 //
13 // gotify://host[:port][/path]/token[?query]
14 //
15 // Where:
16 // - host: Gotify server hostname (required)
17 // - port: optional port number (default: 443 for HTTPS, 80 for HTTP)
18 // - path: optional subpath for Gotify installation (e.g., "/gotify")
19 // - token: application token for authentication (required, must be 15 characters starting with 'A')
20 // - query: configuration parameters
21 //
22 // # Configuration Options
23 //
24 // The following query parameters can be used to configure the service:
25 //
26 // - title: notification title (default: "Shoutrrr notification")
27 // - priority: message priority (-2 to 10, where higher numbers indicate higher priority; negative values have special meanings in some clients)
28 // - disabletls: set to "yes" to disable TLS (use HTTP instead of HTTPS)
29 // - insecureskipverify: set to "yes" to skip TLS certificate verification (insecure, use with caution)
30 // - useheader: set to "yes" to send token in X-Gotify-Key header instead of URL query parameter
31 // - date: optional custom timestamp in ISO 8601 format for the notification (accepts multiple input formats and converts to RFC3339)
32 // - extras: JSON string containing additional key-value pairs to include in the notification
33 //
34 // # Templates
35 //
36 // Gotify does not use templates in the Shoutrrr sense, but supports rich message formatting
37 // through its native features like titles, priorities, and custom extras fields that can
38 // contain structured data for enhanced client-side processing.
39 //
40 // # Usage Examples
41 //
42 // ## Basic notification
43 //
44 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd"
45 // err := shoutrrr.Send(url, "Hello from Shoutrrr!")
46 //
47 // ## Notification with custom title and high priority
48 //
49 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?title=Alert&priority=1"
50 // err := shoutrrr.Send(url, "System is down!")
51 //
52 // ## Notification with extras
53 //
54 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?title=Backup&extras=%7B%22action%22%3A%22view%22%2C%22url%22%3A%22https%3A%2F%2Fexample.com%2Flogs%22%7D"
55 // err := shoutrrr.Send(url, "Backup completed successfully")
56 //
57 // ## Notification with header authentication
58 //
59 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?useheader=yes"
60 // err := shoutrrr.Send(url, "Authenticated notification")
61 //
62 // ## Notification with disabled TLS (insecure)
63 //
64 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?disabletls=yes"
65 // err := shoutrrr.Send(url, "Insecure notification")
66 //
67 // ## Notification with custom path
68 //
69 // url := "gotify://gotify.example.com/gotify/Aaa.bbb.ccc.ddd"
70 // err := shoutrrr.Send(url, "Notification to subpath installation")
71 //
72 // ## Notification with custom timestamp
73 //
74 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?date=2023-12-25T10:30:00Z"
75 // err := shoutrrr.Send(url, "Scheduled notification")
76 //
77 // # Common Use Cases
78 //
79 // ## System Monitoring Alerts
80 //
81 // Send alerts from monitoring systems like Nagios, Prometheus, or Zabbix:
82 //
83 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?title=Alert&priority=1"
84 // err := shoutrrr.Send(url, "Disk space critical: 95% used")
85 //
86 // ## CI/CD Pipeline Notifications
87 //
88 // Notify about build status from Jenkins, GitHub Actions, or GitLab CI:
89 //
90 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?title=Build%20Failed&priority=0"
91 // err := shoutrrr.Send(url, "Build #123 failed on main branch")
92 //
93 // ## Home Automation
94 //
95 // Integrate with home automation systems like Home Assistant:
96 //
97 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?title=Security&priority=1&extras=%7B%22sensor%22%3A%22motion%22%2C%22location%22%3A%22front-door%22%7D"
98 // err := shoutrrr.Send(url, "Motion detected at front door")
99 //
100 // ## Backup Completion Notifications
101 //
102 // Notify when backups complete:
103 //
104 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?title=Backup&extras=%7B%22type%22%3A%22daily%22%2C%22size%22%3A%225GB%22%7D"
105 // err := shoutrrr.Send(url, "Daily backup finished successfully")
106 //
107 // ## Application Health Monitoring
108 //
109 // Send health check notifications from applications:
110 //
111 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?title=Health%20Check&priority=-1"
112 // err := shoutrrr.Send(url, "All services are healthy")
113 //
114 // ## Incident Response
115 //
116 // Send urgent notifications for incident response:
117 //
118 // url := "gotify://gotify.example.com/Aaa.bbb.ccc.ddd?title=INCIDENT&priority=1&extras=%7B%22severity%22%3A%22critical%22%2C%22team%22%3A%22ops%22%7D"
119 // err := shoutrrr.Send(url, "Database connection lost - immediate attention required")
120 //
121 // # Error Handling
122 //
123 // The service returns errors for various failure scenarios. Always check the returned error:
124 //
125 // err := shoutrrr.Send(url, message)
126 // if err != nil {
127 // log.Printf("Failed to send Gotify notification: %v", err)
128 // }
129 //
130 // Common error scenarios:
131 // - Invalid token format (must be 15 characters starting with 'A', valid characters only)
132 // - Empty message content
133 // - Network connectivity issues
134 // - Invalid server hostname or port
135 // - TLS certificate verification failures (when TLS is enabled)
136 // - HTTP error status codes (4xx/5xx) from the Gotify server
137 // - Invalid JSON in extras parameter
138 // - Authentication failures (invalid or expired token)
139 //
140 // # Security Considerations
141 //
142 // - Use HTTPS whenever possible (default behavior) to protect notification content in transit
143 // - Store application tokens securely - avoid hardcoding them in source code or configuration files
144 // - Use header-based authentication (useheader=yes) to avoid exposing tokens in server logs
145 // - Consider token entropy - Gotify tokens are application-specific and should be treated as secrets
146 // - Be cautious with disabletls=yes - only use in trusted environments as it disables TLS (uses HTTP)
147 // - Be cautious with insecureskipverify=yes - only use in trusted environments as it disables certificate verification
148 // - Validate extras JSON content to prevent injection of malicious data
149 // - Use appropriate priority levels - high priority notifications should be reserved for critical events
150 // - Consider message content - avoid sending sensitive information in notification messages
151 // - Implement proper access controls on your Gotify server to prevent unauthorized token usage
152 //
153 // # Limitations and Behaviors
154 //
155 // - Application tokens must be exactly 15 characters long and start with 'A'
156 // - Valid token characters are: a-z, A-Z, 0-9, ., -, _
157 // - Message content cannot be empty
158 // - Priority can be set to a value between -2 and 10, where -2 is the lowest and 10 is the highest priority. Negative values have special meanings in some clients.
159 // - Date parameter accepts multiple formats (RFC3339, RFC3339 without timezone, Unix timestamp seconds, "2006-01-02 15:04:05") and converts them to ISO 8601 format; invalid dates are skipped with a
160 // warning
161 // - Extras field accepts valid JSON objects for custom data
162 // - HTTP client timeout is set to 10 seconds for API requests
163 // - TLS can be disabled entirely (disabletls=yes) or certificate verification can be skipped (insecureskipverify=yes), both are not recommended for production use
164 // - Header authentication sends token in X-Gotify-Key header and cleans up after each request
165 // - Server response includes message ID, app ID, and timestamp upon successful delivery
166 // - Failed requests return structured error responses with error codes and descriptions
167 package gotify