7 releases (4 breaking)

0.6.0 Feb 8, 2024
0.5.0 Jan 26, 2024
0.4.1 Nov 3, 2023
0.4.0 Oct 16, 2023
0.2.1 Jun 7, 2023

#263 in Asynchronous

Custom license

1MB
21K SLoC

PubNub Rust SDK

PubNub

Tests Validations License: MIT

Make your app come alive with real-time experiences!

Overview

This is the official PubNub Rust SDK repository.

PubNub takes care of the infrastructure and APIs needed for the realtime communication layer of your application. Work on your app's logic and let PubNub handle sending and receiving data across the world in less than 100ms.

Getting started

Below you can find everything you need to start messaging!

Get PubNub keys

You will need the publish and subscribe keys to authenticate your app. Get your keys from the Admin Portal.

Import using Cargo

Add pubnub to your Rust project in the Cargo.toml file:

# default features
[dependencies]
pubnub = "0.6.0"

# all features
[dependencies]
pubnub = { version = "0.6.0", features = ["full"] }

Example

Try the following sample code to get up and running quickly!

use pubnub::subscribe::Subscriber;
use futures::StreamExt;
use tokio::time::sleep;
use std::time::Duration;
use serde_json;
use pubnub::{
    dx::subscribe::Update,
    subscribe::EventSubscriber,
    Keyset, PubNubClientBuilder,
};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    use pubnub::subscribe::{EventEmitter, SubscriptionParams};
    let publish_key = "my_publish_key";
    let subscribe_key = "my_subscribe_key";
    let client = PubNubClientBuilder::with_reqwest_transport()
        .with_keyset(Keyset {
            subscribe_key,
            publish_key: Some(publish_key),
            secret_key: None,
        })
        .with_user_id("user_id")
        .build()?;

    println!("PubNub instance created");

    let subscription = client.subscription(SubscriptionParams {
        channels: Some(&["my_channel"]),
        channel_groups: None,
        options: None
    });

    let channel_entity = client.channel("my_channel_2");
    let channel_entity_subscription = channel_entity.subscription(None);

    subscription.subscribe();
    channel_entity_subscription.subscribe();

    println!("Subscribed to channels");

    // Launch a new task to print out each received message
    tokio::spawn(client.status_stream().for_each(|status| async move {
        println!("\nStatus: {:?}", status)
    }));
    tokio::spawn(subscription.stream().for_each(|event| async move {
        match event {
            Update::Message(message) | Update::Signal(message) => {
                // Silently log if UTF-8 conversion fails
                if let Ok(utf8_message) = String::from_utf8(message.data.clone()) {
                    if let Ok(cleaned) = serde_json::from_str::<String>(&utf8_message) {
                        println!("message: {}", cleaned);
                    }
                }
            }
            Update::Presence(presence) => {
                println!("presence: {:?}", presence)
            }
            Update::AppContext(object) => {
                println!("object: {:?}", object)
            }
            Update::MessageAction(action) => {
                println!("message action: {:?}", action)
            }
            Update::File(file) => {
                println!("file: {:?}", file)
            }
        }
    }));

    // Explicitly listen only for real-time `message` updates.
    tokio::spawn(
        channel_entity_subscription
            .messages_stream()
            .for_each(|message| async move {
                if let Ok(utf8_message) = String::from_utf8(message.data.clone()) {
                    if let Ok(cleaned) = serde_json::from_str::<String>(&utf8_message) {
                        println!("message: {}", cleaned);
                    }
                }
            }),
    );

   sleep(Duration::from_secs(2)).await;

    // Send a message to the channel
    client
        .publish_message("hello world!")
        .channel("my_channel")
        .r#type("text-message")
        .execute()
        .await?;

   // Send a message to another channel
    client
        .publish_message("hello world on the other channel!")
        .channel("my_channel_2")
        .r#type("text-message")
        .execute()
        .await?;

    sleep(Duration::from_secs(15)).await;

    Ok(())
}

You can find more examples in our examples directory!

Features

The pubnub crate is split into multiple features. You can enable or disable them in the Cargo.toml file, like so:

# only blocking and access + default features
[dependencies]
pubnub = { version = "0.6.0", features = ["blocking", "access"] }

# only parse_token + default features
[dependencies]
pubnub = { version = "0.6.0", features = ["parse_token"] }

Available features

Feature name Description Available PubNub APIs
full Enables all non-conflicting features Configuration, Publish, Subscribe, Access Manager, Parse Token, Presence, Crypto Module
default Enables default features: publish, subscribe, serde, reqwest, std Configuration, Publish, Subscribe
publish Enables Publish API Configuration, Publish
access Enables Access Manager API Configuration, Access Manager
parse_token Enables parsing Access Manager tokens Configuration, Parse Token
subscribe Enables Subscribe API Configuration, Subscribe
presence Enables Presence API Configuration, Presence
tokio Enables the tokio asynchronous runtime for Subscribe and Presence APIs n/a
serde Uses serde for serialization n/a
reqwest Uses reqwest as a transport layer n/a
blocking Enables blocking executions of APIs n/a
crypto Enables crypto module for data encryption and decryption n/a
std Enables std library n/a

Documentation

Wasm support

The pubnub crate is compatible with WebAssembly. You can use it in your Wasm project.

no_std support

The pubnub crate is no_std compatible. To use it in a no_std environment, you have to disable the default features and enable the ones you need, for example:

[dependencies]
pubnub = { version = "0.6.0", default-features = false, features = ["serde", "publish",
"blocking"] }

Limitations

The no_std support is limited by the implementation details of the SDK.

The SDK uses the alloc crate to allocate memory for some operations, which means that certain targets aren't supported. Additionally, as we provide a synchronous API, we use some parts of the alloc::sync module, which is also not supported in certain no_std environments.

Some SDK features aren't supported in a no_std environment:

  • partially access module (because of lack of timestamp support)
  • partially reqwest transport (because of the reqwest implementation details)
  • partially subscribe module (because of the spawning tasks and time dependence)
  • partially presence module (because of the spawning tasks and time dependence)
  • std feature (because of the std library)

We depend on a random number generator to generate data for debugging purposes. If you want to use the SDK in a no_std environment, you'll have to provide your own random number generator implementation for certain targets.

See more:

If you're having problems compiling this crate for more exotic targets, you can try to use the extra_platforms feature. Be aware that this feature is not supported and we do not recommend using it.

For more information about this feature. refer to Cargo.toml in the [features] section.

Support

If you need help or have a general question, contact support@pubnub.com.

License

This project is licensed under the MIT license.

Dependencies

~10–25MB
~334K SLoC