soil-network 0.2.0

// This file is part of Soil.

// Copyright (C) Soil contributors.
// Copyright (C) Parity Technologies (UK) Ltd.
// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0

//! Block relay protocol related definitions.

use futures::channel::oneshot;
use soil_network::common::sync::message::{BlockData, BlockRequest};
use soil_network::types::PeerId;
use soil_network::{request_responses::RequestFailure, NetworkBackend, ProtocolName};
use std::{fmt, sync::Arc};
use subsoil::runtime::traits::Block as BlockT;

/// 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>: fmt::Debug + Send + Sync {
	/// Protocol name used by block downloader.
	fn protocol_name(&self) -> &ProtocolName;

	/// 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
/// ['soil_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,
}