Crate phoenix_channels_client

Phoenix Channels

This crate implements a Phoenix Channels (v2) client in Rust.

Status

NOTE: This client is still a work-in-progress, though it has enough features to support many use cases already. The following is a list of known missing features:

• Reconnect on error/disconnect
• Ability to send binary messages, receive is implemented however
• More thorough integration testing
• Add support for v1 protocol

About

This client was built to support its use in the LiveView Native core library, which is also implemented in Rust.

The client is implemented on top of tokio, and is designed for the Rust async ecosystem, though it is possible to use the client in a non-async application, with the caveat that you still have to pull in tokio and its dependencies to do so.

This client is brand new, so it likely has bugs and missing features. Bug reports/feature requests are welcome though, so if you do find any issues, please let us know on the issue tracker!

Usage

Add to your dependencies like so:

[dependencies]
phoenix_channels_client = { version = "0.1" }

And in your .cargo/config.toml, turn on unstable tokio features we need for eg. cooperative scheduling:

[build]
rustflags = ["--cfg", "tokio_unstable"]

You can also enable nightly features using features = ["nightly"], currently this only is used to make use of a few nightly APIs for operating on slices, which we use while parsing.

Example

use std::time::Duration;
use serde_json::json;

use phoenix_channels_client::{Config, Client};

#[tokio::main]
async fn main() {
    // Prepare configuration for the client
    let mut config = Config::new("ws://127.0.0.1:9002/socket/websocket").unwrap();
    config.set("shared_secret", "supersecret");

    // Create a client
    let mut client = Client::new(config).unwrap();

    // Connect the client
    client.connect().await.unwrap();

    // Join a channel with a timeout
    let channel = client.join("channel:mytopic", Some(Duration::from_secs(15))).await.unwrap();

    // Register an event handler, save the ref returned and use `off` to unsubscribe
    channel.on("some_event", |channel, payload| {
        println!("channel received {} from topic '{}'", payload, channel.topic());
    }).await.unwrap();

    // Send a message, waiting for a reply indefinitely
    let result = channel.send("send_reply", json!({ "name": "foo", "message": "hi"})).await.unwrap();

    // Send a message, waiting for a reply with an optional timeout
    let result = channel.send_with_timeout("send_reply", json!({ "name": "foo", "message": "hello"}), Some(Duration::from_secs(5))).await.unwrap();

    // Send a message, not waiting for a reply
    let result = channel.send_noreply("send_noreply", json!({ "name": "foo", "message": "jeez"})).await.unwrap();

    // Leave the channel
    channel.leave().await;
}

Contributing

Contributions are welcome! Before starting work on any big PRs, it is recommended you open an issue to discuss the work with the maintainers, or you may risk wasting your time implementing something that is already being worked on!

License

Apache 2.0

Structs

Channel

A Channel is created when one joins a topic via Client::join.

Client

A Client manages the underlying WebSocket connection used to talk to Phoenix.

Config

This struct contains configuration for Client

SubscriptionRef

A reference to a specific event handler

Enums

ChannelError

Represents errors that occur when interacting with Channel

ClientError

Represents errors that occur when interacting with a Client

Event

This is a strongly typed wrapper around the event associated with a Message.

Payload

Contains the response payload sent to/received from Phoenix

PhoenixEvent

Represents special events related to management of Phoenix channels.

SendError

Represents errors that occur when sending messages via Channel

Value

Represents any valid JSON value.

Type Aliases

EventHandler

An event handler is a thread-safe callback which is invoked every time an event is received on a channel to which the handler is subscribed.