Mark `ChannelManager::send_payment_with_route` as deprecated

We probably should have done this long ago a release or two after
adding `send_payment`, but we didn't and the second best time is
now.

`send_payment_with_route` has particularly hard to use retry
semantics that make it unsuitable for real use. Once we get the
last of our users off of it, we'll want to remove it (or at least
mark it test-only), but we should start by deprecating it.

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index 28c40856f50cfa52ca299534d5695c8a69155116..3a2d62497a420830e642181116daf9199a7bedc2 100644 (file)
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -4093,6 +4093,10 @@ where
 
        /// Sends a payment along a given route.
        ///
+       /// This method is *DEPRECATED*, use [`Self::send_payment`] instead. If you wish to fix the
+       /// route for a payment, do so by matching the [`PaymentId`] passed to
+       /// [`Router::find_route_with_id`].
+       ///
        /// Value parameters are provided via the last hop in route, see documentation for [`RouteHop`]
        /// fields for more info.
        ///
@@ -4142,6 +4146,7 @@ where
        /// [`UpdateHTLCs`]: events::MessageSendEvent::UpdateHTLCs
        /// [`PeerManager::process_events`]: crate::ln::peer_handler::PeerManager::process_events
        /// [`ChannelMonitorUpdateStatus::InProgress`]: crate::chain::ChannelMonitorUpdateStatus::InProgress
+       #[cfg_attr(not(any(test, feature = "_test_utils")), deprecated(note = "Use `send_payment` instead"))]
        pub fn send_payment_with_route(&self, route: &Route, payment_hash: PaymentHash, recipient_onion: RecipientOnionFields, payment_id: PaymentId) -> Result<(), PaymentSendFailure> {
                let best_block_height = self.best_block.read().unwrap().height;
                let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);