Crate jamsocket

Jamsocket is a minimalist framework for developing stateful WebSocket applications.

Jamsocket apps implement the SimpleJamsocketService trait, which provides a way for the app to hook into events when clients connect, disconnect, and send messages. Additionally, Jamsocket provides a simple mechanism for invoking events in the future with a timer.

A simple chat server looks like this:

use jamsocket::*;
use std::collections::HashMap;

#[derive(Default)]
struct ChatServer {
    /// The server's only state is a mapping of client ID to username.
    client_to_nickname: HashMap<ClientId, String>,
}

impl SimpleJamsocketService for ChatServer {
    fn new(room_id: &str, _: &impl JamsocketContext) -> Self {
        Default::default()
    }

    /// This is called when a user connects.
    fn connect(&mut self, client: ClientId, ctx: &impl JamsocketContext) {
        let username = format!("client{}", u32::from(client));

        // Send a welcome message.
        ctx.send_message(client,
            &format!("Welcome to the chat! Your name is {}. \
                     Send /nick <username> to change it.",
                     &username));

        // Alert all other connected users to the new user.
        ctx.send_message(MessageRecipient::Broadcast,
            &format!("{} has joined the chat", &username));
    }

    /// This is called when a user disconnects.
    fn disconnect(&mut self, client: ClientId, ctx: &impl JamsocketContext) {
        let username = self.client_to_nickname.remove(&client).unwrap();

        // Alert all remaining users that a user has left.
        ctx.send_message(MessageRecipient::Broadcast,
           &format!("{} has left the chat", &username));
    }

    /// This is called when a user sends a message.
    fn message(&mut self, client: ClientId, message: &str, ctx: &impl JamsocketContext) {
        if let Some(new_nick) = message.strip_prefix("/nick ") {
            // This message is a /nick command, so process accordingly.
            let old_nick = self.client_to_nickname.insert(client, new_nick.to_string()).unwrap();
            ctx.send_message(MessageRecipient::Broadcast,
               &format!("{} is now known as {}", old_nick, new_nick));
        } else {
            // Broadcast the message to all connected users, prefixed by the username.
            let username = self.client_to_nickname.get(&client).unwrap();
            ctx.send_message(MessageRecipient::Broadcast,
               &format!("{}: {}", username, message));
        }
    }
}

Structs

ClientId

SimpleJamsocketServiceFactory

A JamsocketServiceFactory that passes through build() arguments directly to the associated SimpleJamsocketService’s new() constructor, and wraps the result in a WrappedJamsocketService.

WrappedJamsocketService

Combines a SimpleJamsocketService with an owned JamsocketContext in order to implement JamsocketService.

Enums

MessageFromProcess

MessagePayload

MessageRecipient

Represents the recipient(s) of a message.

MessageToProcess

Traits

JamsocketContext

Provides an interface for a JamsocketService instance to send messages back to its host environment.

JamsocketService

The host interface to a Jamsocket service. Implementations should instead implement the trait SimpleJamsocketService.

JamsocketServiceFactory

Enables an object to become a JamsocketService of the associated Service type.

SimpleJamsocketService

A simplified interface for creating a JamsocketService that can be exposed as a WebAssembly module.