Add Subscription RPC for Grandpa Finality (#5732)

* Rough skeleton for what I think the RPC should look like * Create channel for sending justifications Sends finalized header and justification from Grandpa to the client. This lays the groundwork for hooking into the RPC module. * WIP: Add subscribers for justifications to Grandpa Adds the Sender end of a channel into Grandpa, through which notifications about block finality events can be sent. * WIP: Add a struct for managing subscriptions Slightly different approach from the last commit, but same basic idea. Still a rough sketch, very much doesn't compile yet. * Make naming more clear and lock data in Arc * Rough idea of what RPC would look like * Remove code from previous approach * Missed some things * Update client/rpc-api/src/chain/mod.rs Co-Authored-By: Tomasz Drwięga <tomusdrw@users.noreply.github.com> * Update client/rpc-api/src/chain/mod.rs Co-Authored-By: Tomasz Drwięga <tomusdrw@users.noreply.github.com> * Split justification subscription into sender and receiver halves * Replace RwLock with a Mutex * Add sample usage from the Service's point of view * Remove code that referred to "chain_" RPC * Use the Justification sender/receivers from Grandpa LinkHalf * Add some PubSub boilerplate * Add guiding comments * TMP: comment out to fix compilation * Return MetaIoHandler from PubSubHandler in create_full * Uncomment pubsub methods in rpc handler (fails to build) * node/rpc: make Metadata concrete in create_full to fix compilation * node: pass in SubscriptionManger to grandpa rpc handler * grandpa-rpc: use SubscriptionManger to add subscriber * grandpa-rpc: attempt at setting up the justification stream (fails to build) * grandpa-rpc: fix compilation of connecting stream to sink * grandpa-rpc: implement unsubscribe * grandpa-rpc: update older tests * grandpa-rpc: add full prefix to avoid confusing rust-analyzer * grandpa-rpc: add test for pubsub not available * grandpa-rpc: tidy up leftover code * grandpa-rpc: add test for sub and unsub of justifications * grandpa-rpc: minor stylistic changes * grandpa-rpc: split unit test * grandpa-rpc: minor stylistic changes in test * grandpa-rpc: skip returning future when cancelling * grandpa-rpc: reuse testing executor from sc-rpc * grandpa-rpc: don't need to use PubSubHandler in tests * node-rpc: use MetaIoHandler rather than PubSubHandler * grandpa: log if getting header failed * grandpa: move justification channel creation into factory function * grandpa: make the justification sender optional * grandpa: fix compilation warnings * grandpa: move justification notification types to new file * grandpa-rpc: move JustificationNotification to grandpa-rpc * grandpa-rpc: move JustificationNotification to its own file * grandpa: rename justification channel pairs * grandpa: rename notifier types * grandpa: pass justification as GrandpaJustification to the rpc module * Move Metadata to sc-rpc-api * grandpa-rpc: remove unsed error code * grandpa: fix bug for checking if channel is closed before sendind * grandpa-rpc: unit test for sending justifications * grandpa-rpc: update comments for the pubsub test * grandpa-rpc: update pubsub tests with more steps * grandpa-rpc: fix pubsub test * grandpa-rpc: minor indendation * grandpa-rpc: decode instead of encode in test * grandpa: fix review comments * grandpa: remove unused serde dependency Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com> Co-authored-by: Jon Häggblad <jon.haggblad@gmail.com> Co-authored-by: Tomasz Drwięga <tomasz@parity.io>
2026-06-01 03:21:02 +00:00 · 2020-08-10 06:31:36 -04:00
parent a936771c0f
commit 433b7214f5
28 changed files with 589 additions and 94 deletions
@@ -19,13 +19,25 @@
 //! RPC API for GRANDPA.
 #![warn(missing_docs)]

-use futures::{FutureExt, TryFutureExt};
+use futures::{FutureExt, TryFutureExt, TryStreamExt, StreamExt};
+use log::warn;
 use jsonrpc_derive::rpc;
+use jsonrpc_pubsub::{typed::Subscriber, SubscriptionId, manager::SubscriptionManager};
+use jsonrpc_core::futures::{
+	sink::Sink as Sink01,
+	stream::Stream as Stream01,
+	future::Future as Future01,
+};

 mod error;
+mod notification;
 mod report;

+use sc_finality_grandpa::GrandpaJustificationStream;
+use sp_runtime::traits::Block as BlockT;
+
 use report::{ReportAuthoritySet, ReportVoterState, ReportedRoundStates};
+use notification::JustificationNotification;

 /// Returned when Grandpa RPC endpoint is not ready.
 pub const NOT_READY_ERROR_CODE: i64 = 1;
@@ -35,48 +47,128 @@ type FutureResult<T> =

 /// Provides RPC methods for interacting with GRANDPA.
 #[rpc]
-pub trait GrandpaApi {
+pub trait GrandpaApi<Notification> {
+	/// RPC Metadata
+	type Metadata;
+
 	/// Returns the state of the current best round state as well as the
 	/// ongoing background rounds.
 	#[rpc(name = "grandpa_roundState")]
 	fn round_state(&self) -> FutureResult<ReportedRoundStates>;
+
+	/// Returns the block most recently finalized by Grandpa, alongside
+	/// side its justification.
+	#[pubsub(
+		subscription = "grandpa_justifications",
+		subscribe,
+		name = "grandpa_subscribeJustifications"
+	)]
+	fn subscribe_justifications(
+		&self,
+		metadata: Self::Metadata,
+		subscriber: Subscriber<Notification>
+	);
+
+	/// Unsubscribe from receiving notifications about recently finalized blocks.
+	#[pubsub(
+		subscription = "grandpa_justifications",
+		unsubscribe,
+		name = "grandpa_unsubscribeJustifications"
+	)]
+	fn unsubscribe_justifications(
+		&self,
+		metadata: Option<Self::Metadata>,
+		id: SubscriptionId
+	) -> jsonrpc_core::Result<bool>;
 }

 /// Implements the GrandpaApi RPC trait for interacting with GRANDPA.
