Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

How to use dnet

dnet is a easy-to-use async messaging abstraction. You define the message shapes your application needs, choose a transport and a codec, then send and receive messages over that transport.

This page uses TCP examples, but the same concepts apply to other transports such as WebSocket, UDP, channel transport, etc.

Dependencies

To use dnet, add it to your Cargo.toml, along with serde for message serialization and futures for async stream and sink extensions:

[dependencies]
dnet = "*"
serde = { version = "*", features = ["derive"] }
futures = "*"

Messages

Define the messages your application will send and receive. Use serde to derive serialization and deserialization for your message types.

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
pub struct ServerMessage {
    some_string: String,
    some_int: u32,
}

Incoming and outgoing messages can be of different types:

#[derive(Serialize, Deserialize)]
pub struct ClientMessage {
    some_float: f64,
}

Transport

A transport wraps an underlying I/O channel and provides dnet message send/receive operations.

Note

Different transports require different setup of the underlying protocol/channel/etc. before they can wrap them. See the transport documentation for details.

use dnet::{codecs::BincodeCodec, tcp::TcpTransport};
use tokio::net::TcpStream;

let stream = TcpStream::connect("127.0.0.1:8080").await?;
let mut transport = TcpTransport::<_, _, ClientMessage, ServerMessage>::buffered(
    stream,
    BincodeCodec::default(),
);

Sending

Send values with future’s SinkExt send(...):

use futures::SinkExt;

transport.send(ServerMessage { 
    some_string: "Hello, world!".into(), 
    some_int: 42 
}).await?;

Receiving

Receive values with future’s StreamExt next():

use futures::StreamExt;

match transport.next().await {
    Some(Ok(message)) => {
        println!("received message from the server: {}", message.some_string);
        transport.send(ClientMessage { some_float: 3.14 }).await?;
    }
    Some(Err(error)) => {
        // handle receive error
    }
    None => {
        // transport closed
    }
}

or by using the receive() method:

use dnet::Receive as _;

let incoming: ClientMessage = transport.receive().await?;
println!("received message from the client: {}", message.some_float);

Logging

dnet transports support logging via the Logging trait (enabled with the “logging” feature). To see transport logs, initialize a tracing subscriber from tracing-subscriber, then enable logging on the transport.

[dependencies]
dnet = { version = "*", features = ["logging"] }
tracing-subscriber = "*"
use dnet::{codecs::BincodeCodec, tcp::TcpTransport};
use tracing_subscriber;

tracing_subscriber::fmt().init();

let stream = TcpStream::connect("127.0.0.1:8080").await?;
let mut transport = TcpTransport::<_, _, ServerMessage, ClientMessage>::buffered(
    stream,
    BincodeCodec::default(),
);
// optionally: transport.set_logging_name("tcp-client");
transport.enable_logging();

Examples

See the repository examples for complete working code.