_ Git - rust-lightning/blob - lightning/src/ln/wire.rs

   1 //! Wire encoding/decoding for Lightning messages according to [BOLT #1].
   2 //!
   3 //! Messages known by this module can be read from the wire using [`read`].
   4 //! The [`Message`] enum returned by [`read`] wraps the decoded message or the message type (if
   5 //! unknown) to use with pattern matching.
   6 //!
   7 //! Messages implementing the [`Encode`] trait define a message type and can be sent over the wire
   8 //! using [`write`].
   9 //!
  10 //! [BOLT #1]: https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md
  11 //! [`read`]: fn.read.html
  12 //! [`write`]: fn.write.html
  13 //! [`Encode`]: trait.Encode.html
  14 //! [`Message`]: enum.Message.html
  15
  16 use ln::msgs;
  17 use util::ser::{Readable, Writeable, Writer};
  18
  19 /// A Lightning message returned by [`read`] when decoding bytes received over the wire. Each
  20 /// variant contains a message from [`ln::msgs`] or otherwise the message type if unknown.
  21 ///
  22 /// [`read`]: fn.read.html
  23 /// [`ln::msgs`]: ../msgs/index.html
  24 #[allow(missing_docs)]
  25 pub enum Message {
  26         Init(msgs::Init),
  27         Error(msgs::ErrorMessage),
  28         Ping(msgs::Ping),
  29         Pong(msgs::Pong),
  30         OpenChannel(msgs::OpenChannel),
  31         AcceptChannel(msgs::AcceptChannel),
  32         FundingCreated(msgs::FundingCreated),
  33         FundingSigned(msgs::FundingSigned),
  34         FundingLocked(msgs::FundingLocked),
  35         Shutdown(msgs::Shutdown),
  36         ClosingSigned(msgs::ClosingSigned),
  37         UpdateAddHTLC(msgs::UpdateAddHTLC),
  38         UpdateFulfillHTLC(msgs::UpdateFulfillHTLC),
  39         UpdateFailHTLC(msgs::UpdateFailHTLC),
  40         UpdateFailMalformedHTLC(msgs::UpdateFailMalformedHTLC),
  41         CommitmentSigned(msgs::CommitmentSigned),
  42         RevokeAndACK(msgs::RevokeAndACK),
  43         UpdateFee(msgs::UpdateFee),
  44         ChannelReestablish(msgs::ChannelReestablish),
  45         AnnouncementSignatures(msgs::AnnouncementSignatures),
  46         ChannelAnnouncement(msgs::ChannelAnnouncement),
  47         NodeAnnouncement(msgs::NodeAnnouncement),
  48         ChannelUpdate(msgs::ChannelUpdate),
  49         /// A message that could not be decoded because its type is unknown.
  50         Unknown(u16),
  51 }
  52
  53 impl Message {
  54         /// Returns the type that was used to decode the message payload.
  55         pub fn type_id(&self) -> u16 {
  56                 match self {
  57                         &Message::Init(ref msg) => msg.type_id(),
  58                         &Message::Error(ref msg) => msg.type_id(),
  59                         &Message::Ping(ref msg) => msg.type_id(),
  60                         &Message::Pong(ref msg) => msg.type_id(),
  61                         &Message::OpenChannel(ref msg) => msg.type_id(),
  62                         &Message::AcceptChannel(ref msg) => msg.type_id(),
  63                         &Message::FundingCreated(ref msg) => msg.type_id(),
  64                         &Message::FundingSigned(ref msg) => msg.type_id(),
  65                         &Message::FundingLocked(ref msg) => msg.type_id(),
  66                         &Message::Shutdown(ref msg) => msg.type_id(),
  67                         &Message::ClosingSigned(ref msg) => msg.type_id(),
  68                         &Message::UpdateAddHTLC(ref msg) => msg.type_id(),
  69                         &Message::UpdateFulfillHTLC(ref msg) => msg.type_id(),
  70                         &Message::UpdateFailHTLC(ref msg) => msg.type_id(),
  71                         &Message::UpdateFailMalformedHTLC(ref msg) => msg.type_id(),
  72                         &Message::CommitmentSigned(ref msg) => msg.type_id(),
  73                         &Message::RevokeAndACK(ref msg) => msg.type_id(),
  74                         &Message::UpdateFee(ref msg) => msg.type_id(),
  75                         &Message::ChannelReestablish(ref msg) => msg.type_id(),
  76                         &Message::AnnouncementSignatures(ref msg) => msg.type_id(),
  77                         &Message::ChannelAnnouncement(ref msg) => msg.type_id(),
  78                         &Message::NodeAnnouncement(ref msg) => msg.type_id(),
  79                         &Message::ChannelUpdate(ref msg) => msg.type_id(),
  80                         &Message::Unknown(type_id) => type_id,
  81                 }
  82         }
  83 }
  84
  85 /// Reads a message from the data buffer consisting of a 2-byte big-endian type and a
  86 /// variable-length payload conforming to the type.
  87 ///
  88 /// # Errors
  89 ///
  90 /// Returns an error if the message payload code not be decoded as the specified type.
  91 pub fn read<R: ::std::io::Read>(buffer: &mut R) -> Result<Message, msgs::DecodeError> {
  92         let message_type = <u16 as Readable<R>>::read(buffer)?;
  93         match message_type {
  94                 msgs::Init::TYPE => {
  95                         Ok(Message::Init(Readable::read(buffer)?))
  96                 },
  97                 msgs::ErrorMessage::TYPE => {
  98                         Ok(Message::Error(Readable::read(buffer)?))
  99                 },
 100                 msgs::Ping::TYPE => {
 101                         Ok(Message::Ping(Readable::read(buffer)?))
 102                 },
 103                 msgs::Pong::TYPE => {
 104                         Ok(Message::Pong(Readable::read(buffer)?))
 105                 },
 106                 msgs::OpenChannel::TYPE => {
 107                         Ok(Message::OpenChannel(Readable::read(buffer)?))
 108                 },
 109                 msgs::AcceptChannel::TYPE => {
 110                         Ok(Message::AcceptChannel(Readable::read(buffer)?))
 111                 },
 112                 msgs::FundingCreated::TYPE => {
 113                         Ok(Message::FundingCreated(Readable::read(buffer)?))
 114                 },
 115                 msgs::FundingSigned::TYPE => {
 116                         Ok(Message::FundingSigned(Readable::read(buffer)?))
 117                 },
 118                 msgs::FundingLocked::TYPE => {
 119                         Ok(Message::FundingLocked(Readable::read(buffer)?))
 120                 },
 121                 msgs::Shutdown::TYPE => {
 122                         Ok(Message::Shutdown(Readable::read(buffer)?))
 123                 },
 124                 msgs::ClosingSigned::TYPE => {
 125                         Ok(Message::ClosingSigned(Readable::read(buffer)?))
 126                 },
 127                 msgs::UpdateAddHTLC::TYPE => {
 128                         Ok(Message::UpdateAddHTLC(Readable::read(buffer)?))
 129                 },
 130                 msgs::UpdateFulfillHTLC::TYPE => {
 131                         Ok(Message::UpdateFulfillHTLC(Readable::read(buffer)?))
 132                 },
 133                 msgs::UpdateFailHTLC::TYPE => {
 134                         Ok(Message::UpdateFailHTLC(Readable::read(buffer)?))
 135                 },
 136                 msgs::UpdateFailMalformedHTLC::TYPE => {
 137                         Ok(Message::UpdateFailMalformedHTLC(Readable::read(buffer)?))
 138                 },
 139                 msgs::CommitmentSigned::TYPE => {
 140                         Ok(Message::CommitmentSigned(Readable::read(buffer)?))
 141                 },
 142                 msgs::RevokeAndACK::TYPE => {
 143                         Ok(Message::RevokeAndACK(Readable::read(buffer)?))
 144                 },
 145                 msgs::UpdateFee::TYPE => {
 146                         Ok(Message::UpdateFee(Readable::read(buffer)?))
 147                 },
 148                 msgs::ChannelReestablish::TYPE => {
 149                         Ok(Message::ChannelReestablish(Readable::read(buffer)?))
 150                 },
 151                 msgs::AnnouncementSignatures::TYPE => {
 152                         Ok(Message::AnnouncementSignatures(Readable::read(buffer)?))
 153                 },
 154                 msgs::ChannelAnnouncement::TYPE => {
 155                         Ok(Message::ChannelAnnouncement(Readable::read(buffer)?))
 156                 },
 157                 msgs::NodeAnnouncement::TYPE => {
 158                         Ok(Message::NodeAnnouncement(Readable::read(buffer)?))
 159                 },
 160                 msgs::ChannelUpdate::TYPE => {
 161                         Ok(Message::ChannelUpdate(Readable::read(buffer)?))
 162                 },
 163                 _ => {
 164                         Ok(Message::Unknown(message_type))
 165                 },
 166         }
 167 }
 168
 169 /// Writes a message to the data buffer encoded as a 2-byte big-endian type and a variable-length
 170 /// payload.
 171 ///
 172 /// # Errors
 173 ///
 174 /// Returns an I/O error if the write could not be completed.
 175 pub fn write<M: Encode + Writeable, W: Writer>(message: &M, buffer: &mut W) -> Result<(), ::std::io::Error> {
 176         M::TYPE.write(buffer)?;
 177         message.write(buffer)
 178 }
 179
 180 /// Defines a type-identified encoding for sending messages over the wire.
 181 ///
 182 /// Messages implementing this trait specify a type and must be [`Writeable`] to use with [`write`].
 183 ///
 184 /// [`Writeable`]: ../../util/ser/trait.Writeable.html
 185 /// [`write`]: fn.write.html
 186 pub trait Encode {
 187         /// The type identifying the message payload.
 188         const TYPE: u16;
 189
 190         /// Returns the type identifying the message payload. Convenience method for accessing
 191         /// [`TYPE`](TYPE).
 192         fn type_id(&self) -> u16 {
 193                 Self::TYPE
 194         }
 195 }
 196
 197 impl Encode for msgs::Init {
 198         const TYPE: u16 = 16;
 199 }
 200
 201 impl Encode for msgs::ErrorMessage {
 202         const TYPE: u16 = 17;
 203 }
 204
 205 impl Encode for msgs::Ping {
 206         const TYPE: u16 = 18;
 207 }
 208
 209 impl Encode for msgs::Pong {
 210         const TYPE: u16 = 19;
 211 }
 212
 213 impl Encode for msgs::OpenChannel {
 214         const TYPE: u16 = 32;
 215 }
 216
 217 impl Encode for msgs::AcceptChannel {
 218         const TYPE: u16 = 33;
 219 }
 220
 221 impl Encode for msgs::FundingCreated {
 222         const TYPE: u16 = 34;
 223 }
 224
 225 impl Encode for msgs::FundingSigned {
 226         const TYPE: u16 = 35;
 227 }
 228
 229 impl Encode for msgs::FundingLocked {
 230         const TYPE: u16 = 36;
 231 }
 232
 233 impl Encode for msgs::Shutdown {
 234         const TYPE: u16 = 38;
 235 }
 236
 237 impl Encode for msgs::ClosingSigned {
 238         const TYPE: u16 = 39;
 239 }
 240
 241 impl Encode for msgs::UpdateAddHTLC {
 242         const TYPE: u16 = 128;
 243 }
 244
 245 impl Encode for msgs::UpdateFulfillHTLC {
 246         const TYPE: u16 = 130;
 247 }
 248
 249 impl Encode for msgs::UpdateFailHTLC {
 250         const TYPE: u16 = 131;
 251 }
 252
 253 impl Encode for msgs::UpdateFailMalformedHTLC {
 254         const TYPE: u16 = 135;
 255 }
 256
 257 impl Encode for msgs::CommitmentSigned {
 258         const TYPE: u16 = 132;
 259 }
 260
 261 impl Encode for msgs::RevokeAndACK {
 262         const TYPE: u16 = 133;
 263 }
 264
 265 impl Encode for msgs::UpdateFee {
 266         const TYPE: u16 = 134;
 267 }
 268
 269 impl Encode for msgs::ChannelReestablish {
 270         const TYPE: u16 = 136;
 271 }
 272
 273 impl Encode for msgs::AnnouncementSignatures {
 274         const TYPE: u16 = 259;
 275 }
 276
 277 impl Encode for msgs::ChannelAnnouncement {
 278         const TYPE: u16 = 256;
 279 }
 280
 281 impl Encode for msgs::NodeAnnouncement {
 282         const TYPE: u16 = 257;
 283 }
 284
 285 impl Encode for msgs::ChannelUpdate {
 286         const TYPE: u16 = 258;
 287 }
 288
 289 #[cfg(test)]
 290 mod tests {
 291         use super::*;
 292         use util::byte_utils;
 293
 294         // Big-endian wire encoding of Pong message (type = 19, byteslen = 2).
 295         const ENCODED_PONG: [u8; 6] = [0u8, 19u8, 0u8, 2u8, 0u8, 0u8];
 296
 297         #[test]
 298         fn read_empty_buffer() {
 299                 let buffer = [];
 300                 let mut reader = ::std::io::Cursor::new(buffer);
 301                 assert!(read(&mut reader).is_err());
 302         }
 303
 304         #[test]
 305         fn read_incomplete_type() {
 306                 let buffer = &ENCODED_PONG[..1];
 307                 let mut reader = ::std::io::Cursor::new(buffer);
 308                 assert!(read(&mut reader).is_err());
 309         }
 310
 311         #[test]
 312         fn read_empty_payload() {
 313                 let buffer = &ENCODED_PONG[..2];
 314                 let mut reader = ::std::io::Cursor::new(buffer);
 315                 assert!(read(&mut reader).is_err());
 316         }
 317
 318         #[test]
 319         fn read_invalid_message() {
 320                 let buffer = &ENCODED_PONG[..4];
 321                 let mut reader = ::std::io::Cursor::new(buffer);
 322                 assert!(read(&mut reader).is_err());
 323         }
 324
 325         #[test]
 326         fn read_known_message() {
 327                 let buffer = &ENCODED_PONG[..];
 328                 let mut reader = ::std::io::Cursor::new(buffer);
 329                 let message = read(&mut reader).unwrap();
 330                 match message {
 331                         Message::Pong(_) => (),
 332                         _ => panic!("Expected pong message; found message type: {}", message.type_id()),
 333                 }
 334         }
 335
 336         #[test]
 337         fn read_unknown_message() {
 338                 let buffer = &byte_utils::be16_to_array(::std::u16::MAX);
 339                 let mut reader = ::std::io::Cursor::new(buffer);
 340                 let message = read(&mut reader).unwrap();
 341                 match message {
 342                         Message::Unknown(::std::u16::MAX) => (),
 343                         _ => panic!("Expected message type {}; found: {}", ::std::u16::MAX, message.type_id()),
 344                 }
 345         }
 346
 347         #[test]
 348         fn write_message_with_type() {
 349                 let message = msgs::Pong { byteslen: 2u16 };
 350                 let mut buffer = Vec::new();
 351                 assert!(write(&message, &mut buffer).is_ok());
 352
 353                 let type_length = ::std::mem::size_of::<u16>();
 354                 let (type_bytes, payload_bytes) = buffer.split_at(type_length);
 355                 assert_eq!(byte_utils::slice_to_be16(type_bytes), msgs::Pong::TYPE);
 356                 assert_eq!(payload_bytes, &ENCODED_PONG[type_length..]);
 357         }
 358
 359         #[test]
 360         fn read_message_encoded_with_write() {
 361                 let message = msgs::Pong { byteslen: 2u16 };
 362                 let mut buffer = Vec::new();
 363                 assert!(write(&message, &mut buffer).is_ok());
 364
 365                 let mut reader = ::std::io::Cursor::new(buffer);
 366                 let decoded_message = read(&mut reader).unwrap();
 367                 match decoded_message {
 368                         Message::Pong(msgs::Pong { byteslen: 2u16 }) => (),
 369                         Message::Pong(msgs::Pong { byteslen }) => {
 370                                 panic!("Expected byteslen {}; found: {}", message.byteslen, byteslen);
 371                         },
 372                         _ => panic!("Expected pong message; found message type: {}", decoded_message.type_id()),
 373                 }
 374         }
 375 }