Debian Codegraph @

pkg/services/push/mqtt/doc.go

raw
1 // Package mqtt provides a notification service for sending messages to MQTT brokers.
2 //
3 // MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol
4 // ideal for small sensors and mobile devices, optimized for high-latency or
5 // unreliable networks. This service supports both standard (mqtt://) and secure
6 // (mqtts://) connections to any MQTT-compatible broker.
7 //
8 // # URL Format
9 //
10 // The service URL follows the format:
11 //
12 // mqtt://[username[:password]@]host[:port]/topic[?options]
13 // mqtts://[username[:password]@]host[:port]/topic[?options]
14 //
15 // Where:
16 // - username: optional username for authentication
17 // - password: optional password for authentication
18 // - host: MQTT broker hostname (default: localhost)
19 // - port: optional port number (default: 1883 for mqtt://, 8883 for mqtts://)
20 // - topic: target topic name (required)
21 // - options: configuration parameters
22 //
23 // # Configuration Options
24 //
25 // The following query parameters can be used to configure the service:
26 //
27 // - clientid: MQTT client identifier (default: shoutrrr)
28 // - qos: Quality of Service level (0=at most once, 1=at least once, 2=exactly once)
29 // - retained: retain message on broker (default: no)
30 // - cleansession: start with a clean session (default: yes)
31 // - disabletls: disable TLS encryption (default: no)
32 // - disabletlsverification: disable TLS certificate verification (default: no)
33 //
34 // # Quality of Service (QoS) Levels
35 //
36 // MQTT supports three QoS levels:
37 // - 0 (At most once): Message delivered at most once, no acknowledgment
38 // - 1 (At least once): Message delivered at least once, requires acknowledgment
39 // - 2 (Exactly once): Message delivered exactly once, requires four-part handshake
40 //
41 // # Usage Examples
42 //
43 // ## Basic notification
44 //
45 // url := "mqtt://broker.example.com/notifications"
46 // err := shoutrrr.Send(url, "Hello from Shoutrrr!")
47 //
48 // ## Notification with authentication
49 //
50 // url := "mqtt://user:[email protected]/sensors/temperature"
51 // err := shoutrrr.Send(url, "Temperature: 25°C")
52 //
53 // ## Secure connection with QoS
54 //
55 // url := "mqtts://broker.example.com/alerts?qos=1&retained=yes"
56 // err := shoutrrr.Send(url, "System alert: High CPU usage")
57 //
58 // ## Custom client ID and clean session
59 //
60 // url := "mqtt://broker.example.com/events?clientid=myapp&cleansession=no"
61 // err := shoutrrr.Send(url, "Event triggered")
62 //
63 // # Common Use Cases
64 //
65 // ## IoT Device Notifications
66 //
67 // Send notifications from IoT devices to central systems:
68 //
69 // url := "mqtt://iot-broker.local/sensors/living-room?retained=yes"
70 // err := shoutrrr.Send(url, "Motion detected")
71 //
72 // ## Home Automation
73 //
74 // Integrate with home automation systems like Home Assistant:
75 //
76 // url := "mqtt://homeassistant.local/homeassistant/sensor/temperature"
77 // err := shoutrrr.Send(url, `{"state": "22.5", "unit": "°C"}`)
78 //
79 // ## Real-time Monitoring
80 //
81 // Send monitoring alerts to MQTT topics:
82 //
83 // url := "mqtts://mqtt.example.com/monitoring/alerts?qos=1"
84 // err := shoutrrr.Send(url, "Server CPU usage above 90%")
85 //
86 // # TLS Configuration
87 //
88 // For secure connections, use the mqtts:// scheme (TLS enabled by default):
89 //
90 // url := "mqtts://broker.example.com:8883/secure-topic"
91 //
92 // To explicitly disable TLS, set disabletls=true. To explicitly enable TLS when
93 // using the mqtt:// scheme, set disabletls=false:
94 //
95 // url := "mqtt://broker.example.com/topic?disabletls=false"
96 //
97 // To explicitly disable TLS when using the mqtts:// scheme:
98 //
99 // url := "mqtts://broker.example.com:8883/secure-topic?disabletls=true"
100 //
101 // To skip TLS certificate verification (useful for testing with self-signed certs):
102 //
103 // url := "mqtts://broker.example.com/topic?disabletlsverification=yes"
104 //
105 // # Connection Behavior
106 //
107 // The service establishes a connection to the MQTT broker on each Send call
108 // and disconnects after the message is published. This ensures reliable
109 // delivery while maintaining compatibility with various broker configurations.
110 //
111 // For high-volume messaging, consider using a dedicated MQTT client library
112 // that maintains persistent connections.
113 package mqtt