#network #message #asynchronous #events

message-io

Easy asynchronous network message library

21 releases (8 breaking)

new 0.9.0 Feb 25, 2021
0.7.1 Feb 17, 2021
0.5.1 Dec 2, 2020
0.5.0 Nov 30, 2020
0.2.0 Jul 15, 2020

#22 in Asynchronous

Download history 88/week @ 2020-11-06 31/week @ 2020-11-13 113/week @ 2020-11-20 183/week @ 2020-11-27 46/week @ 2020-12-04 105/week @ 2020-12-11 7/week @ 2020-12-18 6/week @ 2020-12-25 31/week @ 2021-01-01 14/week @ 2021-01-08 76/week @ 2021-01-15 28/week @ 2021-01-22 66/week @ 2021-01-29 174/week @ 2021-02-05 386/week @ 2021-02-12 169/week @ 2021-02-19

412 downloads per month
Used in 2 crates

Apache-2.0

98KB
2K SLoC

message-io

message-io is an event-driven message library to build network applications easy and fast. The library manages and processes the socket data streams in order to offer a simple event message API to the user. Working as a generic network manager, it allows you to implement your own protocol following some rules, delegating to the library the tedious asynchrony and thread management. See more here.

If you find a problem using the library or you have an improvement idea, do not hesitate to open an issue. Any contribution is welcome!

Motivation

Managing sockets is hard because you need to fight with threads, concurrency, IO errors that come from the OS (which are really difficult to understand in some situations), encoding... And if you make use of non-blocking sockets, it adds a new layer of complexity: synchronize the events that come asynchronously from the OS poll.

message-io offers an easy way to deal with all these mentioned problems, making them transparently for you, the programmer that wants to make an application with its own problems. For that, message-io offers a simple API and give only two concepts to understand: messages (the data you send and receive), and endpoints (the recipients of that data). This abstraction also offers the possibility to use the same API independently of the transport protocol used. You could change the protocol of your application in literally one line.

Features

  • Asynchronous: internal poll event with non-blocking sockets using mio.
  • Multiplatform: see mio platform support.
  • Multiples transports: TCP, UDP (with multicast option) and WebSockets (secure and non-secure option).
  • Internal encoding layer: handle messages, not data streams.
  • FIFO events with timers and priority.
  • Easy, intuitive and consistent API:
    • Follows KISS principle.
    • Abstraction from transport layer: do not think about sockets, think about messages and endpoints.
    • Only two main entities to use:
      • an extensible Eventqueue to manage all events synchronously,
      • a Network to manage all connections (connect, listen, remove, send, receive).
    • Forget concurrence problems: handle thousands of active connections and listeners without any effort. "One thread to rule them all".
    • Easy error handling. Do not deal with dark internal std::io::Error when send/receive from the network.
  • High performance:
    • One thread for manage all internal connections over the faster OS poll.
    • Full duplex socket: simultaneous reading/writing operations over same internal OS sockets.

Getting started

Add to your Cargo.toml

message-io = "0.9"

Documentation

All in one: TCP, UDP and WebSocket echo server

The following example is the simplest server that reads messages from the clients and respond to them. It is capable to manage several client connections and listen from 3 differents protocols at the same time.

use message_io::network::{Network, NetEvent, Transport};

fn main() {
    // Create a Network with an associated event queue for reading its events.
    let (mut network, mut events) = Network::split();

    // Listen for TCP, UDP and WebSocket messages.
    network.listen(Transport::Tcp, "0.0.0.0:3042").unwrap();
    network.listen(Transport::Udp, "0.0.0.0:3043").unwrap();
    network.listen(Transport::Ws, "0.0.0.0:3044").unwrap(); //WebSockets

    loop {
        match events.receive() { // Read the next event or wait until have it.
            NetEvent::Message(endpoint, data) => {
                println!("Received: {}", String::from_utf8_lossy(&data));
                network.send(endpoint, &data);
            },
            NetEvent::Connected(_endpoint) => println!("Client connected"), // Tcp or Ws
            NetEvent::Disconnected(_endpoint) => println!("Client disconnected"), //Tcp or Ws
        }
    }
}

Echo client

The following example shows a client that can connect to the previous server. It sends a message each second to the server and listen its echo response. Changing the Transport::Tcp to Udp or Ws will change the underlying transport used. Also, you can create the number of connections you want at the same time, without any extra thread.

use message_io::network::{Network, NetEvent, Transport};

enum Event {
    Net(NetEvent),
    Tick,
    // Any other app event here.
}

fn main() {
    // The split_and_map() version allows to combine network events with your application events.
    let (mut network, mut events) = Network::split_and_map(|net_event| Event::Net(net_event));

    // You can change the transport to Udp or Websocket.
    let (server, _ ) = network.connect(Transport::Tcp, "127.0.0.1:3042").unwrap();

    events.sender().send(Event::Tick); // Start sending
    loop {
        match events.receive() {
            Event::Net(net_event) => match net_event { // event from the network
                NetEvent::Message(_endpoint, data) => {
                    println!("Received: {}", String::from_utf8_lossy(&data));
                },
                _ => (),
            }
            Event::Tick => { // computed every second
                network.send(server, "Hello server!".as_bytes());
                events.sender().send_with_timer(Event::Tick, std::time::Duration::from_secs(1));
            }
        }
    }
}

Test it yourself!

Clone the repository and test the Ping Pong example (similar to the echo example but more vitaminized).

Run the server:

cargo run --example ping-pong server tcp 3456

Run the client:

cargo run --example ping-pong client tcp 127.0.0.1:3456

You can play with it changing the transport, running several clients, disconnect them, etc. See more here.

Do you need a transport protocol that message-io doesn't have? Add an adapter!

message-io offers two kinds of APIs. The user API, that talks to message-io itself as an user that want to use the library, and the internal adapter API for those who want to add their protocol adapters into the library.

If the protocol can be built in top of mio (most of the existing protocol libraries can), then you can add it to message-io really easy:

  1. Add your adapter file in src/adapters/<my-transport-protocol>.rs that implements the traits that you find here. It contains only 7 mandatory functions to implement (see the template), and take little more than 150 lines to implement an adapter file.

  2. Add a new field in the Transport enum found in src/transport.rs to register your new adapter.

That's all. You can use your new transport with the message-io API like any other.

Oops! one step more, make a Pull request so everyone can use it :)

Dependencies

~6.5MB
~142K SLoC