1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

// Copyright Parity Technologies (UK) Ltd.
// This file is part of Substrate.

// Substrate 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.

// Substrate 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 Substrate.  If not, see <http://www.gnu.org/licenses/>.

//! Block relay protocol related definitions.

use futures::channel::oneshot;
use sc_network::{request_responses::RequestFailure, NetworkBackend, ProtocolName};
use sc_network_common::sync::message::{BlockData, BlockRequest};
use sc_network_types::PeerId;
use sp_runtime::traits::Block as BlockT;
use std::sync::Arc;

/// The serving side of the block relay protocol. It runs a single instance
/// of the server task that processes the incoming protocol messages.
#[async_trait::async_trait]
pub trait BlockServer<Block: BlockT>: Send {
	/// Starts the protocol processing.
	async fn run(&mut self);
}

/// The client side stub to download blocks from peers. This is a handle
/// that can be used to initiate concurrent downloads.
#[async_trait::async_trait]
pub trait BlockDownloader<Block: BlockT>: Send + Sync {
	/// Performs the protocol specific sequence to fetch the blocks from the peer.
	/// Output: if the download succeeds, the response is a `Vec<u8>` which is
	/// in a format specific to the protocol implementation. The block data
	/// can be extracted from this response using [`BlockDownloader::block_response_into_blocks`].
	async fn download_blocks(
		&self,
		who: PeerId,
		request: BlockRequest<Block>,
	) -> Result<Result<(Vec<u8>, ProtocolName), RequestFailure>, oneshot::Canceled>;

	/// Parses the protocol specific response to retrieve the block data.
	fn block_response_into_blocks(
		&self,
		request: &BlockRequest<Block>,
		response: Vec<u8>,
	) -> Result<Vec<BlockData<Block>>, BlockResponseError>;
}

/// Errors returned by [`BlockDownloader::block_response_into_blocks`].
#[derive(Debug)]
pub enum BlockResponseError {
	/// Failed to decode the response bytes.
	DecodeFailed(String),

	/// Failed to extract the blocks from the decoded bytes.
	ExtractionFailed(String),
}

/// Block relay specific params for network creation, specified in
/// ['sc_service::BuildNetworkParams'].
pub struct BlockRelayParams<Block: BlockT, N: NetworkBackend<Block, <Block as BlockT>::Hash>> {
	pub server: Box<dyn BlockServer<Block>>,
	pub downloader: Arc<dyn BlockDownloader<Block>>,
	pub request_response_config: N::RequestResponseProtocolConfig,
}