Module polkadot_node_network_protocol::request_response

Request/response protocols used in Polkadot. Overview over request/responses as used in Polkadot.

enum Protocol …. List of all supported protocols.

enum Requests …. List of all supported requests, each entry matches one in protocols, but has the actual request as payload.

struct IncomingRequest …. wrapper for incoming requests, containing a sender for sending responses.

struct OutgoingRequest …. wrapper for outgoing requests, containing a sender used by the networking code for delivering responses/delivery errors.

trait IsRequest …. A trait describing a particular request. It is used for gathering meta data, like what is the corresponding response type.

Versioning

Versioning for request-response protocols can be done in multiple ways.

If you’re just changing the protocol name but the binary payloads are the same, just add a new fallback_name to the protocol config.

One way in which versioning has historically been achieved for req-response protocols is to bundle the new req-resp version with an upgrade of a notifications protocol. The subsystem would then know which request version to use based on stored data about the peer’s notifications protocol version.

When bumping a notifications protocol version is not needed/desirable, you may add a new req-resp protocol and set the old request as a fallback (see OutgoingRequest::new_with_fallback). A request with the new version will be attempted and if the protocol is refused by the peer, the fallback protocol request will be used. Information about the actually used protocol will be returned alongside the raw response, so that you know how to decode it.

Re-exports

• pub use incoming::IncomingRequest;
• pub use incoming::IncomingRequestReceiver;
• pub use outgoing::OutgoingRequest;
• pub use outgoing::OutgoingResult;
• pub use outgoing::Recipient;
• pub use outgoing::Requests;
• pub use outgoing::ResponseSender;

Modules

• incoming
  Everything related to handling of incoming requests.
• network
  Configuration of the networking layer.
• outgoing
  Everything related to handling of outgoing requests.
• v1
  Actual versioned requests and responses that are sent over the wire. Requests and responses as sent over the wire for the individual protocols.
• v2
  Actual versioned requests and responses that are sent over the wire. Requests and responses as sent over the wire for the individual protocols.

Structs

• ProtocolIter
  An iterator over the variants of Protocol
• ReqProtocolNames
  Type for getting on the wire Protocol names using genesis hash & fork id.
• RequestResponseConfig
  Configuration for a single request-response protocol.

Enums

• Protocol
  A protocol per subsystem seems to make the most sense, this way we don’t need any dispatching within protocols.
• ProtocolName
  The protocol name transmitted on the wire.

Constants

• CHUNK_REQUEST_TIMEOUT
  Timeout for requesting availability chunks.
• DISPUTE_REQUEST_TIMEOUT
  We can have relative large timeouts here, there is no value of hitting a timeout as we want to get statements through to each node in any case.
• MAX_PARALLEL_ATTESTED_CANDIDATE_REQUESTS
  We don’t want a slow peer to slow down all the others, at the same time we want to get out the data quickly in full to at least some peers (as this will reduce load on us as they then can start serving the data). So this value is a tradeoff. 5 seems to be sensible. So we would need to have 5 slow nodes connected, to delay transfer for others by ATTESTED_CANDIDATE_TIMEOUT.
• MAX_PARALLEL_STATEMENT_REQUESTS
  We don’t want a slow peer to slow down all the others, at the same time we want to get out the data quickly in full to at least some peers (as this will reduce load on us as they then can start serving the data). So this value is a trade-off. 3 seems to be sensible. So we would need to have 3 slow nodes connected, to delay transfer for others by STATEMENTS_TIMEOUT.

Traits

• IsRequest
  Common properties of any Request.