Skip to content

Latest commit

 

History

History
294 lines (207 loc) · 6.72 KB

README.md

File metadata and controls

294 lines (207 loc) · 6.72 KB
Raw

Welcome to pusher_rs - The long-missing Rust Pusher crate.

This library is still under heavy development. Currently in use by one of the projects I am working on. 

Open-sourcing it since it has matured to a good level.

A Rust client library for interacting with the Pusher Channels API. This library provides a simple and efficient way to integrate Pusher's real-time functionality into your Rust applications.

Features

  • Connect to Pusher Channels
  • Subscribe to public, private, presence, and private encrypted channels
  • Publish events to channels
  • Handle incoming events
  • Automatic reconnection with exponential backoff
  • Environment-based configuration
  • Flexible channel management
  • Support for Batch Triggers

Todo

  • Improve error handling and logging
  • Add comprehensive test suite
  • Implement WebHooks support
  • Optimize performance for high-load scenarios
  • Create more detailed documentation and examples

Installation

Add this to your Cargo.toml:

[dependencies]
pusher-rs = "0.1.2"

If you want to use a specific branch or commit, you can specify it like this:

[dependencies]
pusher-rs = { git = "https://github.com/username/pusher-rs.git", branch = "main" }
# or
pusher-rs = { git = "https://github.com/username/pusher-rs.git", rev = "commit_hash" }

Configuration

The library uses environment variables for configuration. Create a .env file in your project root with the following variables:

PUSHER_APP_ID=your_app_id
PUSHER_KEY=your_app_key
PUSHER_SECRET=your_app_secret
PUSHER_CLUSTER=your_cluster
PUSHER_USE_TLS=true - this will enforce TLS

Usage

Initializing the client

use pusher_rs::{PusherClient, PusherConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = PusherConfig::from_env()?;
    let mut client = PusherClient::new(config)?;

    // PusherClient::new(config).unwrap()
    
    client.connect().await?;

    Ok(())
}

Connecting

Connect to Pusher:

client.connect().await?;

Subscribing to Channels

Subscribe to a public channel:

client.subscribe("my-channel").await?;

Subscribe to a private channel:

client.subscribe("private-my-channel").await?;

Subscribe to a presence channel:

client.subscribe("presence-my-channel").await?;

Unsubscribing from Channels

client.unsubscribe("my-channel").await?;

Binding to Events

Bind to a specific event on a channel:

use pusher_rs::Event;

client.bind("my-event", |event: Event| {
    println!("Received event: {:?}", event);
}).await?;

Subscribing to a channel

client.subscribe("my-channel").await?;

Publishing an event

client.trigger("my-channel", "my-event", "Hello, Pusher!").await?;

Publishing batch events

use pusher_rs::BatchEvent;

let batch_events = vec![
    BatchEvent {
        channel: "channel-1".to_string(),
        event: "event-1".to_string(),
        data: "{\"message\": \"Hello from event 1\"}".to_string(),
    },
    BatchEvent {
        channel: "channel-2".to_string(),
        event: "event-2".to_string(),
        data: "{\"message\": \"Hello from event 2\"}".to_string(),
    },
];

client.trigger_batch(batch_events).await?;

Handling events

client.bind("my-event", |event| {
    println!("Received event: {:?}", event);
}).await?;

Working with encrypted channels

// Subscribe to an encrypted channel
client.subscribe_encrypted("private-encrypted-channel").await?;

// Publish to an encrypted channel
client.trigger_encrypted("private-encrypted-channel", "my-event", "Secret message").await?;

Channel Types

The library supports four types of channels:

  • Public
  • Private
  • Presence
  • Private Encrypted

Each channel type has specific features and authentication requirements.

Handling Connection State

Get the current connection state:

let state = client.get_connection_state().await;
println!("Current connection state: {:?}", state);

Error Handling

The library uses a custom PusherError type for error handling. You can match on different error variants to handle specific error cases:

use pusher_rs::PusherError;

match client.connect().await {
    Ok(_) => println!("Connected successfully"),
    Err(PusherError::ConnectionError(e)) => println!("Connection error: {}", e),
    Err(PusherError::AuthError(e)) => println!("Authentication error: {}", e),
    Err(e) => println!("Other error: {}", e),
}

Disconnecting

When you're done, disconnect from Pusher:

client.disconnect().await?;

Advanced Usage

Custom Configuration

While the library defaults to using environment variables, you can also create a custom configuration:

use pusher_rs::PusherConfig;
use std::time::Duration;

let config = PusherConfig {
    app_id: "your_app_id".to_string(),
    app_key: "your_app_key".to_string(),
    app_secret: "your_app_secret".to_string(),
    cluster: "your_cluster".to_string(),
    use_tls: true,
    host: Some("custom.pusher.com".to_string()),
    max_reconnection_attempts: 10,
    backoff_interval: Duration::from_secs(2),
    activity_timeout: Duration::from_secs(180),
    pong_timeout: Duration::from_secs(45),
};

Channel Management

The library provides a ChannelList struct for managing subscribed channels:

let mut channel_list = ChannelList::new();
let channel = Channel::new("my-channel");
channel_list.add(channel);

if let Some(channel) = channel_list.get("my-channel") {
    println!("Channel type: {:?}", channel.channel_type());
}

Presence Channels

When subscribing to a presence channel, you can provide user information:

use serde_json::json;

let channel = "presence-my-channel";
let socket_id = client.get_socket_id().await?;
let user_id = "user_123";
let user_info = json!({
    "name": "John Doe",
    "email": "[email protected]"
});

let auth = client.authenticate_presence_channel(&socket_id, channel, user_id, Some(&user_info))?;
client.subscribe_with_auth(channel, &auth).await?;

Tests

Integration tests live under tests/integration_tests

Just run cargo test --test integration_tests -- --nocapture to start.

More tests are being added. This section will be updated accordingly.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Here's how you can contribute:

  • Fork the repository
  • Create your feature branch (git checkout -b feat/amazing-feature)
  • Commit your changes (git commit -m 'feat: Add some amazing feature')
  • Push to the branch (git push origin feat/amazing-feature)
  • Open a Pull Request

License

This project is licensed under the MIT License.