Use BaseEventHandler to expose async event handling on InvoicePayer

We introduce a new sealed trait BaseEventHandler that has a blanket
implementation for any T. Since the trait cannot be implemented outside
of the crate, this allow us to expose specific implementations of
InvoicePayer that allow for synchronous and asynchronous event handling.

Author: wpaulino

lightning-invoice/src/payment.rs

@@ -157,6 +157,7 @@ use secp256k1::PublicKey;
 
 use core::fmt;
 use core::fmt::{Debug, Display, Formatter};
+use core::future::Future;
 use core::ops::Deref;
 use core::time::Duration;
 #[cfg(feature = "std")]
@@ -176,8 +177,15 @@ use crate::time_utils;
 #[cfg(feature = "no-std")]
 type ConfiguredTime = time_utils::Eternity;
 
+/// Sealed trait with a blanket implementation to allow both sync and async implementations of event
+/// handling to exist within the InvoicePayer.
+mod sealed {
+	pub trait BaseEventHandler {}
+	impl<T> BaseEventHandler for T {}
+}
+
 /// (C-not exported) generally all users should use the [`InvoicePayer`] type alias.
-pub struct InvoicePayerUsingTime<P: Deref, R: ScoringRouter, L: Deref, E: EventHandler, T: Time>
+pub struct InvoicePayerUsingTime<P: Deref, R: ScoringRouter, L: Deref, E: sealed::BaseEventHandler, T: Time>
 where
 	P::Target: Payer,
 	L::Target: Logger,
@@ -342,7 +350,7 @@ pub enum PaymentError {
 	Sending(PaymentSendFailure),
 }
 
-impl<P: Deref, R: ScoringRouter, L: Deref, E: EventHandler, T: Time> InvoicePayerUsingTime<P, R, L, E, T>
+impl<P: Deref, R: ScoringRouter, L: Deref, E: sealed::BaseEventHandler, T: Time> InvoicePayerUsingTime<P, R, L, E, T>
 where
 	P::Target: Payer,
 	L::Target: Logger,
@@ -744,12 +752,12 @@ fn has_expired(route_params: &RouteParameters) -> bool {
 	} else { false }
 }
 
-impl<P: Deref, R: ScoringRouter, L: Deref, E: EventHandler, T: Time> EventHandler for InvoicePayerUsingTime<P, R, L, E, T>
+impl<P: Deref, R: ScoringRouter, L: Deref, E: sealed::BaseEventHandler, T: Time> InvoicePayerUsingTime<P, R, L, E, T>
 where
 	P::Target: Payer,
 	L::Target: Logger,
 {
-	fn handle_event(&self, event: Event) {
+	fn handle_event_internal(&self, event: Event) -> Option<Event> {
 		match event {
 			Event::PaymentPathFailed { payment_hash, ref path, ..  }
 			| Event::PaymentPathSuccessful { ref path, payment_hash: Some(payment_hash), .. }
@@ -779,7 +787,7 @@ where
 					self.payer.abandon_payment(payment_id.unwrap());
 				} else if self.retry_payment(payment_id.unwrap(), payment_hash, retry.as_ref().unwrap()).is_ok() {
 					// We retried at least somewhat, don't provide the PaymentPathFailed event to the user.
-					return;
+					return None;
 				} else {
 					self.payer.abandon_payment(payment_id.unwrap());
 				}
@@ -814,7 +822,35 @@ where
 		}
 
 		// Delegate to the decorated event handler unless the payment is retried.
-		self.event_handler.handle_event(event)
+		Some(event)
+	}
+}
+
+impl<P: Deref, R: ScoringRouter, L: Deref, E: EventHandler, T: Time>
+	EventHandler for InvoicePayerUsingTime<P, R, L, E, T>
+where
+	P::Target: Payer,
+	L::Target: Logger,
+{
+	fn handle_event(&self, event: Event) {
+		if let Some(event) = self.handle_event_internal(event) {
+			self.event_handler.handle_event(event)
+		}
+	}
+}
+
+impl<P: Deref, R: ScoringRouter, L: Deref, T: Time, F: Future, H: Fn(Event) -> F>
+	InvoicePayerUsingTime<P, R, L, H, T>
+where
+	P::Target: Payer,
+	L::Target: Logger,
+{
+	/// Intercepts events required by the [`InvoicePayer`] and forwards them to the underlying event
+	/// handler, if necessary, to handle them asynchronously.
+	pub async fn handle_event_async(&self, event: Event) {
+		if let Some(event) = self.handle_event_internal(event) {
+			(self.event_handler)(event).await;
+		}
 	}
 }
 
