Debian Codegraph @

pkg/services/push/bark/doc.go

raw
1 // Package bark provides a notification service for sending push notifications via Bark.
2 //
3 // The Bark service allows sending push notifications to iOS devices through a self-hosted
4 // Bark server. Bark is an iOS push notification service that provides a simple REST API
5 // for sending custom notifications with titles, sounds, badges, and more. It supports
6 // device-specific keys for targeted notifications and offers rich notification features
7 // including custom icons (iOS 15+), notification grouping, and actionable notifications.
8 //
9 // For more information about the Bark server, see: https://github.com/Finb/Bark
10 //
11 // # URL Format
12 //
13 // The service URL follows the format:
14 //
15 // bark://:devicekey@host[:port][/path][?query]
16 //
17 // Where:
18 // - devicekey: device key for authentication (required, passed as password in URL)
19 // - host: Bark server hostname (required)
20 // - port: optional port number (default: 443 for HTTPS, 80 for HTTP)
21 // - path: optional server path (default: "/")
22 // - query: configuration parameters
23 //
24 // # Configuration Options
25 //
26 // The following query parameters can be used to configure the service:
27 //
28 // - title: notification title (default: empty, uses app name)
29 // - sound: notification sound (default: empty, uses default system sound)
30 // See: https://github.com/Finb/Bark/tree/master/Sounds
31 // - badge: badge number displayed next to app icon (default: 0)
32 // - icon: URL to notification icon (iOS 15+ only)
33 // - group: notification group identifier
34 // - url: URL to open when notification is tapped
35 // - category: notification category (reserved for future use)
36 // - copy: text to copy to clipboard when notification is tapped
37 // - scheme: server protocol, "http" or "https" (default: "https")
38 //
39 // # Templates
40 //
41 // Bark does not use templates in the Shoutrrr sense, but supports rich notification
42 // formatting through its native features like titles, sounds, badges, and custom actions.
43 //
44 // # Usage Examples
45 //
46 // ## Basic notification
47 //
48 // url := "bark://:[email protected]"
49 // err := shoutrrr.Send(url, "Hello from Shoutrrr!")
50 //
51 // ## Notification with custom title and sound
52 //
53 // url := "bark://:[email protected]?title=Alert&sound=alarm"
54 // err := shoutrrr.Send(url, "System is down!")
55 //
56 // ## Notification with badge count
57 //
58 // url := "bark://:[email protected]?title=Messages&badge=5"
59 // err := shoutrrr.Send(url, "You have 5 new messages")
60 //
61 // ## Notification with custom icon
62 //
63 // url := "bark://:[email protected]?icon=https://example.com/icon.png"
64 // err := shoutrrr.Send(url, "Notification with custom icon")
65 //
66 // ## Notification with group and URL
67 //
68 // url := "bark://:[email protected]?group=alerts&url=https://example.com/details"
69 // err := shoutrrr.Send(url, "Click to view alert details")
70 //
71 // ## Notification that copies to clipboard
72 //
73 // url := "bark://:[email protected]?copy=https://example.com/api/token"
74 // err := shoutrrr.Send(url, "API token copied to clipboard")
75 //
76 // ## Notification to custom server path
77 //
78 // url := "bark://:[email protected]:2225/bark/push"
79 // err := shoutrrr.Send(url, "Notification to custom path")
80 //
81 // ## Notification with HTTP (insecure)
82 //
83 // url := "bark://:[email protected]?scheme=http"
84 // err := shoutrrr.Send(url, "Insecure notification (not recommended)")
85 //
86 // # Common Use Cases
87 //
88 // ## System Monitoring Alerts
89 //
90 // Send alerts from monitoring systems like Nagios, Prometheus, or Zabbix:
91 //
92 // url := "bark://:[email protected]?title=Alert&sound=alarm"
93 // err := shoutrrr.Send(url, "Disk space critical: 95% used")
94 //
95 // ## CI/CD Pipeline Notifications
96 //
97 // Notify about build status from Jenkins, GitHub Actions, or GitLab CI:
98 //
99 // url := "bark://:[email protected]?title=Build%20Failed&sound=alert"
100 // err := shoutrrr.Send(url, "Build #123 failed on main branch")
101 //
102 // ## Home Automation
103 //
104 // Integrate with home automation systems like Home Assistant:
105 //
106 // url := "bark://:[email protected]?title=Security&sound=alarm&group=home"
107 // err := shoutrrr.Send(url, "Motion detected at front door")
108 //
109 // ## Backup Completion Notifications
110 //
111 // Notify when backups complete:
112 //
113 // url := "bark://:[email protected]?title=Backup&sound=complete"
114 // err := shoutrrr.Send(url, "Daily backup finished successfully")
115 //
116 // ## Application Health Monitoring
117 //
118 // Send health check notifications from applications:
119 //
120 // url := "bark://:[email protected]?title=Health%20Check"
121 // err := shoutrrr.Send(url, "All services are healthy")
122 //
123 // ## Incident Response
124 //
125 // Send urgent notifications for incident response:
126 //
127 // url := "bark://:[email protected]?title=INCIDENT&sound=alarm&group=ops"
128 // err := shoutrrr.Send(url, "Database connection lost - immediate attention required")
129 //
130 // # Error Handling
131 //
132 // The service returns errors for various failure scenarios. Always check the returned error:
133 //
134 // err := shoutrrr.Send(url, message)
135 // if err != nil {
136 // log.Printf("Failed to send Bark notification: %v", err)
137 // }
138 //
139 // Common error scenarios:
140 // - Invalid device key format
141 // - Empty message content
142 // - Network connectivity issues
143 // - Invalid server hostname or port
144 // - TLS certificate verification failures (when HTTPS is used)
145 // - HTTP error status codes (4xx/5xx) from the Bark server
146 // - Invalid icon URL
147 // - Server-side errors (returned in API response message)
148 //
149 // # Security Considerations
150 //
151 // - Use HTTPS whenever possible (default behavior) to protect notification content in transit
152 // - Store device keys securely - avoid hardcoding them in source code or configuration files
153 // - Device keys are device-specific and act as authentication tokens
154 // - Be cautious with scheme=http - only use in trusted environments as it disables encryption
155 // - Validate icon URLs - ensure they point to trusted sources
156 // - Consider message content - avoid sending sensitive information in notification messages
157 // - Use appropriate notification sounds - avoid disruptive sounds in production environments
158 // - Implement proper access controls on your Bark server to prevent unauthorized key usage
159 //
160 // # Limitations and Behaviors
161 //
162 // - Device key is required and must be provided in the URL password field
163 // - Message content cannot be empty
164 // - Icon is only available on iOS 15 or later
165 // - Category is reserved for future use
166 // - Badge number can be any non-negative integer
167 // - Sound values must match available sounds in the Bark server
168 // (see: https://github.com/Finb/Bark/tree/master/Sounds)
169 // - Custom sounds can be added to the Bark server
170 // - Group helps organize notifications but display depends on the client
171 // - URL field specifies what URL to open when notification is tapped
172 // - Copy field specifies text to copy to clipboard when notification is tapped
173 // - Server path defaults to "/" if not specified
174 // - Default scheme is "https" for secure communication
175 // - HTTP client timeout is set for API requests
176 // - Server response includes code, message, and timestamp upon delivery
177 // - Failed requests return structured error responses with error codes and descriptions
178 package bark