phoenix-channels-rs

A Rust library providing functionality to connect to a phoenix channel.

It is intended to become at least a production grade client however it is very early in development and as such should be treated as experimental.

Currently there are two ways to use this library. The first is a high level threaded client and the second is a low level sender/receiver.

Connecting via the client

Connecting via the client will return a tuple with the Client struct and a mpsc::Receiver of processed incoming messages. This allows for messages to be received in a separate thread if desired.

An very basic example of connecting with the Client:

use std::thread;

extern crate phoenix_channels;
use phoenix_channels::client;


let url = "ws://localhost:4000/socket";

let token = "abcde12345";
let params = vec![("token", token)];

let (client, messages) = client::Client::new(url, params, None).unwrap();

thread::spawn(move || {
    for message in messages {
        println!("{:?}", message);
    }
});

client.join("room:lobby").unwrap();

The client itself will handle the heartbeat and anything else required to deliver a serde json struct to the message iterator result. However, it is an opinionated implementation of a phoenix client and uses threading, mutexes and channels to achieve its end goal of an easy to use interface. This may not be desirable for scenarios where more control is required.

Connecting via the Sender/Receiver

An alternative to the high level Client is to purely use the low level Sender and Receiver structs and handle the threading and heartbeats yourself. The processing of messages is still handled and methods such as join and heartbeat are still conveniently available on the Sender struct (the Client library actually uses these under the hood).

Here is an example of how one can use the Sender/Receiver structs themselves:

use std::thread;
use std::time::Duration;

extern crate phoenix_channels;
use phoenix_channels::client;

let url = "ws://localhost:4000/socket";

let token = "abcde12345";
let params = vec![("token", token)];

let (mut sender, receiver) = client::connect(url, params, None).unwrap();

sender.join("room:lobby").unwrap();

// create a heartbeat thread
thread::spawn(move || {
    loop {
        sender.heartbeat().unwrap();
        thread::sleep(Duration::from_secs(2));
    }
});

for message in receiver {
    println!("{:?}", message);
}

Using the lower level API requires more work but it gives you full control over the threading and flow of messages being sent and received to the server.

Logging

Both the high level and low level APIs use slog under the hood for structured logging. To enable this you can pass your logger via both connect and Client::new by specifying Some(logger) where the examples currently specify None.