@@ -980,7 +1016,7 @@ mod tests {
 
 	#[test]
 	fn pays_invoice_on_partial_failure() {
-		let event_handler = |_: _| { panic!() };
+		let event_handler = |_: Event| { panic!() };
 
 		let payment_preimage = PaymentPreimage([1; 32]);
 		let invoice = invoice(payment_preimage);
@@ -1184,7 +1220,7 @@ mod tests {
 	#[test]
 	fn fails_paying_invoice_after_expiration() {
 		let event_handled = core::cell::RefCell::new(false);
-		let event_handler = |_: _| { *event_handled.borrow_mut() = true; };
+		let event_handler = |_: Event| { *event_handled.borrow_mut() = true; };
 
 		let payer = TestPayer::new();
 		let router = TestRouter::new(TestScorer::new());
@@ -1360,7 +1396,7 @@ mod tests {
 		let router = FailingRouter {};
 		let logger = TestLogger::new();
 		let invoice_payer =
-			InvoicePayer::new(&payer, router, &logger, |_: _| {}, Retry::Attempts(0));
+			InvoicePayer::new(&payer, router, &logger, |_: Event| {}, Retry::Attempts(0));
 
 		let payment_preimage = PaymentPreimage([1; 32]);
 		let invoice = invoice(payment_preimage);
@@ -1383,7 +1419,7 @@ mod tests {
 		let router = TestRouter::new(TestScorer::new());
 		let logger = TestLogger::new();
 		let invoice_payer =
-			InvoicePayer::new(&payer, router, &logger, |_: _| {}, Retry::Attempts(0));
+			InvoicePayer::new(&payer, router, &logger, |_: Event| {}, Retry::Attempts(0));
 
 		match invoice_payer.pay_invoice(&invoice) {
 			Err(PaymentError::Sending(_)) => {},
@@ -1422,7 +1458,7 @@ mod tests {
 	#[test]
 	fn fails_paying_zero_value_invoice_with_amount() {
 		let event_handled = core::cell::RefCell::new(false);
-		let event_handler = |_: _| { *event_handled.borrow_mut() = true; };
+		let event_handler = |_: Event| { *event_handled.borrow_mut() = true; };
 
 		let payer = TestPayer::new();
 		let router = TestRouter::new(TestScorer::new());
@@ -1732,7 +1768,7 @@ mod tests {
 	#[test]
 	fn accounts_for_some_inflight_htlcs_sent_during_partial_failure() {
 		let event_handled = core::cell::RefCell::new(false);
-		let event_handler = |_: _| { *event_handled.borrow_mut() = true; };
+		let event_handler = |_: Event| { *event_handled.borrow_mut() = true; };
 
 		let payment_preimage = PaymentPreimage([1; 32]);
 		let invoice_to_pay = invoice(payment_preimage);
@@ -1763,7 +1799,7 @@ mod tests {
 	#[test]
 	fn accounts_for_all_inflight_htlcs_sent_during_partial_failure() {
 		let event_handled = core::cell::RefCell::new(false);
-		let event_handler = |_: _| { *event_handled.borrow_mut() = true; };
+		let event_handler = |_: Event| { *event_handled.borrow_mut() = true; };
 
 		let payment_preimage = PaymentPreimage([1; 32]);
 		let invoice_to_pay = invoice(payment_preimage);
@@ -2260,7 +2296,7 @@ mod tests {
 		route.paths[1][0].fee_msat = 50_000_000;
 		router.expect_find_route(Ok(route.clone()));
 
-		let event_handler = |_: _| { panic!(); };
+		let event_handler = |_: Event| { panic!(); };
 		let invoice_payer = InvoicePayer::new(nodes[0].node, router, nodes[0].logger, event_handler, Retry::Attempts(1));
 
 		assert!(invoice_payer.pay_invoice(&create_invoice_from_channelmanager_and_duration_since_epoch(
@@ -2305,7 +2341,7 @@ mod tests {
 		route.paths[1][0].fee_msat = 50_000_001;
 		router.expect_find_route(Ok(route.clone()));
 
-		let event_handler = |_: _| { panic!(); };
+		let event_handler = |_: Event| { panic!(); };
 		let invoice_payer = InvoicePayer::new(nodes[0].node, router, nodes[0].logger, event_handler, Retry::Attempts(1));
 
 		assert!(invoice_payer.pay_invoice(&create_invoice_from_channelmanager_and_duration_since_epoch(