Chain API subsystem (#1498)

* chain-api subsystem skeleton

* chain-api subsystem: draft impl

* chain-api subsystem: mock testclient

* chain-api subsystem: impl HeaderBacked for TestClient

* chain-api subsystem: impl basic tests

* chain-api subsystem: tiny guide

* chain-api subsystem: rename ChainApiRequestMessage to ChainApiMessage

* chain-api subsystem: add the page to the ToC

* chain-api subsystem: proper error type

* chain-api subsystem: impl ancestors request

* chain-api subsystem: tests for ancestors request

* guide: fix ancestor return type

* runtime-api subsystem: remove unused dep

* fix fmt

* fix outdated comment

* chain-api subsystem: s/format/to_string

* lower-case subsystem names

* chain-api subsystem: resolve Finalized todo

* chain-api subsystem: remove TODO

* extract request errors into a module

* remove caching TODO

* fix imports

polkadot/node/subsystem/src/errors.rs

@@ -0,0 +1,57 @@
+// Copyright 2020 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Error types for the subsystem requests.
+
+/// A description of an error causing the runtime API request to be unservable.
+#[derive(Debug, Clone)]
+pub struct RuntimeApiError(String);
+
+impl From<String> for RuntimeApiError {
+	fn from(s: String) -> Self {
+		RuntimeApiError(s)
+	}
+}
+
+impl core::fmt::Display for RuntimeApiError {
+	fn fmt(&self, f: &mut core::fmt::Formatter) -> Result<(), core::fmt::Error> {
+		write!(f, "{}", self.0)
+	}
+}
+
+/// A description of an error causing the chain API request to be unservable.
+#[derive(Debug, Clone)]
+pub struct ChainApiError {
+	msg: String,
+}
+
+impl From<&str> for ChainApiError {
+	fn from(s: &str) -> Self {
+		s.to_owned().into()
+	}
+}
+
+impl From<String> for ChainApiError {
+	fn from(msg: String) -> Self {
+		Self { msg }
+	}
+}
+
+impl core::fmt::Display for ChainApiError {
+	fn fmt(&self, f: &mut core::fmt::Formatter) -> Result<(), core::fmt::Error> {
+		write!(f, "{}", self.msg)
+	}
+}

polkadot/node/subsystem/src/lib.rs

@@ -34,6 +34,7 @@ use smallvec::SmallVec;
 
 use crate::messages::AllMessages;
 
+pub mod errors;
 pub mod messages;
 pub mod util;
 #[cfg(any(test, feature = "test-helpers"))]

polkadot/node/subsystem/src/messages.rs

@@ -31,7 +31,7 @@ use polkadot_primitives::v1::{
 	CoreAssignment, CoreOccupied, CandidateDescriptor,
 	ValidatorSignature, OmittedValidationData, AvailableData, GroupRotationInfo,
 	CoreState, LocalValidationData, GlobalValidationData, OccupiedCoreAssumption,
-	CandidateEvent, SessionIndex,
+	CandidateEvent, SessionIndex, BlockNumber,
 };
 use polkadot_node_primitives::{
 	MisbehaviorReport, SignedFullStatement, View, ProtocolId, ValidationResult,
@@ -285,6 +285,43 @@ impl AvailabilityStoreMessage {
 	}
 }
 
+/// A response channel for the result of a chain API request.
+pub type ChainApiResponseChannel<T> = oneshot::Sender<Result<T, crate::errors::ChainApiError>>;
+
+/// Chain API request subsystem message.
+#[derive(Debug)]
+pub enum ChainApiMessage {
+	/// Request the block number by hash.
+	/// Returns `None` if a block with the given hash is not present in the db.
+	BlockNumber(Hash, ChainApiResponseChannel<Option<BlockNumber>>),
+	/// Request the finalized block hash by number.
+	/// Returns `None` if a block with the given number is not present in the db.
+	/// Note: the caller must ensure the block is finalized.
+	FinalizedBlockHash(BlockNumber, ChainApiResponseChannel<Option<Hash>>),
+	/// Request the last finalized block number.
+	/// This request always succeeds.
+	FinalizedBlockNumber(ChainApiResponseChannel<BlockNumber>),
+	/// Request the `k` ancestors block hashes of a block with the given hash.
+	/// The response channel may return a `Vec` of size up to `k`
+	/// filled with ancestors hashes with the following order:
+	/// `parent`, `grandparent`, ...
+	Ancestors {
+		/// The hash of the block in question.
+		hash: Hash,
+		/// The number of ancestors to request.
+		k: usize,
+		/// The response channel. 
+		response_channel: ChainApiResponseChannel<Vec<Hash>>,
+	},
+}
+
+impl ChainApiMessage {
+	/// If the current variant contains the relay parent hash, return it.
+	pub fn relay_parent(&self) -> Option<Hash> {
+		None
+	}
+}
+
 /// The information on scheduler assignments that some somesystems may be querying.
 #[derive(Debug, Clone)]
 pub struct SchedulerRoster {
@@ -298,18 +335,8 @@ pub struct SchedulerRoster {
 	pub availability_cores: Vec<Option<CoreOccupied>>,
 }
 
-/// A description of an error causing the runtime API request to be unservable.
-#[derive(Debug, Clone)]
-pub struct RuntimeApiError(String);
-
-impl From<String> for RuntimeApiError {
-	fn from(s: String) -> Self {
-		RuntimeApiError(s)
-	}
-}
-
 /// A sender for the result of a runtime API request.
-pub type RuntimeApiSender<T> = oneshot::Sender<Result<T, RuntimeApiError>>;
+pub type RuntimeApiSender<T> = oneshot::Sender<Result<T, crate::errors::RuntimeApiError>>;
 
 /// A request to the Runtime API subsystem.
 #[derive(Debug)]

polkadot/node/subsystem/src/util.rs

@@ -22,8 +22,9 @@
 
 use crate::{
 	messages::{
-		AllMessages, RuntimeApiError, RuntimeApiMessage, RuntimeApiRequest, RuntimeApiSender,
+		AllMessages, RuntimeApiMessage, RuntimeApiRequest, RuntimeApiSender,
 	},
+	errors::{ChainApiError, RuntimeApiError},
 	FromOverseer, SpawnedSubsystem, Subsystem, SubsystemContext, SubsystemError, SubsystemResult,
 };
 use futures::{
@@ -72,7 +73,10 @@ pub enum Error {
 	/// A subsystem error
 	#[from]
 	Subsystem(SubsystemError),
-	/// An error in the runtime API.
+	/// An error in the Chain API.
+	#[from]
+	ChainApi(ChainApiError),
+	/// An error in the Runtime API.
 	#[from]
 	RuntimeApi(RuntimeApiError),
 	/// The type system wants this even though it doesn't make sense