Crate tentacle

Summary

A multiplexed p2p network framework based on yamux that supports mounting custom protocols.

The crate is aimed at implementing a framework that light weight, simple, reliable, high performance, and friendly to users.

Concept

Multiaddr

Multiaddr aims to make network addresses future-proof, composable, and efficient.

It can express almost all network protocols, such as:

• TCP/IP: /ip4/127.0.0.1/tcp/1337
• DNS/IP: /dns4/localhost/tcp/1337
• UDP: /ip4/127.0.0.1/udp/1234
• Websocket: /ip4/127.0.0.1/tcp/1337/ws

Protocol

In this library, the most important concept is protocol, so we need to clarify what is the protocol defined by tentacle.

If you use the simplest way to understand, then it can be compared to the http protocol on the TCP protocol, that is, each protocol can have its own behavior standards, analysis methods, etc.

As a framework, a builder is provided to describe the standard protocol, and three traits are provided to define the behavior of the protocol. Unfortunately, users also need an event trait to perceive other events that occur in the service, such as session establishment, protocol exceptions, etc.

builder: MetaBuilder

traits: ServiceProtocol/SessionProtocol/ProtocolSpawn

event trait: ServiceHandle

The biggest question users may have is why there are three different traits defining protocol behavior.

These three traits can be divided into two groups, representing two different design ideas:

Callback

user can only do what it defines, tentacle has stronger constraints on it

ServiceProtocol defines a globally unique single-protocol processing capability, and all the protocol data and behaviors opened by the session will be summarized here for processing. Its lifetime is from the start of the service to the end.

SessionProtocol its lifetime is only in the phase when the corresponding session is opened, the session is disconnected, and the handle drop, session open, handle open. That’s all.

Obviously, there is an abstraction of data interception

Stream

user can combine stream with any existing future ecology, tentacle restricts it weaker

ProtocolSpawn Users can get a perfect asynchronous environment to make complex control flow, and even use this trait to implement data summary processing in callback mode again

Compared with callback mode, it reduces a layer of abstraction

Use tentacle

1. Define protocol behavior with Callback or Stream trait
2. Define ServiceHandle to process other event output on tentacle service
3. Build all need ProtocolMeta from MetaBuilder
4. Register all ProtocolMeta into ServiceBuilder, then build Service
5. Setup an async runtime such as tokio
6. Run Service just like other stream, maybe keep a Control on some place which want to communicate with background Service

Feature flags

Tentacle uses the Feature flag to enable some optional functions and split the smallest dependencies for use as much as possible. Users can choose the dependencies they want according to their needs.

Related to runtime :

• tokio-runtime: Enable by default, use tokio runtime

• tokio-timer: Enable by default, use tokio inner timer

• async-timer: use async-io timer

• async-runtime: use async-std runtime

• generic-timer: use futures-timer

• wasm-timer: only use on Browser WebAssembly platform

Function related:

• ws: Enable websocket protocol support
• upnp: Enable upnp protocol, automatically try to register the port to the gateway
• unstable: Enable the feature that has not yet decided to stabilize the API
• parking_lot: Enable priority channel use parking_lot

Re-exports

pub use bytes;
pub use multiaddr;
pub use secio;
pub use yamux;

Modules

builder	Some gadgets that help create a service
context	Context for Session and Service
error	Error
protocol_select	Protocol select
runtime	runtime compatible
service	An abstraction of p2p service
traits	Useful traits
utils	Some useful functions

Structs

ProtocolId	Protocol id
SessionId	Index of session
SubstreamReadPart	Protocol Stream read part