PubNub Rust SDK 0.6.0
This page outlines the steps to follow to create a simple Hello, World application with PubNub. This covers the basics of integrating PubNub into your application: setting up a connection to PubNub and sending messages.
PubNub account
Sign in or create an account to create an app on the Admin Portal and get the keys to use in your application.
When you create a new app, the first set of keys is generated automatically, but a single app can have as many keysets as you like. We recommend that you create separate keysets for production and test environments.
Download the SDK
Download the SDK from any of the following sources:
Import using Cargo
Add pubnub to your Rust project in the Cargo.toml file:
Get the source code
https://github.com/pubnub/rust
Select 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, Presence, Access Manager, Parse Token |
default | Enables default features: publish, subscribe, serde, reqwest, aescbc, 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 | 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 API | n/a |
aescbc | Enables AES-CBC encryption | n/a |
std | Enables std library | n/a |
Disable standard features
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"] }
For more information, refer to Readme in the Rust SDK GitHub repository.
Configure PubNub
In the IDE of your choice, create a new Rust project. In that project, create a new app.rs file with the following content. This is the minimum configuration you need to send messages with PubNub.
Make sure to provide the publish and subscribe keys from the Admin Portal to your app.
For more information, refer to the Configuration section of the SDK documentation.
Add event listeners
Listeners help your app react to events and messages. You can implement custom app logic to respond to each type of message or event.
In addition to setting up listeners, the following code prints out the content of every received message.
For more information, refer to the Add Listeners section of the SDK documentation.
Publish and subscribe
To receive messages sent to a particular channel, you subscribe to it. When you publish a message to a channel, PubNub delivers that message to everyone who subscribes to that channel.
To subscribe, you send a subscribe() call. It is best to define the channel subscription and the message before you introduce the listeners and send the subscribe call, so make sure to place the relevant code in the appropriate places within your code.
The publish_message() method uses the channel variable that you can see in the following code.
For more information, refer to the Publish section of the SDK documentation and to Publishing a Message.
Putting it all together
Your main() function should now look similar to the following:
Now, run this example and inspect the console output.
Congratulations! You've just subscribed to a channel and sent your first message.
Walkthrough
Instead of focusing on the order in which you wrote the code, let's focus on the order in which it runs. The app you just created does a few things:
- configures a PubNub connection
- subscribes to a channel
- configures event listeners
- publishes a message
Configuring PubNub
The following code is the minimum configuration you need to send and receive messages with PubNub. For more information, refer to the Initialization section of the SDK documentation.
Add event listeners
Listeners help your app react to events and messages. You can implement custom app logic to respond to each type of message or event.
You added several listeners to the app, but only the Message listeners react to events - all other listeners are no-op. You may note that we introduced the same listener - one on the PubNub client level and one on the channel subscription level. Even though they listen for the same message publish event, they can behave entirely differently.
The message listeners respond to incoming messages on a particular channel. When they receive a message, the app prints them to the console. This is why two variations of "hello world" are displayed in the console.
For more information, refer to the Add Listeners section of the SDK documentation.
Publishing and subscribing
PubNub uses the Publish/Subscribe model for real-time communication. This model involves two essential parts:
- Channels are transient paths over which your data is transmitted
- Messages contain the data you want to transmit to one or more recipients
When you want to receive messages sent to a particular channel, you subscribe to it. When you publish a message to a channel, PubNub delivers that message to everyone who is subscribed to that channel. In this example, you subscribe to a channel named my_channel and my_channel_2.
A message can be any type of JSON-serializable data (such as objects, arrays, integers, strings) smaller than 32 KiB. PubNub will, in most cases, deliver your message to its intended recipients in fewer than 100 ms, regardless of their location. You can also share files up to 5MB.
You can subscribe to more than one channel with a single subscribe call, but in this example, you subscribe to two. One subscription is created on the PubNub client, while the other is created directly on the channel:
For more information, refer to the Publish and Subscribe section of the SDK documentation and to Publishing a Message.
Next steps
You have just learned how to use the Rust SDK to send and receive messages using PubNub. Next, look at the SDK's reference documentation covering PubNub API in more detail.