establish new `node` folder for overseer, messages, and subsystems (#1200)

* establish new `node` folder for overseer, messages, and subsystems

* extract message types from overseer crate

* remove doc links

Cargo.lock

@@ -3216,20 +3216,6 @@ version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77af24da69f9d9341038eba93a073b1fdaaa1b788221b00a69bce9e762cb32de"
 
-[[package]]
-name = "overseer"
-version = "0.1.0"
-dependencies = [
- "femme",
- "futures 0.3.5",
- "futures-timer 3.0.2",
- "kv-log-macro",
- "log 0.4.8",
- "polkadot-primitives",
- "sc-client-api",
- "streamunordered",
-]
-
 [[package]]
 name = "owning_ref"
 version = "0.4.1"
@@ -4209,6 +4195,28 @@ dependencies = [
  "sp-runtime",
 ]
 
+[[package]]
+name = "polkadot-node-messages"
+version = "0.1.0"
+dependencies = [
+ "polkadot-primitives",
+]
+
+[[package]]
+name = "polkadot-overseer"
+version = "0.1.0"
+dependencies = [
+ "femme",
+ "futures 0.3.5",
+ "futures-timer 3.0.2",
+ "kv-log-macro",
+ "log 0.4.8",
+ "polkadot-node-messages",
+ "polkadot-primitives",
+ "sc-client-api",
+ "streamunordered",
+]
+
 [[package]]
 name = "polkadot-parachain"
 version = "0.8.3"

Cargo.toml

@@ -27,7 +27,6 @@ members = [
 	"erasure-coding",
 	"network",
 	"network/test",
-	"overseer",
 	"primitives",
 	"runtime/common",
 	"runtime/parachains",
@@ -41,6 +40,9 @@ members = [
 	"service",
 	"validation",
 
+	"node/messages",
+	"node/overseer",
+
 	"parachain/test-parachains",
 	"parachain/test-parachains/adder",
 	"parachain/test-parachains/adder/collator",

node/core/README.md

+Stub - This folder will hold core subsystem implementations, each with their own crate.

node/messages/Cargo.toml

+[package]
+name = "polkadot-node-messages"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+description = "Message types used by Subsystems"
+
+[dependencies]
+polkadot-primitives = { path = "../../primitives" }

node/messages/src/lib.rs

+// 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 polkadot_primitives::Hash;
+
+/// 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 used by the Validation Subsystem.
+#[derive(Debug)]
+pub enum ValidationSubsystemMessage {
+	ValidityAttestation,
+}
+
+/// A message type used by the CandidateBacking Subsystem.
+#[derive(Debug)]
+pub enum CandidateBackingSubsystemMessage {
+	RegisterBackingWatcher,
+	Second,
+}
+
+/// A message type tying together all message types that are used across Subsystems.
+#[derive(Debug)]
+pub enum AllMessages {
+	Validation(ValidationSubsystemMessage),
+	CandidateBacking(CandidateBackingSubsystemMessage),
+}
+
+/// 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: std::fmt::Debug> {
+	/// Signal from the `Overseer`.
+	Signal(OverseerSignal),
+
+	/// Some other `Subsystem`'s message.
+	Communication {
+		msg: M,
+	},
+}

node/network/README.md

+Stub - This folder will hold networking subsystem implementations, each with their own crate.

overseer/Cargo.toml → node/overseer/Cargo.toml

 [package]
-name = "overseer"
+name = "polkadot-overseer"
 version = "0.1.0"
 authors = ["Parity Technologies <admin@parity.io>"]
 edition = "2018"
@@ -9,8 +9,9 @@ futures = "0.3.5"
 log = "0.4.8"
 futures-timer = "3.0.2"
 streamunordered = "0.5.1"
-polkadot-primitives = { path = "../primitives" }
+polkadot-primitives = { path = "../../primitives" }
 client = { package = "sc-client-api", git = "https://github.com/paritytech/substrate", branch = "master" }
+messages = { package = "polkadot-node-messages", path = "../messages" }
 
 [dev-dependencies]
 futures = { version = "0.3.5", features = ["thread-pool"] }

overseer/examples/minimal-example.rs → node/overseer/examples/minimal-example.rs

@@ -26,9 +26,10 @@ use futures::{
 use futures_timer::Delay;
 use kv_log_macro as log;
 
-use overseer::{
-	AllMessages, CandidateBackingSubsystemMessage, FromOverseer,
-	Overseer, Subsystem, SubsystemContext, SpawnedSubsystem, ValidationSubsystemMessage,
+use polkadot_overseer::{Overseer, Subsystem, SubsystemContext, SpawnedSubsystem};
+
+use messages::{
+	AllMessages, CandidateBackingSubsystemMessage, FromOverseer, ValidationSubsystemMessage
 };
 
 struct Subsystem1;

overseer/src/lib.rs → node/overseer/src/lib.rs

@@ -74,6 +74,11 @@ use streamunordered::{StreamYield, StreamUnordered};
 use polkadot_primitives::{Block, BlockNumber, Hash};
 use client::{BlockImportNotification, BlockchainEvents, FinalityNotification};
 
+pub use messages::{
+	OverseerSignal, ValidationSubsystemMessage, CandidateBackingSubsystemMessage, AllMessages,
+	FromOverseer,
+};
+
 /// An error type that describes faults that may happen
 ///
 /// These are:
@@ -183,13 +188,6 @@ enum Event {
 	Stop,
 }
 
-/// Some message that is sent from one of the `Subsystem`s to the outside world.
-pub enum OutboundMessage {
-	SubsystemMessage {
-		msg: AllMessages,
-	}
-}
-
 /// A handler used to communicate with the [`Overseer`].
 ///
 /// [`Overseer`]: struct.Overseer.html
@@ -228,7 +226,7 @@ impl OverseerHandler {
 	}
 }
 
-/// Glues together the [`Overseer`] and `BlockchainEvents` by forwarding 
+/// Glues together the [`Overseer`] and `BlockchainEvents` by forwarding
 /// import and finality notifications into the [`OverseerHandler`].
 ///
 /// [`Overseer`]: struct.Overseer.html
@@ -295,65 +293,6 @@ pub struct SubsystemContext<M: Debug>{
 	tx: mpsc::Sender<ToOverseer>,
 }
 
-/// A signal used by [`Overseer`] to communicate with the [`Subsystem`]s.
-///
-/// [`Overseer`]: struct.Overseer.html
-/// [`Subsystem`]: trait.Subsystem.html
-#[derive(PartialEq, Clone, Debug)]
-pub enum OverseerSignal {
-	/// `Subsystem` should start working.
-	StartWork(Hash),
-	/// `Subsystem` should stop working.
-	StopWork(Hash),
-	/// Conclude the work of the `Overseer` and all `Subsystem`s.
-	Conclude,
-}
-
-#[derive(Debug)]
-/// A message type used by the Validation [`Subsystem`].
-///
-/// [`Subsystem`]: trait.Subsystem.html
-pub enum ValidationSubsystemMessage {
-	ValidityAttestation,
-}
-
-#[derive(Debug)]
-/// A message type used by the CandidateBacking [`Subsystem`].
-///
-/// [`Subsystem`]: trait.Subsystem.html
-pub enum CandidateBackingSubsystemMessage {
-	RegisterBackingWatcher,
-	Second,
-}
-
-/// A message type tying together all message types that are used across [`Subsystem`]s.
-///
-/// [`Subsystem`]: trait.Subsystem.html
-#[derive(Debug)]
-pub enum AllMessages {
-	Validation(ValidationSubsystemMessage),
-	CandidateBacking(CandidateBackingSubsystemMessage),
-}
-
-/// A message type that a [`Subsystem`] receives from the [`Overseer`].
-/// It wraps siglans from the [`Overseer`] and messages that are circulating
-/// between subsystems.
-///
-/// It is generic over over the message type `M` that a particular `Subsystem` may use.
-///
-/// [`Overseer`]: struct.Overseer.html
-/// [`Subsystem`]: trait.Subsystem.html
-#[derive(Debug)]
-pub enum FromOverseer<M: Debug> {
-	/// Signal from the `Overseer`.
-	Signal(OverseerSignal),
-
-	/// Some other `Subsystem`'s message.
-	Communication {
-		msg: M,
-	},
-}
-
 impl<M: Debug> SubsystemContext<M> {
 	/// Try to asyncronously receive a message.
 	///
@@ -501,7 +440,7 @@ where
 	/// # use std::time::Duration;
 	/// # use futures::{executor, pin_mut, select, FutureExt};
 	/// # use futures_timer::Delay;
-	/// # use overseer::{
+	/// # use polkadot_overseer::{
 	/// #     Overseer, Subsystem, SpawnedSubsystem, SubsystemContext,
 	/// #     ValidationSubsystemMessage, CandidateBackingSubsystemMessage,
 	/// # };
@@ -898,7 +837,7 @@ mod tests {
 	//
 	// Should immediately conclude the overseer itself with an error.
 	#[test]
-	fn overseer_panics_on_sybsystem_exit() {
+	fn overseer_panics_on_subsystem_exit() {
 		let spawner = executor::ThreadPool::new().unwrap();
 
 		executor::block_on(async move {