Skip to content

Commit 126c1e8

Browse files
fixup: LSPS5 events - Improve type safety and documentation
- Replaces raw error code/message pairs with a structured LSPS5Error type - Changes String timestamp fields to use the proper LSPSDateTime type - Improves documentation with references to MAX_APP_NAME_LENGTH constant
1 parent 5ddcfbd commit 126c1e8

File tree

1 file changed

+87
-75
lines changed

1 file changed

+87
-75
lines changed

lightning-liquidity/src/lsps5/event.rs

+87-75
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,16 @@
99

1010
//! Events generated by the LSPS5 service and client
1111
12+
use crate::lsps0::ser::LSPSDateTime;
1213
use crate::lsps0::ser::LSPSRequestId;
1314
use alloc::string::String;
1415
use alloc::vec::Vec;
1516
use bitcoin::secp256k1::PublicKey;
1617

1718
use super::msgs::LSPS5AppName;
19+
use super::msgs::LSPS5Error;
1820
use super::msgs::LSPS5WebhookUrl;
1921
use super::msgs::WebhookNotification;
20-
2122
/// An event which an bLIP-55 / LSPS5 server should take some action in response to.
2223
#[derive(Debug, Clone, PartialEq, Eq)]
2324
pub enum LSPS5ServiceEvent {
@@ -26,101 +27,119 @@ pub enum LSPS5ServiceEvent {
2627
/// This event occurs when a client successfully registers a webhook via `lsps5.set_webhook`.
2728
/// You should store this information to be able to contact the client when they are offline.
2829
WebhookRegistered {
29-
/// Client node ID that registered the webhook
30+
/// Client node ID that registered the webhook.
3031
counterparty_node_id: PublicKey,
31-
/// App name provided by the client (up to 64 bytes in UTF-8 format)
32+
/// App name provided by the client.
33+
///
34+
/// This app name is used to identify the webhook registration.
35+
///
36+
/// **Note**: Ensure the app name is valid and its length does not exceed [`MAX_APP_NAME_LENGTH`].
37+
///
38+
/// [`MAX_APP_NAME_LENGTH`]: super::msgs::MAX_APP_NAME_LENGTH
3239
app_name: LSPS5AppName,
33-
/// Webhook URL (HTTPS) that should be contacted to notify the client (up to 1024 ASCII characters)
40+
/// Webhook URL (HTTPS) to be contacted for notifying the client.
41+
///
42+
/// This URL is used by the LSP to send notifications.
43+
///
44+
/// **Note**: Ensure the URL is valid and its length does not exceed [`MAX_WEBHOOK_URL_LENGTH`].
45+
/// Also ensure that the URL points to a public host.
46+
///
47+
/// [`MAX_WEBHOOK_URL_LENGTH`]: super::msgs::MAX_WEBHOOK_URL_LENGTH
3448
url: LSPS5WebhookUrl,
35-
/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
49+
/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request.
3650
///
3751
/// This can be used to track which request this event corresponds to.
3852
request_id: LSPSRequestId,
39-
/// Whether this was a new registration or an update to existing one with no changes
40-
/// If false, a notification should be sent to the registered webhook
53+
/// Whether this was a new registration or an update to existing one with no changes.
54+
/// If false, a notification should be sent to the registered webhook.
4155
no_change: bool,
4256
},
4357

44-
/// Webhooks were listed for a client
58+
/// Webhooks were listed for a client.
4559
///
4660
/// This event occurs when a client requests their registered webhooks via `lsps5.list_webhooks`.
4761
WebhooksListed {
48-
/// Client node ID that requested their webhooks
62+
/// Client node ID that requested their webhooks.
4963
counterparty_node_id: PublicKey,
50-
/// App names with registered webhooks for this client
64+
/// App names with registered webhooks for this client.
5165
app_names: Vec<LSPS5AppName>,
52-
/// The identifier of the issued bLIP-55 / LSPS5 webhook listing request
66+
/// The identifier of the issued bLIP-55 / LSPS5 webhook listing request.
5367
///
5468
/// This can be used to track which request this event corresponds to.
5569
request_id: LSPSRequestId,
56-
/// Maximum number of webhooks allowed by LSP per client
70+
/// Maximum number of webhooks allowed by LSP per client.
5771
max_webhooks: u32,
5872
},
5973

60-
/// A webhook was removed by a client
74+
/// A webhook was removed by a client.
6175
///
6276
/// This event occurs when a client successfully removes a webhook via `lsps5.remove_webhook`.
6377
WebhookRemoved {
64-
/// Client node ID that removed the webhook
78+
/// Client node ID that removed the webhook.
6579
counterparty_node_id: PublicKey,
66-
/// App name that was removed
80+
/// App name that was removed.
6781
app_name: LSPS5AppName,
68-
/// The identifier of the issued bLIP-55 / LSPS5 webhook removal request
82+
/// The identifier of the issued bLIP-55 / LSPS5 webhook removal request.
6983
///
7084
/// This can be used to track which request this event corresponds to.
7185
request_id: LSPSRequestId,
7286
},
7387

74-
/// A notification needs to be sent to a client's webhook
88+
/// A notification needs to be sent to a client's webhook.
7589
///
7690
/// This event occurs when the LSP needs to send a notification to a client's webhook.
7791
/// When this event is received, the LSP should:
78-
/// 1. Serialize the notification to JSON
79-
/// 2. Make an HTTP POST request to the provided URL with the given headers and the serialized notification
92+
/// 1. Serialize the notification to JSON.
93+
/// 2. Make an HTTP POST request to the provided
94+
/// URL with the given headers and the serialized notification.
8095
///
8196
/// When the client receives this notification, they will process it and generate a
8297
/// `WebhookNotificationReceived` event on their side. The client will validate the
8398
/// signature using the LSP's node ID to ensure the notification is authentic.
8499
SendWebhookNotifications {
85-
/// Client node ID to be notified
100+
/// Client node ID to be notified.
86101
counterparty_node_id: PublicKey,
87-
/// App name to be notified
102+
/// App name to be notified.
88103
app_name: LSPS5AppName,
89-
/// URL that to be contacted
104+
/// URL that to be contacted.
90105
url: LSPS5WebhookUrl,
91-
/// Notification method with its parameters
106+
/// Notification method with its parameters.
92107
notification: WebhookNotification,
93-
/// ISO8601 timestamp of the notification (YYYY-MM-DDThh:mm:ss.uuuZ format)
94-
timestamp: String,
95-
/// Signature of the notification using the LSP's node ID
108+
/// Timestamp of the notification.
109+
timestamp: LSPSDateTime,
110+
/// Signature of the notification using the LSP's node ID.
96111
signature: String,
97-
/// Headers to be included in the HTTP POST request
112+
/// Headers to be included in the HTTP POST request.
113+
///
114+
/// Content-Type (application/json).
115+
/// x-lsps5-timestamp (timestamp in RFC3339 (YYYY-MM-DDThh:mm:ss.uuuZ) format).
116+
/// x-lsps5-signature (signature of the notification using the LSP's node ID).
98117
headers: Vec<(String, String)>,
99118
},
100119
}
101120

102121
/// An event which an LSPS5 client should take some action in response to.
103122
#[derive(Debug, Clone, PartialEq, Eq)]
104123
pub enum LSPS5ClientEvent {
105-
/// A webhook was successfully registered with the LSP
124+
/// A webhook was successfully registered with the LSP.
106125
///
107126
/// This event is triggered when the LSP confirms successful registration
108127
/// of a webhook via `lsps5.set_webhook`.
109128
WebhookRegistered {
110-
/// The node id of the LSP that confirmed the registration
129+
/// The node id of the LSP that confirmed the registration.
111130
counterparty_node_id: PublicKey,
112-
/// Current number of webhooks registered for this client
131+
/// Current number of webhooks registered for this client.
113132
num_webhooks: u32,
114-
/// Maximum number of webhooks allowed by LSP
133+
/// Maximum number of webhooks allowed by LSP.
115134
max_webhooks: u32,
116-
/// Whether this was an unchanged registration (same app_name and URL)
117-
/// If true, the LSP didn't send a webhook notification for this registration
135+
/// Whether this was an unchanged registration (same app_name and URL).
136+
/// If true, the LSP didn't send a webhook notification for this registration.
118137
no_change: bool,
119-
/// The app name that was registered (up to 64 bytes in UTF-8 format)
138+
/// The app name that was registered.
120139
app_name: LSPS5AppName,
121-
/// The webhook URL that was registered (HTTPS protocol)
140+
/// The webhook URL that was registered.
122141
url: LSPS5WebhookUrl,
123-
/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
142+
/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request.
124143
///
125144
/// This can be used to track which request this event corresponds to.
126145
request_id: LSPSRequestId,
@@ -132,102 +151,95 @@ pub enum LSPS5ClientEvent {
132151
/// via `lsps5.set_webhook`. This can happen if the app_name or URL is too long,
133152
/// the URL uses an unsupported protocol, or the maximum number of webhooks is reached.
134153
WebhookRegistrationFailed {
135-
/// The node id of the LSP that rejected the registration
154+
/// The node id of the LSP that rejected the registration.
136155
counterparty_node_id: PublicKey,
137-
/// Error code from the LSP (500: too_long, 501: url_parse_error,
138-
/// 502: unsupported_protocol, 503: too_many_webhooks)
139-
error_code: i32,
140-
/// Error message from the LSP
141-
error_message: String,
142-
/// The app name that was attempted
156+
/// Error from the LSP.
157+
error: LSPS5Error,
158+
/// The app name that was attempted.
143159
app_name: LSPS5AppName,
144-
/// The webhook URL that was attempted
160+
/// The webhook URL that was attempted.
145161
url: LSPS5WebhookUrl,
146-
/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
162+
/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request.
147163
///
148164
/// This can be used to track which request this event corresponds to.
149165
request_id: LSPSRequestId,
150166
},
151167

152-
/// The list of registered webhooks was successfully retrieved
168+
/// The list of registered webhooks was successfully retrieved.
153169
///
154170
/// This event is triggered when the LSP responds to a `lsps5.list_webhooks` request.
155171
WebhooksListed {
156-
/// The node id of the LSP that provided the list
172+
/// The node id of the LSP that provided the list.
157173
counterparty_node_id: PublicKey,
158-
/// List of app names with registered webhooks
174+
/// List of app names with registered webhooks.
159175
app_names: Vec<LSPS5AppName>,
160-
/// Maximum number of webhooks allowed by LSP
176+
/// Maximum number of webhooks allowed by LSP.
161177
max_webhooks: u32,
162-
/// The identifier of the issued bLIP-55 / LSPS5 list webhooks request
178+
/// The identifier of the issued bLIP-55 / LSPS5 list webhooks request.
163179
///
164180
/// This can be used to track which request this event corresponds to.
165181
request_id: LSPSRequestId,
166182
},
167183

168-
/// The attempt to list webhooks failed
184+
/// The attempt to list webhooks failed.
169185
///
170186
/// This event is triggered when the LSP rejects a `lsps5.list_webhooks` request.
171187
WebhooksListFailed {
172-
/// The node id of the LSP that rejected the request
188+
/// The node id of the LSP that rejected the request.
173189
counterparty_node_id: PublicKey,
174-
/// Error code from the LSP
175-
error_code: i32,
176-
/// Error message from the LSP
177-
error_message: String,
178-
/// The identifier of the issued bLIP-55 / LSPS5 list webhooks request
190+
/// Error from the LSP.
191+
error: LSPS5Error,
192+
/// The identifier of the issued bLIP-55 / LSPS5 list webhooks request.
179193
///
180194
/// This can be used to track which request this event corresponds to.
181195
request_id: LSPSRequestId,
182196
},
183197

184-
/// A webhook was successfully removed
198+
/// A webhook was successfully removed.
185199
///
186200
/// This event is triggered when the LSP confirms successful removal
187201
/// of a webhook via `lsps5.remove_webhook`.
188202
WebhookRemoved {
189-
/// The node id of the LSP that confirmed the removal
203+
/// The node id of the LSP that confirmed the removal.
190204
counterparty_node_id: PublicKey,
191-
/// The app name that was removed
205+
/// The app name that was removed.
192206
app_name: LSPS5AppName,
193-
/// The identifier of the issued bLIP-55 / LSPS5 remove webhook request
207+
/// The identifier of the issued bLIP-55 / LSPS5 remove webhook request.
194208
///
195209
/// This can be used to track which request this event corresponds to.
196210
request_id: LSPSRequestId,
197211
},
198212

199-
/// A webhook removal attempt failed
213+
/// A webhook removal attempt failed.
200214
///
201215
/// This event is triggered when the LSP rejects a webhook removal
202216
/// via `lsps5.remove_webhook`. The most common error is app_name_not_found (1010).
203217
WebhookRemovalFailed {
204-
/// The node id of the LSP that rejected the removal
218+
/// The node id of the LSP that rejected the removal.
205219
counterparty_node_id: PublicKey,
206-
/// Error code from the LSP (1010: app_name_not_found)
207-
error_code: i32,
208-
/// Error message from the LSP
209-
error_message: String,
210-
/// The app name that was attempted to be removed
220+
/// Error from the LSP.
221+
error: LSPS5Error,
222+
/// The app name that was attempted to be removed.
211223
app_name: LSPS5AppName,
212-
/// The identifier of the issued bLIP-55 / LSPS5 remove webhook request
224+
/// The identifier of the issued bLIP-55 / LSPS5 remove webhook request.
213225
///
214226
/// This can be used to track which request this event corresponds to.
215227
request_id: LSPSRequestId,
216228
},
217229

218-
/// A webhook notification was received from the LSP
230+
/// A webhook notification was received from the LSP.
219231
///
220232
/// This event is triggered when the client receives a webhook notification
221233
/// from the LSP. This can happen for various reasons such as incoming payment,
222234
/// expiring HTLCs, liquidity management requests, or incoming onion messages.
223235
WebhookNotificationReceived {
224-
/// LSP node ID that sent the notification
236+
/// LSP node ID that sent the notification.
225237
counterparty_node_id: PublicKey,
226-
/// The notification with its method and parameters
238+
/// The notification with its method and parameters.
227239
notification: WebhookNotification,
228-
/// Timestamp of the notification in ISO8601 format (YYYY-MM-DDThh:mm:ss.uuuZ)
229-
timestamp: String,
230-
/// Whether the LSP's signature was successfully verified
240+
/// Timestamp of the notification.
241+
timestamp: LSPSDateTime,
242+
/// Whether the LSP's signature was successfully verified.
231243
signature_valid: bool,
232244
},
233245
}

0 commit comments

Comments
 (0)