Implement Network Bridge (#1280)

* network bridge skeleton * move some primitives around and add debug impls * protocol registration glue & abstract network interface * add send_msgs to subsystemctx * select logic * transform different events into actions and handle * implement remaining network bridge state machine * start test skeleton * make network methods asynchronous * extract subsystem out to subsystem crate * port over overseer to subsystem context trait * fix minimal example * fix overseer doc test * update network-bridge crate * write a subsystem test-helpers crate * write a network test helper for network-bridge * set up (broken) view test * Revamp network to be more async-friendly and not require Sync * fix spacing * fix test compilation * insert side-channel for actions * Add some more message types to AllMessages * introduce a test harness * add some tests * ensure service compiles and passes tests * fix typo * fix service-new compilation * Subsystem test helpers send messages synchronously * remove smelly action inspector * remove superfluous let binding * fix warnings * Update node/network/bridge/src/lib.rs Co-authored-by: Peter Goodspeed-Niklaus <coriolinus@users.noreply.github.com> * fix compilation Co-authored-by: Peter Goodspeed-Niklaus <coriolinus@users.noreply.github.com>
2026-06-15 04:31:08 +00:00 · 2020-06-30 11:21:40 -04:00
parent 90de55918a
commit d16e7485d4
16 changed files with 1533 additions and 169 deletions
@@ -0,0 +1,150 @@
+// Copyright 2017-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/>.
+
+//! Subsystem trait definitions and message types.
+//!
+//! Node-side logic for Polkadot is mostly comprised of Subsystems, which are discrete components
+//! that communicate via message-passing. They are coordinated by an overseer, provided by a
+//! separate crate.
+
+use std::pin::Pin;
+
+use futures::prelude::*;
+use futures::channel::{mpsc, oneshot};
+use futures::future::BoxFuture;
+
+use polkadot_primitives::Hash;
+use async_trait::async_trait;
+
+use crate::messages::AllMessages;
+
+pub mod messages;
+
+/// Signals sent by an overseer to a subsystem.
+#[derive(PartialEq, Clone, Debug)]
+pub enum OverseerSignal {
+	/// `Subsystem` should start working on block-based work, given by the relay-chain block hash.
+	StartWork(Hash),
+	/// `Subsystem` should stop working on block-based work specified by the relay-chain block hash.
+	StopWork(Hash),
+	/// Conclude the work of the `Overseer` and all `Subsystem`s.
+	Conclude,
+}
+
+/// A message type that a subsystem receives from an overseer.
+/// It wraps signals from an overseer and messages that are circulating
+/// between subsystems.
+///
+/// It is generic over over the message type `M` that a particular `Subsystem` may use.
+#[derive(Debug)]
+pub enum FromOverseer<M> {
+	/// Signal from the `Overseer`.
+	Signal(OverseerSignal),
+
+	/// Some other `Subsystem`'s message.
+	Communication {
+		msg: M,
+	},
+}
+
+/// An error type that describes faults that may happen
+///
+/// These are:
+///   * Channels being closed
+///   * Subsystems dying when they are not expected to
+///   * Subsystems not dying when they are told to die
+///   * etc.
+#[derive(Debug)]
+pub struct SubsystemError;
+
+impl From<mpsc::SendError> for SubsystemError {
+	fn from(_: mpsc::SendError) -> Self {
+		Self
+	}
+}
+
+impl From<oneshot::Canceled> for SubsystemError {
+	fn from(_: oneshot::Canceled) -> Self {
+		Self
+	}
+}
+
+impl From<futures::task::SpawnError> for SubsystemError {
+    fn from(_: futures::task::SpawnError) -> Self {
+		Self
+    }
+}
+
+impl From<std::convert::Infallible> for SubsystemError {
+	fn from(e: std::convert::Infallible) -> Self {
+		match e {}
+	}
+}
+
+/// An asynchronous subsystem task..
+///
+/// In essence it's just a newtype wrapping a `BoxFuture`.
+pub struct SpawnedSubsystem(pub BoxFuture<'static, ()>);
+
+/// A `Result` type that wraps [`SubsystemError`].
+///
+/// [`SubsystemError`]: struct.SubsystemError.html
+pub type SubsystemResult<T> = Result<T, SubsystemError>;
+
+/// A context type that is given to the [`Subsystem`] upon spawning.
+/// It can be used by [`Subsystem`] to communicate with other [`Subsystem`]s
+/// or spawn jobs.
+///
+/// [`Overseer`]: struct.Overseer.html
+/// [`SubsystemJob`]: trait.SubsystemJob.html
+#[async_trait]
+pub trait SubsystemContext: Send + 'static {
+	/// The message type of this context. Subsystems launched with this context will expect
+	/// to receive messages of this type.
+	type Message: Send;
+
+	/// Try to asynchronously receive a message.
+	///
+	/// This has to be used with caution, if you loop over this without
+	/// using `pending!()` macro you will end up with a busy loop!
+	async fn try_recv(&mut self) -> Result<Option<FromOverseer<Self::Message>>, ()>;
+
+	/// Receive a message.
+	async fn recv(&mut self) -> SubsystemResult<FromOverseer<Self::Message>>;
+
+	/// Spawn a child task on the executor.
+	async fn spawn(&mut self, s: Pin<Box<dyn Future<Output = ()> + Send>>) -> SubsystemResult<()>;
+
+	/// Send a direct message to some other `Subsystem`, routed based on message type.
+	async fn send_message(&mut self, msg: AllMessages) -> SubsystemResult<()>;
+
+	/// Send multiple direct messages to other `Subsystem`s, routed based on message type.
+	async fn send_messages<T>(&mut self, msgs: T) -> SubsystemResult<()>
+		where T: IntoIterator<Item = AllMessages> + Send, T::IntoIter: Send;
+}
+
+/// A trait that describes the [`Subsystem`]s that can run on the [`Overseer`].
+///
+/// It is generic over the message type circulating in the system.
+/// The idea that we want some type contaning persistent state that
+/// can spawn actually running subsystems when asked to.
+///
+/// [`Overseer`]: struct.Overseer.html
+/// [`Subsystem`]: trait.Subsystem.html
+pub trait Subsystem<C: SubsystemContext> {
+	/// Start this `Subsystem` and return `SpawnedSubsystem`.
+	fn start(&mut self, ctx: C) -> SpawnedSubsystem;
+}
@@ -0,0 +1,226 @@
+// Copyright 2017-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/>.
+
+//! Message types for the overseer and subsystems.
+//!
+//! These messages are intended to define the protocol by which different subsystems communicate with each
+//! other and signals that they receive from an overseer to coordinate their work.
+//! This is intended for use with the `polkadot-overseer` crate.
+//!
+//! Subsystems' APIs are defined separately from their implementation, leading to easier mocking.
+
+use futures::channel::{mpsc, oneshot};
+
+use sc_network::{ObservedRole, ReputationChange, PeerId};
+use polkadot_primitives::{BlockNumber, Hash, Signature};
+use polkadot_primitives::parachain::{
+	AbridgedCandidateReceipt, PoVBlock, ErasureChunk, BackedCandidate, Id as ParaId,
+	SignedAvailabilityBitfield, SigningContext, ValidatorId, ValidationCode, ValidatorIndex,
+};
+use polkadot_node_primitives::{
+	MisbehaviorReport, SignedFullStatement, View, ProtocolId,
+};
+
+/// A notification of a new backed candidate.
+#[derive(Debug)]
+pub struct NewBackedCandidate(pub BackedCandidate);
+
+/// Messages received by the Candidate Selection subsystem.
+#[derive(Debug)]
+pub enum CandidateSelectionMessage {
+	/// We recommended a particular candidate to be seconded, but it was invalid; penalize the collator.
+	/// The hash is the relay parent.
+	Invalid(Hash, AbridgedCandidateReceipt),
+}
+
+/// Messages received by the Candidate Backing subsystem.
+#[derive(Debug)]
+pub enum CandidateBackingMessage {
+	/// Registers a stream listener for updates to the set of backable candidates that could be backed
+	/// in a child of the given relay-parent, referenced by its hash.
+	RegisterBackingWatcher(Hash, mpsc::Sender<NewBackedCandidate>),
+	/// Note that the Candidate Backing subsystem should second the given candidate in the context of the
+	/// given relay-parent (ref. by hash). This candidate must be validated.
+	Second(Hash, AbridgedCandidateReceipt),
+	/// Note a validator's statement about a particular candidate. Disagreements about validity must be escalated
+	/// to a broader check by Misbehavior Arbitration. Agreements are simply tallied until a quorum is reached.
+	Statement(Hash, SignedFullStatement),
+}
+
+/// Blanket error for validation failing.
+#[derive(Debug)]
+pub struct ValidationFailed;
+
+/// Messages received by the Validation subsystem
+#[derive(Debug)]
+pub enum CandidateValidationMessage {
+	/// Validate a candidate, sending a side-channel response of valid or invalid.
+	///
+	/// Provide the relay-parent in whose context this should be validated, the full candidate receipt,
+	/// and the PoV.
+	Validate(
+		Hash,
+		AbridgedCandidateReceipt,
+		PoVBlock,
+		oneshot::Sender<Result<(), ValidationFailed>>,
+	),
+}
+
+/// Events from network.
+#[derive(Debug, Clone)]
+pub enum NetworkBridgeEvent {
+	/// A peer has connected.
+	PeerConnected(PeerId, ObservedRole),
+
+	/// A peer has disconnected.
+	PeerDisconnected(PeerId),
+
+	/// Peer has sent a message.
+	PeerMessage(PeerId, Vec<u8>),
+
+	/// Peer's `View` has changed.
+	PeerViewChange(PeerId, View),
+
+	/// Our `View` has changed.
+	OurViewChange(View),
+}
+
+/// Messages received by the network bridge subsystem.
+#[derive(Debug)]
+pub enum NetworkBridgeMessage {
+	/// Register an event producer on startup.
+	RegisterEventProducer(ProtocolId, fn(NetworkBridgeEvent) -> AllMessages),
+
+	/// Report a peer for their actions.
+	ReportPeer(PeerId, ReputationChange),
+
+	/// Send a message to multiple peers.
+	SendMessage(Vec<PeerId>, ProtocolId, Vec<u8>),
+}
+
+/// Availability Distribution Message.
+#[derive(Debug)]
+pub enum AvailabilityDistributionMessage {
+	/// Distribute an availability chunk to other validators.
+	DistributeChunk(Hash, ErasureChunk),
+
+	/// Fetch an erasure chunk from networking by candidate hash and chunk index.
+	FetchChunk(Hash, u32),
+
+	/// Event from the network bridge.
+	NetworkBridgeUpdate(NetworkBridgeEvent),
+}
+
+/// Bitfield distribution message.
+#[derive(Debug)]
+pub enum BitfieldDistributionMessage {
+	/// Distribute a bitfield via gossip to other validators.
+	DistributeBitfield(Hash, SignedAvailabilityBitfield),
+
+	/// Event from the network bridge.
+	NetworkBridgeUpdate(NetworkBridgeEvent),
+}
+
+/// Availability store subsystem message.
+#[derive(Debug)]
+pub enum AvailabilityStoreMessage {
+	/// Query a `PoVBlock` from the AV store.
+	QueryPoV(Hash, oneshot::Sender<Option<PoVBlock>>),
+
+	/// Query an `ErasureChunk` from the AV store.
+	QueryChunk(Hash, ValidatorIndex, oneshot::Sender<ErasureChunk>),
+
+	/// Store an `ErasureChunk` in the AV store.
+	StoreChunk(Hash, ValidatorIndex, ErasureChunk),
+}
+
+/// A request to the Runtime API subsystem.
+#[derive(Debug)]
+pub enum RuntimeApiRequest {
+	/// Get the current validator set.
+	Validators(oneshot::Sender<Vec<ValidatorId>>),
+	/// Get a signing context for bitfields and statements.
+	SigningContext(oneshot::Sender<SigningContext>),
+	/// Get the validation code for a specific para, assuming execution under given block number, and
+	/// an optional block number representing an intermediate parablock executed in the context of
+	/// that block.
+	ValidationCode(ParaId, BlockNumber, Option<BlockNumber>, oneshot::Sender<ValidationCode>),
+}
+
+/// A message to the Runtime API subsystem.
+#[derive(Debug)]
+pub enum RuntimeApiMessage {
+	/// Make a request of the runtime API against the post-state of the given relay-parent.
+	Request(Hash, RuntimeApiRequest),
+}
+
+/// Statement distribution message.
+#[derive(Debug)]
+pub enum StatementDistributionMessage {
+	/// We have originated a signed statement in the context of
+	/// given relay-parent hash and it should be distributed to other validators.
+	Share(Hash, SignedFullStatement),
+	/// Event from the network bridge.
+	NetworkBridgeUpdate(NetworkBridgeEvent),
+}
+
+/// This data becomes intrinsics or extrinsics which should be included in a future relay chain block.
+#[derive(Debug)]
+pub enum ProvisionableData {
+	/// This bitfield indicates the availability of various candidate blocks.
+	Bitfield(Hash, SignedAvailabilityBitfield),
+	/// The Candidate Backing subsystem believes that this candidate is valid, pending availability.
+	BackedCandidate(BackedCandidate),
+	/// Misbehavior reports are self-contained proofs of validator misbehavior.
+	MisbehaviorReport(Hash, MisbehaviorReport),
+	/// Disputes trigger a broad dispute resolution process.
+	Dispute(Hash, Signature),
+}
+
+/// Message to the Provisioner.
+///
+/// In all cases, the Hash is that of the relay parent.
+#[derive(Debug)]
+pub enum ProvisionerMessage {
+	/// This message allows potential block authors to be kept updated with all new authorship data
+	/// as it becomes available.
+	RequestBlockAuthorshipData(Hash, mpsc::Sender<ProvisionableData>),
+	/// This data should become part of a relay chain block
+	ProvisionableData(ProvisionableData),
+}
+
+/// A message type tying together all message types that are used across Subsystems.
+#[derive(Debug)]
+pub enum AllMessages {
+	/// Message for the validation subsystem.
+	CandidateValidation(CandidateValidationMessage),
+	/// Message for the candidate backing subsystem.
+	CandidateBacking(CandidateBackingMessage),
+	/// Message for the candidate selection subsystem.
+	CandidateSelection(CandidateSelectionMessage),
+	/// Message for the statement distribution subsystem.
+	StatementDistribution(StatementDistributionMessage),
+	/// Message for the availability distribution subsystem.
+	AvailabilityDistribution(AvailabilityDistributionMessage),
+	/// Message for the bitfield distribution subsystem.
+	BitfieldDistribution(BitfieldDistributionMessage),
+	/// Message for the Provisioner subsystem.
+	Provisioner(ProvisionerMessage),
+	/// Message for the Runtime API subsystem.
+	RuntimeApi(RuntimeApiMessage),
+	/// Message for the availability store subsystem.
+	AvailabilityStore(AvailabilityStoreMessage),
+}