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