Crate ractor_cluster

Support for remote nodes in a distributed cluster.

A node is the same as Erlang’s definition for distributed Erlang, in that it’s a remote “hosting” process in the distributed pool of processes.

In this realization, nodes are simply actors which handle an external connection to the other nodes in the pool. When nodes connect and are authenticated, they spawn their remote-supporting local actors on the remote system as RemoteActors. The additionally handle synchronizing PG groups so the groups can contain both local and remote actors.

We have chosen protobuf for our inter-node defined protocol, however you can chose whatever medium you like for binary serialization + deserialization. The “remote” actor will simply encode your message type and send it over the wire for you

(Future) When nodes connect, they identify all of the nodes the remote node is also connected to and additionally connect to them as well.

Important note on message serialization

An important note on usage, when utilizing ractor_cluster and ractor in the cluster configuration (i.e. ractor/cluster), you no longer receive the auto-implementation for all types for ractor::Message. This is due to specialization (see: https://github.com/rust-lang/rust/issues/31844). Ideally we’d have the trait have a “default” non-serializable implementation for all types that could be messages, and specific implementations for those that can be messages sent over the network. However this is presently a +nightly only functionality and has a soundness hole in it’s definition and usage. Therefore as a workaround, when the cluster feature is enabled on ractor the default implementation, specifically

impl<T: std::any::Any + Send + Sized + 'static> ractor::Message for T {}

is disabled.

This means that you need to specify the implementation of the ractor::Message trait on all message types, and when they’re not network supported messages, this is just a default empty implementation. When they are potentially sent over a network in a dist protocol, then you need to fill out the implementation details for how the message serialization is handled. There however is a procedural macro in ractor_cluster_derive to facilitate this, which is re-exposed on this crate under the same naming. Simply derive RactorMessage or RactorClusterMessage if you want local or remote-supporting messages, respectively.

Re-exports

• pub use node::client::connect as client_connect;
• pub use node::client::connect_enc as client_connect_enc;
• pub use node::client::ClientConnectErr;
• pub use node::NodeEventSubscription;
• pub use node::NodeServer;
• pub use node::NodeServerMessage;
• pub use node::NodeSession;
• pub use node::NodeSessionMessage;

Modules

• macros
  Macro helpers for remote actors
• node
  Erlang node() host communication for managing remote actor communication in a cluster

Macros

• derive_serialization_for_prost_type
  Derive crate::BytesConvertable for a given prost type. This utilizes the prost extensions

Enums

• IncomingEncryptionMode
  Incoming encryption mode
• NetworkStream
  A network data stream which can either be

Traits

• BytesConvertable
  Trait for use with ractor_cluster_derive::RactorClusterMessage derive macro. It defines argument and reply message types which are serializable to/from byte payloads so code can be autogenerated for you by macros for over-the-wire message formats between actors

Type Aliases

• NodeId
  Node’s are representing by an integer id

Derive Macros

• RactorClusterMessage
  Derive ractor::Message for messages that can be sent over the network
• RactorMessage
  Derive ractor::Message for messages that are local-only