]> git.bitcoin.ninja Git - rust-lightning/blob - lightning-custom-message/src/lib.rs
Persist scorer upon update based on event handling
[rust-lightning] / lightning-custom-message / src / lib.rs
1 //! Utilities for supporting custom peer-to-peer messages in LDK.
2 //!
3 //! [BOLT 1] specifies a custom message type range for use with experimental or application-specific
4 //! messages. While a [`CustomMessageHandler`] can be defined to support more than one message type,
5 //! defining such a handler requires a significant amount of boilerplate and can be error prone.
6 //!
7 //! This crate provides the [`composite_custom_message_handler`] macro for easily composing
8 //! pre-defined custom message handlers into one handler. The resulting handler can be further
9 //! composed with other custom message handlers using the same macro.
10 //!
11 //! The following example demonstrates defining a `FooBarHandler` to compose separate handlers for
12 //! `Foo` and `Bar` messages, and further composing it with a handler for `Baz` messages.
13 //!
14 //!```
15 //! # extern crate bitcoin;
16 //! extern crate lightning;
17 //! #[macro_use]
18 //! extern crate lightning_custom_message;
19 //!
20 //! # use bitcoin::secp256k1::PublicKey;
21 //! # use lightning::io;
22 //! # use lightning::ln::msgs::{DecodeError, LightningError};
23 //! use lightning::ln::peer_handler::CustomMessageHandler;
24 //! use lightning::ln::wire::{CustomMessageReader, self};
25 //! use lightning::util::ser::Writeable;
26 //! # use lightning::util::ser::Writer;
27 //!
28 //! // Assume that `FooHandler` and `BarHandler` are defined in one crate and `BazHandler` is
29 //! // defined in another crate, handling messages `Foo`, `Bar`, and `Baz`, respectively.
30 //!
31 //! #[derive(Debug)]
32 //! pub struct Foo;
33 //!
34 //! macro_rules! foo_type_id {
35 //!     () => { 32768 }
36 //! }
37 //!
38 //! impl wire::Type for Foo {
39 //!     fn type_id(&self) -> u16 { foo_type_id!() }
40 //! }
41 //! impl Writeable for Foo {
42 //!     // ...
43 //! #     fn write<W: Writer>(&self, _: &mut W) -> Result<(), io::Error> {
44 //! #         unimplemented!()
45 //! #     }
46 //! }
47 //!
48 //! pub struct FooHandler;
49 //!
50 //! impl CustomMessageReader for FooHandler {
51 //!     // ...
52 //! #     type CustomMessage = Foo;
53 //! #     fn read<R: io::Read>(
54 //! #         &self, _message_type: u16, _buffer: &mut R
55 //! #     ) -> Result<Option<Self::CustomMessage>, DecodeError> {
56 //! #         unimplemented!()
57 //! #     }
58 //! }
59 //! impl CustomMessageHandler for FooHandler {
60 //!     // ...
61 //! #     fn handle_custom_message(
62 //! #         &self, _msg: Self::CustomMessage, _sender_node_id: &PublicKey
63 //! #     ) -> Result<(), LightningError> {
64 //! #         unimplemented!()
65 //! #     }
66 //! #     fn get_and_clear_pending_msg(&self) -> Vec<(PublicKey, Self::CustomMessage)> {
67 //! #         unimplemented!()
68 //! #     }
69 //! }
70 //!
71 //! #[derive(Debug)]
72 //! pub struct Bar;
73 //!
74 //! macro_rules! bar_type_id {
75 //!     () => { 32769 }
76 //! }
77 //!
78 //! impl wire::Type for Bar {
79 //!     fn type_id(&self) -> u16 { bar_type_id!() }
80 //! }
81 //! impl Writeable for Bar {
82 //!     // ...
83 //! #     fn write<W: Writer>(&self, _: &mut W) -> Result<(), io::Error> {
84 //! #         unimplemented!()
85 //! #     }
86 //! }
87 //!
88 //! pub struct BarHandler;
89 //!
90 //! impl CustomMessageReader for BarHandler {
91 //!     // ...
92 //! #     type CustomMessage = Bar;
93 //! #     fn read<R: io::Read>(
94 //! #         &self, _message_type: u16, _buffer: &mut R
95 //! #     ) -> Result<Option<Self::CustomMessage>, DecodeError> {
96 //! #         unimplemented!()
97 //! #     }
98 //! }
99 //! impl CustomMessageHandler for BarHandler {
100 //!     // ...
101 //! #     fn handle_custom_message(
102 //! #         &self, _msg: Self::CustomMessage, _sender_node_id: &PublicKey
103 //! #     ) -> Result<(), LightningError> {
104 //! #         unimplemented!()
105 //! #     }
106 //! #     fn get_and_clear_pending_msg(&self) -> Vec<(PublicKey, Self::CustomMessage)> {
107 //! #         unimplemented!()
108 //! #     }
109 //! }
110 //!
111 //! #[derive(Debug)]
112 //! pub struct Baz;
113 //!
114 //! macro_rules! baz_type_id {
115 //!     () => { 32770 }
116 //! }
117 //!
118 //! impl wire::Type for Baz {
119 //!     fn type_id(&self) -> u16 { baz_type_id!() }
120 //! }
121 //! impl Writeable for Baz {
122 //!     // ...
123 //! #     fn write<W: Writer>(&self, _: &mut W) -> Result<(), io::Error> {
124 //! #         unimplemented!()
125 //! #     }
126 //! }
127 //!
128 //! pub struct BazHandler;
129 //!
130 //! impl CustomMessageReader for BazHandler {
131 //!     // ...
132 //! #     type CustomMessage = Baz;
133 //! #     fn read<R: io::Read>(
134 //! #         &self, _message_type: u16, _buffer: &mut R
135 //! #     ) -> Result<Option<Self::CustomMessage>, DecodeError> {
136 //! #         unimplemented!()
137 //! #     }
138 //! }
139 //! impl CustomMessageHandler for BazHandler {
140 //!     // ...
141 //! #     fn handle_custom_message(
142 //! #         &self, _msg: Self::CustomMessage, _sender_node_id: &PublicKey
143 //! #     ) -> Result<(), LightningError> {
144 //! #         unimplemented!()
145 //! #     }
146 //! #     fn get_and_clear_pending_msg(&self) -> Vec<(PublicKey, Self::CustomMessage)> {
147 //! #         unimplemented!()
148 //! #     }
149 //! }
150 //!
151 //! # fn main() {
152 //! // The first crate may define a handler composing `FooHandler` and `BarHandler` and export the
153 //! // corresponding message type ids as a macro to use in further composition.
154 //!
155 //! composite_custom_message_handler!(
156 //!     pub struct FooBarHandler {
157 //!         foo: FooHandler,
158 //!         bar: BarHandler,
159 //!     }
160 //!
161 //!     pub enum FooBarMessage {
162 //!         Foo(foo_type_id!()),
163 //!         Bar(bar_type_id!()),
164 //!     }
165 //! );
166 //!
167 //! #[macro_export]
168 //! macro_rules! foo_bar_type_ids {
169 //!     () => { foo_type_id!() | bar_type_id!() }
170 //! }
171 //!
172 //! // Another crate can then define a handler further composing `FooBarHandler` with `BazHandler`
173 //! // and similarly export the composition of message type ids as a macro.
174 //!
175 //! composite_custom_message_handler!(
176 //!     pub struct FooBarBazHandler {
177 //!         foo_bar: FooBarHandler,
178 //!         baz: BazHandler,
179 //!     }
180 //!
181 //!     pub enum FooBarBazMessage {
182 //!         FooBar(foo_bar_type_ids!()),
183 //!         Baz(baz_type_id!()),
184 //!     }
185 //! );
186 //!
187 //! #[macro_export]
188 //! macro_rules! foo_bar_baz_type_ids {
189 //!     () => { foo_bar_type_ids!() | baz_type_id!() }
190 //! }
191 //! # }
192 //!```
193 //!
194 //! [BOLT 1]: https://github.com/lightning/bolts/blob/master/01-messaging.md
195 //! [`CustomMessageHandler`]: crate::lightning::ln::peer_handler::CustomMessageHandler
196
197 #![doc(test(no_crate_inject, attr(deny(warnings))))]
198
199 pub extern crate bitcoin;
200 pub extern crate lightning;
201
202 /// Defines a composite type implementing [`CustomMessageHandler`] (and therefore also implementing
203 /// [`CustomMessageReader`]), along with a corresponding enumerated custom message [`Type`], from
204 /// one or more previously defined custom message handlers.
205 ///
206 /// Useful for parameterizing [`PeerManager`] with custom message handling for one or more sets of
207 /// custom messages. Message type ids may be given as a valid `match` pattern, including ranges,
208 /// though using OR-ed literal patterns is preferred in order to catch unreachable code for
209 /// conflicting handlers.
210 ///
211 /// See [crate documentation] for example usage.
212 ///
213 /// [`CustomMessageHandler`]: crate::lightning::ln::peer_handler::CustomMessageHandler
214 /// [`CustomMessageReader`]: crate::lightning::ln::wire::CustomMessageReader
215 /// [`Type`]: crate::lightning::ln::wire::Type
216 /// [`PeerManager`]: crate::lightning::ln::peer_handler::PeerManager
217 /// [crate documentation]: self
218 #[macro_export]
219 macro_rules! composite_custom_message_handler {
220         (
221                 $handler_visibility:vis struct $handler:ident {
222                         $($field_visibility:vis $field:ident: $type:ty),* $(,)*
223                 }
224
225                 $message_visibility:vis enum $message:ident {
226                         $($variant:ident($pattern:pat)),* $(,)*
227                 }
228         ) => {
229                 #[allow(missing_docs)]
230                 $handler_visibility struct $handler {
231                         $(
232                                 $field_visibility $field: $type,
233                         )*
234                 }
235
236                 #[allow(missing_docs)]
237                 #[derive(Debug)]
238                 $message_visibility enum $message {
239                         $(
240                                 $variant(<$type as $crate::lightning::ln::wire::CustomMessageReader>::CustomMessage),
241                         )*
242                 }
243
244                 impl $crate::lightning::ln::peer_handler::CustomMessageHandler for $handler {
245                         fn handle_custom_message(
246                                 &self, msg: Self::CustomMessage, sender_node_id: &$crate::bitcoin::secp256k1::PublicKey
247                         ) -> Result<(), $crate::lightning::ln::msgs::LightningError> {
248                                 match msg {
249                                         $(
250                                                 $message::$variant(message) => {
251                                                         $crate::lightning::ln::peer_handler::CustomMessageHandler::handle_custom_message(
252                                                                 &self.$field, message, sender_node_id
253                                                         )
254                                                 },
255                                         )*
256                                 }
257                         }
258
259                         fn get_and_clear_pending_msg(&self) -> Vec<($crate::bitcoin::secp256k1::PublicKey, Self::CustomMessage)> {
260                                 vec![].into_iter()
261                                         $(
262                                                 .chain(
263                                                         self.$field
264                                                                 .get_and_clear_pending_msg()
265                                                                 .into_iter()
266                                                                 .map(|(pubkey, message)| (pubkey, $message::$variant(message)))
267                                                 )
268                                         )*
269                                         .collect()
270                         }
271                 }
272
273                 impl $crate::lightning::ln::wire::CustomMessageReader for $handler {
274                         type CustomMessage = $message;
275                         fn read<R: $crate::lightning::io::Read>(
276                                 &self, message_type: u16, buffer: &mut R
277                         ) -> Result<Option<Self::CustomMessage>, $crate::lightning::ln::msgs::DecodeError> {
278                                 match message_type {
279                                         $(
280                                                 $pattern => match <$type>::read(&self.$field, message_type, buffer)? {
281                                                         None => unreachable!(),
282                                                         Some(message) => Ok(Some($message::$variant(message))),
283                                                 },
284                                         )*
285                                         _ => Ok(None),
286                                 }
287                         }
288                 }
289
290                 impl $crate::lightning::ln::wire::Type for $message {
291                         fn type_id(&self) -> u16 {
292                                 match self {
293                                         $(
294                                                 Self::$variant(message) => message.type_id(),
295                                         )*
296                                 }
297                         }
298                 }
299
300                 impl $crate::lightning::util::ser::Writeable for $message {
301                         fn write<W: $crate::lightning::util::ser::Writer>(&self, writer: &mut W) -> Result<(), $crate::lightning::io::Error> {
302                                 match self {
303                                         $(
304                                                 Self::$variant(message) => message.write(writer),
305                                         )*
306                                 }
307                         }
308                 }
309         }
310 }