| 1 |
// Package matrix provides a notification service for sending messages via the Matrix protocol. |
| 2 |
// |
| 3 |
// The Matrix service enables sending notifications to Matrix rooms using the Matrix |
| 4 |
// Client-Server API. Matrix is an open protocol for real-time communication that |
| 5 |
// supports end-to-end encryption, room-based messaging, and integration with various |
| 6 |
// clients. This service supports both password-based and token-based authentication. |
| 7 |
// |
| 8 |
// # URL Format |
| 9 |
// |
| 10 |
// The service URL follows the format: |
| 11 |
// |
| 12 |
// matrix://[user[:password]@]host[:port][?query] |
| 13 |
// |
| 14 |
// Where: |
| 15 |
// - user: Matrix username (required for password authentication, omit when using access token) |
| 16 |
// - password: Matrix password or access token (required) |
| 17 |
// - host: Matrix server hostname (required) |
| 18 |
// - port: optional port number (default: 443) |
| 19 |
// - query: configuration parameters |
| 20 |
// |
| 21 |
// # Authentication |
| 22 |
// |
| 23 |
// The service supports two authentication methods: |
| 24 |
// |
| 25 |
// Password Authentication: |
| 26 |
// When a username is provided along with a password, the service will attempt to |
| 27 |
// authenticate using the m.login.password flow: |
| 28 |
// |
| 29 |
// matrix://user:[email protected] |
| 30 |
// |
| 31 |
// Token Authentication: |
| 32 |
// When no username is provided, the password field is treated as an access token: |
| 33 |
// |
| 34 |
// matrix://:[email protected] |
| 35 |
// |
| 36 |
// # Configuration Options |
| 37 |
// |
| 38 |
// The following query parameters can be used to configure the service: |
| 39 |
// |
| 40 |
// - rooms: comma-separated list of room aliases (e.g., "#room:example.com") or |
| 41 |
// room IDs (e.g., "!roomid:example.com"). If not specified, messages are sent |
| 42 |
// to all joined rooms. |
| 43 |
// - title: notification title to prepend to the message |
| 44 |
// - disableTLS: set to "yes" or "true" to disable TLS (not recommended) |
| 45 |
// |
| 46 |
// # Templates |
| 47 |
// |
| 48 |
// Matrix does not use templates in the Shoutrrr sense, but supports adding a title |
| 49 |
// prefix to messages through the title parameter. |
| 50 |
// |
| 51 |
// # Usage Examples |
| 52 |
// |
| 53 |
// ## Basic notification to all joined rooms |
| 54 |
// |
| 55 |
// url := "matrix://:[email protected]" |
| 56 |
// err := shoutrrr.Send(url, "Hello from Shoutrrr!") |
| 57 |
// |
| 58 |
// ## Notification to specific rooms |
| 59 |
// |
| 60 |
// url := "matrix://:[email protected]?rooms=#alerts:example.com,#general:example.com" |
| 61 |
// err := shoutrrr.Send(url, "Alert message") |
| 62 |
// |
| 63 |
// ## Notification with password authentication |
| 64 |
// |
| 65 |
// url := "matrix://myuser:[email protected]" |
| 66 |
// err := shoutrrr.Send(url, "Hello from myuser!") |
| 67 |
// |
| 68 |
// ## Notification with title |
| 69 |
// |
| 70 |
// url := "matrix://:[email protected]?title=Alert" |
| 71 |
// err := shoutrrr.Send(url, "System is down!") |
| 72 |
// |
| 73 |
// ## Custom port and TLS disabled |
| 74 |
// |
| 75 |
// url := "matrix://:[email protected]:8008?disableTLS=yes" |
| 76 |
// err := shoutrrr.Send(url, "Insecure notification") |
| 77 |
// |
| 78 |
// # Common Use Cases |
| 79 |
// |
| 80 |
// ## Monitoring System Alerts |
| 81 |
// |
| 82 |
// Send alerts from monitoring systems like Prometheus, Nagios, or Zabbix: |
| 83 |
// |
| 84 |
// url := "matrix://:[email protected]?rooms=#alerts:example.com&title=Monitoring" |
| 85 |
// err := shoutrrr.Send(url, "Disk space critical: 95% used") |
| 86 |
// |
| 87 |
// ## CI/CD Pipeline Notifications |
| 88 |
// |
| 89 |
// Notify about build status from Jenkins, GitHub Actions, or GitLab CI: |
| 90 |
// |
| 91 |
// url := "matrix://:[email protected]?rooms=#builds:example.com&title=Build%20Status" |
| 92 |
// err := shoutrrr.Send(url, "Build #123 passed") |
| 93 |
// |
| 94 |
// ## Team Notifications |
| 95 |
// |
| 96 |
// Send notifications to team rooms: |
| 97 |
// |
| 98 |
// url := "matrix://:[email protected]?rooms=#team:example.com" |
| 99 |
// err := shoutrrr.Send(url, "Deployment started") |
| 100 |
// |
| 101 |
// ## Application Notifications |
| 102 |
// |
| 103 |
// Send notifications from applications: |
| 104 |
// |
| 105 |
// url := "matrix://myuser:[email protected]?rooms=#notifications:example.com" |
| 106 |
// err := shoutrrr.Send(url, "New order received: #12345") |
| 107 |
// |
| 108 |
// # Room Alias Resolution |
| 109 |
// |
| 110 |
// The service automatically resolves room aliases to room IDs. If a room alias |
| 111 |
// doesn't start with # or !, # is automatically prepended: |
| 112 |
// |
| 113 |
// // These are equivalent: |
| 114 |
// rooms=general |
| 115 |
// rooms=#general:example.com |
| 116 |
// |
| 117 |
// Room IDs must start with !: |
| 118 |
// |
| 119 |
// rooms=!roomid:example.com |
| 120 |
// |
| 121 |
// # Error Handling |
| 122 |
// |
| 123 |
// The service returns errors for various failure scenarios. Always check the |
| 124 |
// returned error: |
| 125 |
// |
| 126 |
// err := shoutrrr.Send(url, message) |
| 127 |
// if err != nil { |
| 128 |
// log.Printf("Failed to send Matrix notification: %v", err) |
| 129 |
// } |
| 130 |
// |
| 131 |
// Common error scenarios: |
| 132 |
// - ErrMissingHost: No Matrix server host provided |
| 133 |
// - ErrMissingCredentials: No password or access token provided |
| 134 |
// - ErrClientNotInitialized: Client failed to initialize |
| 135 |
// - ErrUnsupportedLoginFlows: Server doesn't support password or token login |
| 136 |
// - ErrUnexpectedStatus: Unexpected HTTP response from server |
| 137 |
// |
| 138 |
// # Security Considerations |
| 139 |
// |
| 140 |
// - Store access tokens securely, never in URLs in production |
| 141 |
// - Prefer token authentication over password authentication when possible |
| 142 |
// - Use TLS (default) for all production connections |
| 143 |
// - Consider room access controls when sending to shared rooms |
| 144 |
// - Access tokens provide full access to your Matrix account |
| 145 |
// |
| 146 |
// # Matrix API |
| 147 |
// |
| 148 |
// This service uses the Matrix Client-Server API v3. Key endpoints include: |
| 149 |
// - POST /_matrix/client/v3/login: Authentication |
| 150 |
// - POST /_matrix/client/v3/join/{roomIdOrAlias}: Join room |
| 151 |
// - GET /_matrix/client/v3/joined_rooms: List joined rooms |
| 152 |
// - PUT /_matrix/client/v3/rooms/{roomId}/send/m.room.message: Send message |
| 153 |
// |
| 154 |
// For more information about Matrix, see: https://matrix.org/ |
| 155 |
package matrix |