| 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 |