-pub struct GrandpaRpcHandler<AuthoritySet, VoterState> {
+pub struct GrandpaRpcHandler<AuthoritySet, VoterState, Block: BlockT> {
 	authority_set: AuthoritySet,
 	voter_state: VoterState,
+	justification_stream: GrandpaJustificationStream<Block>,
+	manager: SubscriptionManager,
 }

-impl<AuthoritySet, VoterState> GrandpaRpcHandler<AuthoritySet, VoterState> {
-	/// Creates a new GrandpaRpcHander instance.
-	pub fn new(authority_set: AuthoritySet, voter_state: VoterState) -> Self {
+impl<AuthoritySet, VoterState, Block: BlockT> GrandpaRpcHandler<AuthoritySet, VoterState, Block> {
+	/// Creates a new GrandpaRpcHandler instance.
+	pub fn new(
+		authority_set: AuthoritySet,
+		voter_state: VoterState,
+		justification_stream: GrandpaJustificationStream<Block>,
+		manager: SubscriptionManager,
+	) -> Self {
 		Self {
 			authority_set,
 			voter_state,
+			justification_stream,
+			manager,
 		}
 	}
 }

-impl<AuthoritySet, VoterState> GrandpaApi for GrandpaRpcHandler<AuthoritySet, VoterState>
+impl<AuthoritySet, VoterState, Block> GrandpaApi<JustificationNotification>
+	for GrandpaRpcHandler<AuthoritySet, VoterState, Block>
 where
 	VoterState: ReportVoterState + Send + Sync + 'static,
 	AuthoritySet: ReportAuthoritySet + Send + Sync + 'static,
+	Block: BlockT,
 {
+	type Metadata = sc_rpc::Metadata;
+
 	fn round_state(&self) -> FutureResult<ReportedRoundStates> {
 		let round_states = ReportedRoundStates::from(&self.authority_set, &self.voter_state);
 		let future = async move { round_states }.boxed();
 		Box::new(future.map_err(jsonrpc_core::Error::from).compat())
 	}
+
+	fn subscribe_justifications(
+		&self,
+		_metadata: Self::Metadata,
+		subscriber: Subscriber<JustificationNotification>
+	) {
+		let stream = self.justification_stream.subscribe()
+			.map(|x| Ok::<_,()>(JustificationNotification::from(x)))
+			.map_err(|e| warn!("Notification stream error: {:?}", e))
+			.compat();
+
+		self.manager.add(subscriber, |sink| {
+			let stream = stream.map(|res| Ok(res));
+			sink.sink_map_err(|e| warn!("Error sending notifications: {:?}", e))
+				.send_all(stream)
+				.map(|_| ())
+		});
+	}
+
+	fn unsubscribe_justifications(
+		&self,
+		_metadata: Option<Self::Metadata>,
+		id: SubscriptionId
+	) -> jsonrpc_core::Result<bool> {
+		Ok(self.manager.cancel(id))
+	}
 }

 #[cfg(test)]
 mod tests {
 	use super::*;
-	use jsonrpc_core::IoHandler;
-	use sc_finality_grandpa::{report, AuthorityId};
+	use std::{collections::HashSet, convert::TryInto, sync::Arc};
+	use jsonrpc_core::{Notification, Output, types::Params};
+
+	use parity_scale_codec::Decode;
+	use sc_block_builder::BlockBuilder;
+	use sc_finality_grandpa::{report, AuthorityId, GrandpaJustificationSender, GrandpaJustification};
+	use sp_blockchain::HeaderBackend;
+	use sp_consensus::RecordProof;
 	use sp_core::crypto::Public;
-	use std::{collections::HashSet, convert::TryInto};
+	use sp_keyring::Ed25519Keyring;
+	use sp_runtime::traits::Header as HeaderT;
+	use substrate_test_runtime_client::{
+		runtime::Block,
+		DefaultTestClientBuilderExt,
+		TestClientBuilderExt,
+		TestClientBuilder,
+	};

 	struct TestAuthoritySet;
 	struct TestVoterState;
@@ -106,7 +198,7 @@ mod tests {
 			let voter_id_1 = AuthorityId::from_slice(&[1; 32]);
 			let voters_best: HashSet<_> = vec![voter_id_1].into_iter().collect();

-			let best_round_state = report::RoundState {
+			let best_round_state = sc_finality_grandpa::report::RoundState {
 				total_weight: 100_u64.try_into().unwrap(),
 				threshold_weight: 67_u64.try_into().unwrap(),
 				prevote_current_weight: 50.into(),
@@ -115,7 +207,7 @@ mod tests {
 				precommit_ids: HashSet::new(),
 			};

-			let past_round_state = report::RoundState {
+			let past_round_state = sc_finality_grandpa::report::RoundState {
 				total_weight: 100_u64.try_into().unwrap(),
 				threshold_weight: 67_u64.try_into().unwrap(),
 				prevote_current_weight: 100.into(),
@@ -133,23 +225,42 @@ mod tests {
 		}
 	}

+	fn setup_io_handler<VoterState>(voter_state: VoterState) -> (
+		jsonrpc_core::MetaIoHandler<sc_rpc::Metadata>,
+		GrandpaJustificationSender<Block>,
+	) where
+		VoterState: ReportVoterState + Send + Sync + 'static,
+	{
+		let (justification_sender, justification_stream) = GrandpaJustificationStream::channel();
+		let manager = SubscriptionManager::new(Arc::new(sc_rpc::testing::TaskExecutor));
+
+		let handler = GrandpaRpcHandler::new(
+			TestAuthoritySet,
+			voter_state,
+			justification_stream,
+			manager,
+		);
+
+		let mut io = jsonrpc_core::MetaIoHandler::default();
+		io.extend_with(GrandpaApi::to_delegate(handler));
+
+		(io, justification_sender)
+	}
+
 	#[test]
 	fn uninitialized_rpc_handler() {
-		let handler = GrandpaRpcHandler::new(TestAuthoritySet, EmptyVoterState);
-		let mut io = IoHandler::new();
-		io.extend_with(GrandpaApi::to_delegate(handler));
+		let (io, _) = setup_io_handler(EmptyVoterState);

 		let request = r#"{"jsonrpc":"2.0","method":"grandpa_roundState","params":[],"id":1}"#;
 		let response = r#"{"jsonrpc":"2.0","error":{"code":1,"message":"GRANDPA RPC endpoint not ready"},"id":1}"#;

-		assert_eq!(Some(response.into()), io.handle_request_sync(request));
+		let meta = sc_rpc::Metadata::default();
+		assert_eq!(Some(response.into()), io.handle_request_sync(request, meta));
 	}

 	#[test]
 	fn working_rpc_handler() {
-		let handler = GrandpaRpcHandler::new(TestAuthoritySet, TestVoterState);
-		let mut io = IoHandler::new();
-		io.extend_with(GrandpaApi::to_delegate(handler));
+		let (io,  _) = setup_io_handler(TestVoterState);

 		let request = r#"{"jsonrpc":"2.0","method":"grandpa_roundState","params":[],"id":1}"#;
 		let response = "{\"jsonrpc\":\"2.0\",\"result\":{\
@@ -166,6 +277,154 @@ mod tests {
 			\"setId\":1\
 		},\"id\":1}";

-		assert_eq!(io.handle_request_sync(request), Some(response.into()));
+		let meta = sc_rpc::Metadata::default();
+		assert_eq!(io.handle_request_sync(request, meta), Some(response.into()));
+	}
+
+	fn setup_session() -> (sc_rpc::Metadata, jsonrpc_core::futures::sync::mpsc::Receiver<String>) {
+		let (tx, rx) = jsonrpc_core::futures::sync::mpsc::channel(1);
+		let meta = sc_rpc::Metadata::new(tx);
+		(meta, rx)
+	}
+
+	#[test]
+	fn subscribe_and_unsubscribe_to_justifications() {
+		let (io, _) = setup_io_handler(TestVoterState);
+		let (meta, _) = setup_session();
+
+		// Subscribe
+		let sub_request = r#"{"jsonrpc":"2.0","method":"grandpa_subscribeJustifications","params":[],"id":1}"#;
+		let resp = io.handle_request_sync(sub_request, meta.clone());
+		let resp: Output = serde_json::from_str(&resp.unwrap()).unwrap();
+
+		let sub_id = match resp {
+			Output::Success(success) => success.result,
+			_ => panic!(),
+		};
+
+		// Unsubscribe
+		let unsub_req = format!(
+			"{{\"jsonrpc\":\"2.0\",\"method\":\"grandpa_unsubscribeJustifications\",\"params\":[{}],\"id\":1}}",
+			sub_id
+		);
+		assert_eq!(
+			io.handle_request_sync(&unsub_req, meta.clone()),
+			Some(r#"{"jsonrpc":"2.0","result":true,"id":1}"#.into()),
+		);
+
+		// Unsubscribe again and fail
+		assert_eq!(
+			io.handle_request_sync(&unsub_req, meta),
+			Some(r#"{"jsonrpc":"2.0","result":false,"id":1}"#.into()),
+		);
+	}
+
+	#[test]
+	fn subscribe_and_unsubscribe_with_wrong_id() {
+		let (io, _) = setup_io_handler(TestVoterState);
+		let (meta, _) = setup_session();
+
+		// Subscribe
+		let sub_request = r#"{"jsonrpc":"2.0","method":"grandpa_subscribeJustifications","params":[],"id":1}"#;
+		let resp = io.handle_request_sync(sub_request, meta.clone());
+		let resp: Output = serde_json::from_str(&resp.unwrap()).unwrap();
+		assert!(matches!(resp, Output::Success(_)));
+
+		// Unsubscribe with wrong ID
+		assert_eq!(
+			io.handle_request_sync(
+				r#"{"jsonrpc":"2.0","method":"grandpa_unsubscribeJustifications","params":["FOO"],"id":1}"#,
+				meta.clone()
+			),
+			Some(r#"{"jsonrpc":"2.0","result":false,"id":1}"#.into())
+		);
+	}
+
+	fn create_justification() -> GrandpaJustification<Block> {
+		let peers = &[Ed25519Keyring::Alice];
+
+		let builder = TestClientBuilder::new();
+		let backend = builder.backend();
+		let client = builder.build();
+		let client = Arc::new(client);
+
+		let built_block = BlockBuilder::new(
+			&*client,
+			client.info().best_hash,
+			client.info().best_number,
+			RecordProof::Yes,
+			Default::default(),
+			&*backend,
+		).unwrap().build().unwrap();
+
+		let block = built_block.block;
+		let block_hash = block.hash();
+
+		let justification = {
+			let round = 1;
+			let set_id = 0;
+
+			let precommit = finality_grandpa::Precommit {
+				target_hash: block_hash,
+				target_number: *block.header.number(),
+			};
+
+			let msg = finality_grandpa::Message::Precommit(precommit.clone());
+			let encoded = sp_finality_grandpa::localized_payload(round, set_id, &msg);
+			let signature = peers[0].sign(&encoded[..]).into();
+
+			let precommit = finality_grandpa::SignedPrecommit {
+				precommit,
+				signature,
+				id: peers[0].public().into(),
+			};
+
+			let commit = finality_grandpa::Commit {
+				target_hash: block_hash,
+				target_number: *block.header.number(),
+				precommits: vec![precommit],
+			};
+
+			GrandpaJustification::from_commit(&client, round, commit).unwrap()
+		};
+
+		justification
+	}
+
+	#[test]
+	fn subscribe_and_listen_to_one_justification() {
+		let (io, justification_sender) = setup_io_handler(TestVoterState);
+		let (meta, receiver) = setup_session();
+
+		// Subscribe
+		let sub_request =
+			r#"{"jsonrpc":"2.0","method":"grandpa_subscribeJustifications","params":[],"id":1}"#;
+
+		let resp = io.handle_request_sync(sub_request, meta.clone());
+		let mut resp: serde_json::Value = serde_json::from_str(&resp.unwrap()).unwrap();
+		let sub_id: String = serde_json::from_value(resp["result"].take()).unwrap();
+
+		// Notify with a header and justification
+		let justification = create_justification();
+		let _ = justification_sender.notify(justification.clone()).unwrap();
+
+		// Inspect what we received
+		let recv = receiver.take(1).wait().flatten().collect::<Vec<_>>();
+		let recv: Notification = serde_json::from_str(&recv[0]).unwrap();
+		let mut json_map = match recv.params {
+			Params::Map(json_map) => json_map,
+			_ => panic!(),
+		};
+
+		let recv_sub_id: String =
+			serde_json::from_value(json_map["subscription"].take()).unwrap();
+		let recv_justification: Vec<u8> =
+			serde_json::from_value(json_map["result"].take()).unwrap();
+		let recv_justification: GrandpaJustification<Block> =
+			Decode::decode(&mut &recv_justification[..]).unwrap();
+
+		assert_eq!(recv.method, "grandpa_justifications");
+		assert_eq!(recv_sub_id, sub_id);
+		assert_eq!(recv_justification, justification);
 	}
 }