f - Expose an async / Future-based async receive offer API

Replace the blocking `await_async_receive_offer(Duration)` with an
`async fn await_async_receive_offer(&self) -> Result<Offer, ()>` and a
new `get_async_receive_offer_ready_future() -> Future` helper.

Async callers can `.await` the offer directly; synchronous callers can
fetch the underlying [`Future`] and call `wait_timeout` on it, which
lets them combine with whatever timing primitive their runtime
provides.

Co-Authored-By: HAL 9000

Author: tnull

lightning/src/ln/channelmanager.rs

@@ -5884,21 +5884,36 @@ impl<
 		})
 	}
 
-	/// Waits for an async receive offer to become ready after the interactive static-invoice
-	/// protocol completes.
+	/// Returns once an async receive offer is ready after the interactive static-invoice
+	/// protocol completes, or immediately if one is already available.
+	///
+	/// Callers that need a timeout can combine this future with their runtime's timeout
+	/// primitive. Synchronous callers should instead fetch the underlying [`Future`] via
+	/// [`Self::get_async_receive_offer_ready_future`] and call [`Future::wait_timeout`] on it.
+	///
+	/// [`Future`]: crate::util::wakers::Future
+	/// [`Future::wait_timeout`]: crate::util::wakers::Future::wait_timeout
 	#[cfg(feature = "std")]
-	pub fn await_async_receive_offer(&self, max_wait: Duration) -> Result<Offer, ()> {
+	pub async fn await_async_receive_offer(&self) -> Result<Offer, ()> {
 		if let Ok(offer) = self.get_async_receive_offer() {
 			return Ok(offer);
 		}
 
-		if !self.flow.wait_for_async_receive_offer_ready(max_wait) {
-			return Err(());
-		}
-
+		self.flow.get_async_receive_offer_ready_future().await;
 		self.get_async_receive_offer()
 	}
 
+	/// Returns a [`Future`] that completes when an async receive offer is ready.
+	///
+	/// See [`OffersMessageFlow::get_async_receive_offer_ready_future`] for details.
+	///
+	/// [`Future`]: crate::util::wakers::Future
+	/// [`OffersMessageFlow::get_async_receive_offer_ready_future`]: crate::offers::flow::OffersMessageFlow::get_async_receive_offer_ready_future
+	#[cfg(feature = "std")]
+	pub fn get_async_receive_offer_ready_future(&self) -> crate::util::wakers::Future {
+		self.flow.get_async_receive_offer_ready_future()
+	}
+
 	/// Should be called after handling an [`Event::PersistStaticInvoice`], where the `Responder`
 	/// comes from [`Event::PersistStaticInvoice::invoice_persisted_path`].
 	pub fn static_invoice_persisted(&self, invoice_persisted_path: Responder) {

lightning/src/offers/flow.rs

@@ -62,6 +62,8 @@ use crate::types::payment::{PaymentHash, PaymentSecret};
 use crate::util::logger::Logger;
 use crate::util::ser::Writeable;
 #[cfg(feature = "std")]
+use crate::util::wakers::Future;
+#[cfg(feature = "std")]
 use crate::util::wakers::Notifier;
 
 /// A BOLT12 offers code and flow utility provider, which facilitates
@@ -1719,9 +1721,15 @@ impl<MR: MessageRouter, L: Logger> OffersMessageFlow<MR, L> {
 		updated
 	}
 
+	/// Returns a [`Future`] that completes when an async receive offer is ready, i.e., after the
+	/// interactive static-invoice protocol completes.
+	///
+	/// Callers can either `.await` the returned [`Future`] in an async context or call
+	/// [`Future::wait_timeout`] from a synchronous context. After it completes, use
+	/// [`Self::get_async_receive_offer`] to retrieve the offer.
 	#[cfg(feature = "std")]
-	pub(crate) fn wait_for_async_receive_offer_ready(&self, max_wait: Duration) -> bool {
-		self.async_receive_offer_ready_notifier.get_future().wait_timeout(max_wait)
+	pub fn get_async_receive_offer_ready_future(&self) -> Future {
+		self.async_receive_offer_ready_notifier.get_future()
 	}
 
 	/// Get the encoded [`AsyncReceiveOfferCache`] for persistence.