rpc: stabilize chainhead backend (#1802)

* rpc: stabilize ChainHeadBackend

* remove noise from example

* add missing features

* make tests compile

* make tests compile v2

* revert stop event

* feature-gate runtime

* Update subxt/Cargo.toml

* add docsrs feature stuff

* Update subxt/src/backend/chain_head/mod.rs

* Update subxt/src/backend/chain_head/mod.rs

* Update subxt/src/backend/chain_head/mod.rs

subxt/examples/setup_reconnecting_rpc_client.rs

@@ -34,20 +34,13 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         .build("ws://localhost:9944".to_string())
         .await?;
 
-    // If you want to use the unstable backend with the reconnecting RPC client, you can do so like this:
+    // If you want to use the chainhead backend with the reconnecting RPC client, you can do so like this:
     //
     // ```
-    // use subxt::backend::unstable::UnstableBackend;
+    // use subxt::backend::chain_head:ChainHeadBackend;
     // use subxt::OnlineClient;
     //
-    // let (backend, mut driver) = UnstableBackend::builder().build(RpcClient::new(rpc.clone()));
-    // tokio::spawn(async move {
-    //     while let Some(val) = driver.next().await {
-    //         if let Err(e) = val {
-    //             eprintln!("Error driving unstable backend: {e}; terminating client");
-    //        }
-    //    }
-    // });
+    // let backend = ChainHeadBackend::builder().build_with_background_task(RpcClient::new(rpc.clone()));
     // let api: OnlineClient<PolkadotConfig> = OnlineClient::from_backend(Arc::new(backend)).await?;
     // ```
 

subxt/examples/setup_rpc_chainhead_backend.rs

@@ -0,0 +1,35 @@
+//! Example to utilize the ChainHeadBackend rpc backend to subscribe to finalized blocks.
+
+#![allow(missing_docs)]
+
+use futures::StreamExt;
+use subxt::backend::chain_head::{ChainHeadBackend, ChainHeadBackendBuilder};
+use subxt::backend::rpc::RpcClient;
+use subxt::{OnlineClient, PolkadotConfig};
+
+// Generate an interface that we can use from the node's metadata.
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata_small.scale")]
+pub mod polkadot {}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tracing_subscriber::fmt::init();
+
+    let rpc = RpcClient::from_url("ws://localhost:9944".to_string()).await?;
+    let backend: ChainHeadBackend<PolkadotConfig> =
+        ChainHeadBackendBuilder::default().build_with_background_driver(rpc.clone());
+    let api = OnlineClient::from_backend(std::sync::Arc::new(backend)).await?;
+
+    let mut blocks_sub = api.blocks().subscribe_finalized().await?.take(100);
+
+    while let Some(block) = blocks_sub.next().await {
+        let block = block?;
+
+        let block_number = block.number();
+        let block_hash = block.hash();
+
+        println!("Block #{block_number} ({block_hash})");
+    }
+
+    Ok(())
+}