Implement clear packets command

.changelog/unreleased/improvements/ibc-relayer-cli/1834-clear-packets-cmd.md

@@ -0,0 +1,3 @@
+- Added `clear packets` command, combining the effects of
+  `tx raw packet-recv` and `tx raw packet-ack`.
+  ([#1834](https://github.com/informalsystems/ibc-rs/pull/1834))

relayer-cli/src/commands.rs

@@ -5,6 +5,7 @@
 //! See the `impl Configurable` below for how to specify the path to the
 //! application's configuration file.
 
+mod clear;
 mod completions;
 mod config;
 mod create;
@@ -20,9 +21,10 @@ mod upgrade;
 mod version;
 
 use self::{
-    completions::CompletionsCmd, config::ConfigCmd, create::CreateCmds, health::HealthCheckCmd,
-    keys::KeysCmd, listen::ListenCmd, misbehaviour::MisbehaviourCmd, query::QueryCmd,
-    start::StartCmd, tx::TxCmd, update::UpdateCmds, upgrade::UpgradeCmds, version::VersionCmd,
+    clear::ClearCmds, completions::CompletionsCmd, config::ConfigCmd, create::CreateCmds,
+    health::HealthCheckCmd, keys::KeysCmd, listen::ListenCmd, misbehaviour::MisbehaviourCmd,
+    query::QueryCmd, start::StartCmd, tx::TxCmd, update::UpdateCmds, upgrade::UpgradeCmds,
+    version::VersionCmd,
 };
 
 use core::time::Duration;
@@ -63,6 +65,10 @@ pub enum CliCmd {
     #[clap(subcommand)]
     Upgrade(UpgradeCmds),
 
+    /// Clear objects, such as outstanding packets on a channel.
+    #[clap(subcommand)]
+    Clear(ClearCmds),
+
     /// Start the relayer in multi-chain mode.
     ///
     /// Relays packets and open handshake messages between all chains in the config.

relayer-cli/src/commands/clear.rs

@@ -0,0 +1,98 @@
+use abscissa_core::clap::Parser;
+use abscissa_core::{Command, Runnable};
+
+use ibc::core::ics24_host::identifier::{ChainId, ChannelId, PortId};
+use ibc::events::IbcEvent;
+use ibc_relayer::link::error::LinkError;
+use ibc_relayer::link::{Link, LinkParameters};
+
+use crate::application::app_config;
+use crate::cli_utils::ChainHandlePair;
+use crate::conclude::Output;
+use crate::error::Error;
+
+/// `clear` subcommands
+#[derive(Command, Debug, Parser, Runnable)]
+pub enum ClearCmds {
+    /// Clear outstanding packets (i.e., packet-recv and packet-ack)
+    /// on a given channel in both directions.
+    Packets(ClearPacketsCmd),
+}
+
+#[derive(Debug, Parser)]
+pub struct ClearPacketsCmd {
+    #[clap(required = true, help = "identifier of the destination chain")]
+    dst_chain_id: ChainId,
+
+    #[clap(required = true, help = "identifier of the source chain")]
+    src_chain_id: ChainId,
+
+    #[clap(required = true, help = "identifier of the source port")]
+    src_port_id: PortId,
+
+    #[clap(required = true, help = "identifier of the source channel")]
+    src_channel_id: ChannelId,
+}
+
+impl Runnable for ClearPacketsCmd {
+    fn run(&self) {
+        let config = app_config();
+
+        let chains = match ChainHandlePair::spawn(&config, &self.src_chain_id, &self.dst_chain_id) {
+            Ok(chains) => chains,
+            Err(e) => Output::error(format!("{}", e)).exit(),
+        };
+
+        let mut ev_list = vec![];
+
+        // Construct links in both directions.
+        // Some of the checks in the two Link constructor calls may be redundant;
+        // going slowly, but reliably.
+        let opts = LinkParameters {
+            src_port_id: self.src_port_id.clone(),
+            src_channel_id: self.src_channel_id.clone(),
+        };
+        let fwd_link =
+            match Link::new_from_opts(chains.src.clone(), chains.dst.clone(), opts, false) {
+                Ok(link) => link,
+                Err(e) => Output::error(format!("{}", e)).exit(),
+            };
+        let opts = LinkParameters {
+            src_port_id: fwd_link.a_to_b.dst_port_id().clone(),
+            src_channel_id: fwd_link.a_to_b.dst_channel_id().clone(),
+        };
+        let rev_link = match Link::new_from_opts(chains.dst, chains.src, opts, false) {
+            Ok(link) => link,
+            Err(e) => Output::error(format!("{}", e)).exit(),
+        };
+
+        // Schedule RecvPacket messages for pending packets in both directions.
+        // This may produce pending acks which will be processed in the next phase.
+        run_and_collect_events(&mut ev_list, || {
+            fwd_link.build_and_send_recv_packet_messages()
+        });
+        run_and_collect_events(&mut ev_list, || {
+            rev_link.build_and_send_recv_packet_messages()
+        });
+
+        // Schedule AckPacket messages in both directions.
+        run_and_collect_events(&mut ev_list, || {
+            fwd_link.build_and_send_ack_packet_messages()
+        });
+        run_and_collect_events(&mut ev_list, || {
+            rev_link.build_and_send_ack_packet_messages()
+        });
+
+        Output::success(ev_list).exit()
+    }
+}
+
+fn run_and_collect_events<F>(ev_list: &mut Vec<IbcEvent>, f: F)
+where
+    F: FnOnce() -> Result<Vec<IbcEvent>, LinkError>,
+{
+    match f() {
+        Ok(mut ev) => ev_list.append(&mut ev),
+        Err(e) => Output::error(Error::link(e)).exit(),
+    };
+}

relayer-cli/src/commands/tx/packet.rs

@@ -38,7 +38,7 @@ impl Runnable for TxRawPacketRecvCmd {
             src_port_id: self.src_port_id.clone(),
             src_channel_id: self.src_channel_id.clone(),
         };
-        let mut link = match Link::new_from_opts(chains.src, chains.dst, opts, false) {
+        let link = match Link::new_from_opts(chains.src, chains.dst, opts, false) {
             Ok(link) => link,
             Err(e) => Output::error(format!("{}", e)).exit(),
         };
@@ -82,7 +82,7 @@ impl Runnable for TxRawPacketAckCmd {
             src_port_id: self.src_port_id.clone(),
             src_channel_id: self.src_channel_id.clone(),
         };
-        let mut link = match Link::new_from_opts(chains.src, chains.dst, opts, false) {
+        let link = match Link::new_from_opts(chains.src, chains.dst, opts, false) {
             Ok(link) => link,
             Err(e) => Output::error(format!("{}", e)).exit(),
         };

relayer/src/link.rs

@@ -163,7 +163,7 @@ impl<ChainA: ChainHandle, ChainB: ChainHandle> Link<ChainA, ChainB> {
     }
 
     /// Implements the `packet-recv` CLI
-    pub fn build_and_send_recv_packet_messages(&mut self) -> Result<Vec<IbcEvent>, LinkError> {
+    pub fn build_and_send_recv_packet_messages(&self) -> Result<Vec<IbcEvent>, LinkError> {
         let _span = error_span!(
             "PacketRecvCmd",
             src_chain = %self.a_to_b.src_chain().id(),
@@ -189,7 +189,7 @@ impl<ChainA: ChainHandle, ChainB: ChainHandle> Link<ChainA, ChainB> {
     }
 
     /// Implements the `packet-ack` CLI
-    pub fn build_and_send_ack_packet_messages(&mut self) -> Result<Vec<IbcEvent>, LinkError> {
+    pub fn build_and_send_ack_packet_messages(&self) -> Result<Vec<IbcEvent>, LinkError> {
         let _span = error_span!(
             "PacketAckCmd",
             src_chain = %self.a_to_b.src_chain().id(),