Debian Codegraph @

pkg/services/chat/matrix/doc.go

raw
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