Guide: router module

roadmap/implementors-guide/src/SUMMARY.md

@@ -13,6 +13,7 @@
   - [Inclusion Module](runtime/inclusion.md)
   - [InclusionInherent Module](runtime/inclusioninherent.md)
   - [Validity Module](runtime/validity.md)
+  - [Router Module](runtime/router.md)
 - [Node Architecture](node/README.md)
   - [Subsystems and Jobs](node/subsystems-and-jobs.md)
   - [Overseer](node/overseer.md)

roadmap/implementors-guide/src/runtime/inclusion.md

@@ -54,11 +54,13 @@ All failed checks should lead to an unrecoverable error making the block invalid
   1. check that each candidate corresponds to a scheduled core and that they are ordered in ascending order by `ParaId`.
   1. Ensure that any code upgrade scheduled by the candidate does not happen within `config.validation_upgrade_frequency` of the currently scheduled upgrade, if any, comparing against the value of `Paras::FutureCodeUpgrades` for the given para ID.
   1. check the backing of the candidate using the signatures and the bitfields.
+  1. check that the upwards messages are not exceeding `config.max_upwards_queue_count` and `config.watermark_queue_size` parameters.
   1. create an entry in the `PendingAvailability` map for each backed candidate with a blank `availability_votes` bitfield.
   1. Return a `Vec<CoreIndex>` of all scheduled cores of the list of passed assignments that a candidate was successfully backed for, sorted ascending by CoreIndex.
 * `enact_candidate(relay_parent_number: BlockNumber, AbridgedCandidateReceipt)`:
   1. If the receipt contains a code upgrade, Call `Paras::schedule_code_upgrade(para_id, code, relay_parent_number + config.validationl_upgrade_delay)`.
     > TODO: Note that this is safe as long as we never enact candidates where the relay parent is across a session boundary. In that case, which we should be careful to avoid with contextual execution, the configuration might have changed and the para may de-sync from the host's understanding of it.
+  1. call `Router::queue_upward_messages` for each backed candidate.
   1. Call `Paras::note_new_head` using the `HeadData` from the receipt and `relay_parent_number`.
 * `collect_pending`:
 

roadmap/implementors-guide/src/runtime/router.md

@@ -0,0 +1,38 @@
+# Router Module
+
+The Router module is responsible for storing and dispatching Upwards and Downwards messages from and to parachains respectively. It is intended to later handle the XCMP logic as well.
+
+For each enacted block the `enqueue_upward_messages` entry-point is called. All dispatching logic is done by the `dispatch_upward_messages` entry-point. This entry-point is mandatory, in that it must be envoked once within every block.
+
+This module does not have the same initialization/finalization concerns as the others, it requires that its entry points be triggered
+  1. When candidate is enacted.
+  1. Upon new block initialization.
+
+## Storage
+
+Storage layout:
+
+```rust,ignore
+/// Messages ready to be dispatched onto the relay chain.
+/// This is subject to `max_upwards_queue_count` and
+///`watermark_queue_size` from `HostConfiguration`.
+RelayDispatchQueues: map ParaId => Vec<UpwardMessage>;
+/// Size of the dispatch queues. Caches sizes of the queues in `RelayDispatchQueue`.
+/// First item in the tuple is the count of messages and second
+/// is the total length (in bytes) of the message payloads.
+RelayDispatchQueueSize: map ParaId => (u32, u32);
+/// The ordered list of `ParaId`s that have a `RelayDispatchQueue` entry.
+NeedsDispatch: Vec<ParaId>;
+```
+
+## Routines
+
+* `queue_upward_messages(AbridgedCandidateReceipt)`:
+  1. Updates `NeedsDispatch`, and enqueues upward messages into `RelayDispatchQueue` and modifies the respective entry in `RelayDispatchQueueSize`.
+* `dispatch_upward_messages()`:
+  1. If `NeedsDispatch` contains an entry passed as an input parameter start dispatching messages from it's respective entry in `RelayDispatchQueues`. The dispatch is done in the FIFO order and it drains the queue and removes it from `RelayDispatchQueues`.
+
+## Initialization
+
+  > TODO: On initalization or finalization or when exactly?
+  1. Dispatch queued upward messages using `dispatch_upward_messages`.

roadmap/implementors-guide/src/types/runtime.md

@@ -34,5 +34,11 @@ struct HostConfiguration {
 	pub thread_availability_period: BlockNumber,
 	/// The amount of blocks ahead to schedule parathreads.
 	pub scheduling_lookahead: u32,
+	/// Total number of individual messages allowed in the parachain -> relay-chain message queue.
+	pub max_upwards_queue_count: u32,
+	/// Total size of messages allowed in the parachain -> relay-chain message queue before which
+	/// no further messages may be added to it. If it exceeds this then the queue may contain only
+	/// a single message.
+	pub watermark_queue_size: u32,
 }
 ```