The Rust library for interacting with the Pusher HTTP API.
This package lets you trigger events to your client and query the state of your Pusher channels. When used with a server, you can validate Pusher webhooks and authenticate private- or presence-channels.
The functions that make HTTP requests are async, so you will need to run them with an executer like tokio. The library is a wrapper around the hyper client.
In order to use this library, you need to have a free account on http://pusher.com. After registering, you will need the application credentials for your app.
This README is meant to give an overview of the library, but more in-depth documentation can be found on our GitHub page.
Add to your Cargo.toml:
rust
pusher="*"
``rust
extern crate pusher; // imports thepushermodule
extern crate futures; //pusher` is async, so we need to block on the future in this example
use pusher::PusherBuilder; // brings the PusherBuilder into scope use futures::executor::block_on;
fn main(){ // initializes a Pusher object with your app credentials let pusher = PusherBuilder::new("APP_ID", "KEY", "SECRET").finalize();
// triggers an event called "myevent" on a channel called "testchannel", with the payload "hello world!" blockon(pusher.trigger("testchannel", "my_event", "hello world!")); } ```
There easiest way to configure the library is by creating a new Pusher instance:
rust
let pusher = PusherBuilder::new("id", "key", "secret").finalize();
PusherBuilder::new returns a PusherBuilder, on which to chain configuration methods, before calling finalize().
rust
PusherBuilder::from_url("http://key:secret@api.host.com/apps/id").finalize();
rust
PusherBuilder::from_env("PUSHER_URL").finalize();
This is particularly relevant if you are using Pusher as a Heroku add-on, which stores credentials in a "PUSHER_URL" environment variable.
To ensure requests occur over HTTPS, call secure() before finalize().
rust
let pusher = PusherBuilder::new("id", "key", "secret").secure().finalize();
Calling host() before finalize() will make sure requests are sent to your specified host.
rust
let pusher = PusherBuilder::new("id", "key", "secret").host("foo.bar.com").finalize();
By default, this is "api.pusherapp.com".
hyper::client::connect::ConnectThe above functions have equivalent functions that also allow a custom Connect to be provided. E.g.:
rust
let pusher = PusherBuilder::new_with_client(my_client, "id", "key", "secret").host("foo.bar.com").finalize();
It is possible to trigger an event on one or more channels. Channel names can contain only characters which are alphanumeric, _ or `-`` and have to be at most 200 characters long. Event name can be at most 200 characters long too.
async fn trigger<S: serde::Serialize>(&self, channel: &str, event: &str, payload: S)|Argument |Description |
|:-:|:-:|
|channel &str |The name of the channel you wish to trigger on. |
|event &str | The name of the event you wish to trigger |
|data S: serde::Serialize | The payload you wish to send. Must be marshallable into JSON. |
|Return Value|Description|
|:-:|:-:|
|result Result<TriggeredEvents, String> | If the trigger was successful and you are connected to certain clusters, an object containing the event_ids field will be returned as part of a Result. An Err value will be returned if any errors were encountered. |
```rust let mut hashmap = HashMap::new(); hashmap.insert("message", "hello world");
pusher.trigger("testchannel", "myevent", &hash_map).await; ```
async fn trigger_multi<S: serde::Serialize>(&self, channels: &[&str], event: &str, payload: S)|Argument | Description |
|:-:|:-:|
|channels &[&str]| A vector of channel names you wish to send an event on. The maximum length is 10.|
|event &str | As above.|
|data S: serde::Serialize |As above.|
|Return Value|Description|
|:-:|:-:|
|result Result<TriggeredEvents, String> | As above. |
```rust let channels = vec!["testchannel", "testchannel2"];
pusher.triggermulti(&channels, "myevent", "hello").await; ```
trigger_exclusive and trigger_multi_exclusive follow the patterns above, except a socket_id is given as the last parameter.
These methods allow you to exclude a recipient whose connection has that socket_id from receiving the event. You can read more here.
On one channel:
rust
pusher.trigger_exclusive("test_channel", "my_event", "hello", "123.12").await;
On multiple channels:
rust
let channels = vec!["test_channel", "test_channel2"];
pusher.trigger_multi_exclusive(&channels, "my_event", "hello", "123.12").await;
Application security is very important so Pusher provides a mechanism for authenticating a user’s access to a channel at the point of subscription.
This can be used both to restrict access to private channels, and in the case of presence channels notify subscribers of who else is also subscribed via presence events.
This library provides a mechanism for generating an authentication signature to send back to the client and authorize them.
For more information see our docs.
fn authenticate_private_channel(&self, channel_name: &str, socket_id: &str)|Argument|Description|
|:-:|:-:|
|channelname &str| The channel name in the request sent by the client|
|socketid &str| The socket id in the request sent by the client|
|Return Value|Description|
|:-:|:-:|
|Result <String, &str> | The Ok value will be the response to send back to the client, carrying an authentication signature. An Err value will be a string describing any errors generated |
rust
async fn pusher_auth(req: Request<Body>) -> Result<Response<Body>, Error> {
let body = to_bytes(req).await.unwrap();
let params = parse(body.as_ref()).into_owned().collect::<HashMap<String, String>>();
let channel_name = params.get("channel_name").unwrap();
let socket_id = params.get("socket_id").unwrap();
let auth_signature = pusher.authenticate_private_channel(channel_name, socket_id).unwrap();
Ok(Response::new(auth_signature.into()))
}
Using presence channels is similar to private channels, but in order to identify a user, clients are sent a user_id and, optionally, custom data.
fn authenticate_presence_channel(&self, channel_name: &str, socket_id: &str, member: &Member)|Argument|Description|
|:-:|:-:|
|channelname &str| The channel name in the request sent by the client|
|socketid &str| The socket id in the request sent by the client|
|member &pusher::Member| A struct representing what to assign to a channel member, consisting of a user_id and any custom user_info. See below |
pusher::Member
rust
pub struct Member<'a> {
pub user_id: &'a str,
pub user_info: Option<HashMap<&'a str, &'a str>>,
}
```rust
async fn pusherauth(req: Request) -> Result
let mut memberdata = HashMap::new(); memberdata.insert("twitter", "jamiepatel"); let member = pusher::Member{userid: "4", userinfo: Some(member_data)};
let authsignature = pusher.authenticatepresencechannel(channelname, socketid, &member).unwrap(); Ok(Response::new(authsignature.into())) } ```
This library allows you to query our API to retrieve information about your application's channels, their individual properties, and, for presence-channels, the users currently subscribed to them.
async fn channels(&self)Requesting a list of application channels without any query options.
|Return Value|Description|
|:-:|:-:|
|result Result<ChannelList, String>| The Ok value will be a struct representing the list of channels. See below. An Err value will represent any errors encountered.|
async fn channels_with_options(&self, params: QueryParameters)Adding options to your channels request.
|Argument|Description|
|:-:|:-:|
|params QueryParameters| A vector of tuples with query options. Where the first value of a tuple is "filter_by_prefix", the API will filter the returned channels with the second value. To get number of users subscribed to a presence-channel, specify an "info" value in a tuple with a corresponding "user_count" value. |
|Return Value|Description|
|:-:|:-:|
|result Result<ChannelList, String>| As above.|
pusher::ChannelsList
rust
pub struct ChannelList {
pub channels: HashMap<String, Channel>,
}
pusher::Channel
```rust
pub struct Channel {
pub occupied: Option
```
Without options:
rust
pusher.channels().await;
//=> Ok(ChannelList { channels: {"presence-chatroom": Channel { occupied: None, user_count: None, subscription_count: None }, "presence-notifications": Channel { occupied: None, user_count: None, subscription_count: None }} })
With options:
rust
let channels_params = vec![("filter_by_prefix", "presence-"), ("info", "user_count")];
pusher.channels_with_options(channels_params).await;
//=> Ok(ChannelList { channels: {"presence-chatroom": Channel { occupied: None, user_count: Some(92), subscription_count: None }, "presence-notifications": Channel { occupied: None, user_count: Some(29), subscription_count: None }} })
async fn channel(&self, channel_name: &str)Requesting the state of a single channel without any query options.
|Return Value|Description|
|:-:|:-:|
|result Result<Channel, String>| The Ok value will be a struct representing a channel. See above. An Err value will represent any errors encountered.|
async fn channel_with_options(&self, channel_name: &str, params: QueryParameters)Adding options to your channel request.
|Argument|Description|
|:-:|:-:|
|channelname &str| The name of the channel|
|params QueryParameters| A vector of tuples with query options. To request information regarding usercount and subscription_count, a tuple must have an "info" value and a value containing a comma-separated list of attributes. An Err will be returned for any invalid API requests. |
|Return Value|Description|
|:-:|:-:|
|result Result<Channel, String>| As above.|
Without options:
rust
pusher.channel("presence-chatroom").await;
//=> Ok(Channel { occupied: Some(true), user_count: None, subscription_count: None })
With options:
rust
let channel_params = vec![("info", "user_count,subscription_count")];
pusher.channel_with_options("presence-chatroom", channel_params).await;
//=> Ok(Channel { occupied: Some(true), user_count: Some(96), subscription_count: Some(96) })
async fn channel_users(&self, channel_name : &str)|Argument|Description|
|:-:|:-:|
|channel_name &str| The channel name|
|Return Value|Description|
|:-:|:-:|
|result Result<ChannelUserList, String>| The Ok value will be a struct representing a list of the users subscribed to the presence-channel. See below. The Err value will represent any errors encountered. |
pusher::ChannelUserList
rust
pub struct ChannelUserList {
pub users: Vec<ChannelUser>,
}
pusher::ChannelUser
rust
pub struct ChannelUser {
pub id: String,
}
rust
pusher.channel_users("presence-chatroom").await;
//=> Ok(ChannelUserList { users: [ChannelUser { id: "red" }, ChannelUser { id: "blue" }] })
On your dashboard, you can set up webhooks to POST a payload to your server after certain events. Such events include channels being occupied or vacated, members being added or removed in presence-channels, or after client-originated events. For more information see https://pusher.com/docs/webhooks.
This library provides a mechanism for checking that these POST requests are indeed from Pusher, by checking the token and authentication signature in the header of the request.
fn webhook(&self, key: &str, signature: &str, body: &str)|Argument|Description|
|:-:|:-:|
|key &str | The key supplied in the "X-Pusher-Key" header |
|signature &str | The signature supplied in the "X-Pusher-Signature" header |
|body &str | The body of the request |
|Return Value|Description|
|:-:|:-:|
|result Result<Webhook, &str>| If the webhook is valid, the Ok value will be a representation of that webhook that includes its timestamp and associated events. If the webhook is invalid, an Err value will be passed.|
pusher::Webhook
rust
pub struct Webhook {
pub time_ms: i64,
pub events: Vec<HashMap<String, String>>,
}
rust
pusher.webhook("supplied_key", "supplied_signature", "body")
Feature | Supported -------------------------------------------| :-------: Trigger event on single channel | ✔ Trigger event on multiple channels | ✔ Excluding recipients from events | ✔ Authenticating private channels | ✔ Authenticating presence channels | ✔ Get the list of channels in an application | ✔ Get the state of a single channel | ✔ Get a list of users in a presence channel | ✔ WebHook validation | ✔ Heroku add-on support | ✔ Debugging & Logging | ✔ Cluster configuration | ✔ HTTPS | ✔ Timeouts | ✘ HTTP Proxy configuration | ✘ HTTP KeepAlive | ✘
These are helpers that have been implemented to to ensure interactions with the HTTP API only occur if they will not be rejected e.g. channel naming conventions.
Helper Functionality | Supported -----------------------------------------| :-------: Channel name validation | ✔ Limit to 10 channels per trigger | ✔ Limit event name length to 200 chars | ✔
Feel more than free to fork this repo, improve it in any way you'd prefer, and send us a pull request :)
Simply type:
bash
$ cargo test
This code is free to use under the terms of the MIT license.