Debian Codegraph @

pkg/services/push/ntfy/doc.go

raw
1 // Package ntfy provides a notification service for sending push notifications via ntfy.sh.
2 //
3 // The ntfy service allows sending notifications to ntfy topics, which can be subscribed to
4 // by mobile apps, web browsers, and other clients. It supports rich notifications with
5 // titles, priorities, tags, attachments, actions, and more. ntfy is a simple HTTP-based
6 // pub-sub notification service that works with any programming language.
7 //
8 // # URL Format
9 //
10 // The service URL follows the format:
11 //
12 // ntfy://[user:password@]host[:port]/topic[?query]
13 //
14 // Where:
15 // - user: optional username for authentication
16 // - password: optional password for authentication
17 // - host: ntfy server hostname (default: ntfy.sh)
18 // - port: optional port number (default: 443 for HTTPS, 80 for HTTP)
19 // - topic: target topic name (required)
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
27 // - priority: message priority (1=min, 2=low, 3=default, 4=high, 5=max/urgent)
28 // - tags: comma-separated list of tags (may map to emojis)
29 // - actions: semicolon-separated list of user action buttons
30 // - click: URL to open when notification is clicked
31 // - attach: URL of attachment to include
32 // - filename: filename for attachment
33 // - delay: timestamp or duration for delayed delivery (e.g., "30m", "1h", "2023-12-25T10:00:00Z")
34 // - email: email address for email notifications
35 // - icon: URL to use as notification icon
36 // - cache: whether to cache messages (default: yes)
37 // - firebase: whether to send via Firebase (default: yes)
38 // - disabletls: set to "yes" to disable TLS verification
39 //
40 // # Templates
41 //
42 // ntfy does not use templates in the Shoutrrr sense, but supports rich message formatting
43 // through its native features like titles, tags, priorities, and actions.
44 //
45 // # Usage Examples
46 //
47 // ## Basic notification
48 //
49 // url := "ntfy://mytopic"
50 // err := shoutrrr.Send(url, "Hello from Shoutrrr!")
51 //
52 // ## Notification with title and high priority
53 //
54 // url := "ntfy://mytopic?title=Alert&priority=high"
55 // err := shoutrrr.Send(url, "System is down!")
56 //
57 // ## Notification with tags and actions
58 //
59 // url := "ntfy://mytopic?tags=warning,server&actions=view,%20View%20logs,%20https://logs.example.com"
60 // err := shoutrrr.Send(url, "Server error occurred")
61 //
62 // ## Notification with attachment
63 //
64 // url := "ntfy://mytopic?title=Backup&attach=https://files.example.com/backup.zip&filename=backup.zip"
65 // err := shoutrrr.Send(url, "Backup completed successfully")
66 //
67 // ## Delayed notification
68 //
69 // url := "ntfy://mytopic?delay=1h"
70 // err := shoutrrr.Send(url, "Reminder: Meeting in 1 hour")
71 //
72 // ## Notification with authentication
73 //
74 // url := "ntfy://user:[email protected]/mytopic"
75 // err := shoutrrr.Send(url, "Authenticated 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 := "ntfy://alerts?priority=high&tags=warning,server"
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 := "ntfy://builds?tags=success,github&title=Build%20Successful"
91 // err := shoutrrr.Send(url, "Build #123 passed")
92 //
93 // ## Home Automation
94 //
95 // Integrate with home automation systems like Home Assistant:
96 //
97 // url := "ntfy://home?tags=home,security&priority=urgent"
98 // err := shoutrrr.Send(url, "Motion detected at front door")
99 //
100 // ## Backup Completion Notifications
101 //
102 // Notify when backups complete:
103 //
104 // url := "ntfy://backups?tags=backup,done&title=Backup%20Complete"
105 // err := shoutrrr.Send(url, "Daily backup finished successfully")
106 //
107 // ## Scheduled Reminders
108 //
109 // Send delayed notifications for reminders:
110 //
111 // url := "ntfy://reminders?delay=9am&title=Morning%20Reminder"
112 // err := shoutrrr.Send(url, "Don't forget the team meeting!")
113 //
114 // # Error Handling
115 //
116 // The service returns errors for network failures, HTTP error status codes (4xx/5xx),
117 // authentication failures, and configuration issues. Always check the returned error:
118 //
119 // err := shoutrrr.Send(url, message)
120 // if err != nil {
121 // log.Printf("Failed to send ntfy notification: %v", err)
122 // }
123 //
124 // Common error scenarios:
125 // - Invalid topic name
126 // - Authentication failure (wrong credentials)
127 // - Network connectivity issues
128 // - Server rate limiting
129 // - Invalid attachment URLs
130 //
131 // # Security Considerations
132 //
133 // - Use HTTPS whenever possible (default behavior)
134 // - Store credentials securely, not in URLs if possible
135 // - Consider topic names as passwords - use unique, hard-to-guess names
136 // - Be cautious with attachment URLs - ensure they are from trusted sources
137 // - Use authentication for private topics
138 // - Consider message content - avoid sending sensitive information in notifications
139 // - Rate limiting may apply depending on server configuration
140 //
141 // # Limitations and Behaviors
142 //
143 // - Topic names are case-sensitive
144 // - Maximum message size depends on server configuration (typically 4KB)
145 // - Attachments are referenced by URL, not uploaded directly
146 // - Actions are limited to view, broadcast, and http types
147 // - Delayed delivery minimum is 10 seconds, maximum is 3 days
148 // - Messages may be cached on the server for up to 12 hours after delivery
149 // - Firebase notifications may not work in all regions or for all clients
150 // - Some features (like actions) are client-dependent and may not work on all platforms
151 package ntfy