Stateroom

Stateroom 是一个用于构建轻量级、单线程服务并通过 WebSocket 发送和接收消息的最简框架。

服务可以是运行在服务器进程中的本地 Rust 代码，也可以编译成 WebAssembly 模块并动态加载。

用法

要创建 Stateroom 服务，实现 SimpleStateroomService trait。你只需要实现一个函数，即构造函数 new。

让我们实现一个简单的共享计数器。任何连接的客户端都可以通过发送 increment 或 decrement 消息来增加或减少它（其他消息将被忽略）。每当值发生变化时，我们将将其广播给所有连接的客户端。

use stateroom_wasm::*;

#[stateroom_wasm]
#[derive(Default)]
struct EchoServer;

impl StateroomService for EchoServer {
    fn connect(&mut self, client_id: ClientId, ctx: &impl StateroomContext) {
        ctx.send_message(client_id, format!("User {:?} connected.", client_id));
    }

    fn message(&mut self, client_id: ClientId, message: MessagePayload, ctx: &impl StateroomContext) {
        let Some(message) = message.text() else {
            return;
        };

        ctx.send_message(
            MessageRecipient::Broadcast,
            format!("User {:?} sent '{}'", client_id, message),
        );
    }

    fn disconnect(&mut self, client_id: ClientId, ctx: &impl StateroomContext) {
        ctx.send_message(
            MessageRecipient::Broadcast,
            format!("User {:?} left.", client_id),
        );
    }
}

要提供此服务，我们将将其编译成 WebAssembly 模块。我们导入 #[stateroom_wasm] 注解宏并将其应用于现有的 SharedCounter 声明。

use stateroom_wasm::*;

#[stateroom_wasm]
#[derive(Default)]
struct SharedCounter(i32);

impl StateroomService for SharedCounter {}

然后，安装 stateroom 命令行工具和 wasm32-wasi 目标，并运行 stateroom dev

$ cargo install stateroom-cli
$ rustup target add wasm32-wasi
$ stateroom dev

stateroom dev 将构建您的应用程序并在端口 :8080 上提供服务。然后，在您的浏览器中打开 http://127.0.0.1:8080/status -- 如果一切顺利，您应该看到状态消息 ok。打开浏览器中的开发者工具并输入

let ws = new WebSocket('ws://127.0.0.1:8080/ws');
ws.onmessage = (c) => console.log(c.data);

这将连接到您的服务，如果不存在，将创建一个 ID 为 1 的新房间（在默认服务器设置下，任何字符串都是有效的房间 ID，连接到不存在的房间将创建它）。

现在，您可以通过使用 ws 处理程序发送 increment 消息来增加计数器。

ws.send('increment')

如果一切设置正确，结果将被打印出来

new value: 1

如果有多个客户端连接，每个客户端都将收到此消息。就是这样，我们有一个机制在客户端之间共享一些（非常基础）的应用状态。

模块

Stateroom具有模块化架构。如果您只想生成一个与现有的Stateroom WebAssembly服务器一起提供服务的Stateroom服务，您可能需要与以下主要crate交互：stateroom-cli，它提供了一个命令行工具，以及stateroom-wasm，它是构建服务的最主要Cargo依赖项。

• stateroom是服务接口的核心，最小实现。
• stateroom-cli是一个用于与WebAssembly编译的Stateroom服务交互的命令行界面。
• stateroom-server提供了一个基于Axum的WebSocket服务器，该服务器运行Stateroom服务。
• stateroom-wasm提供了一个从Stateroom服务生成WebAssembly模块的宏。
• stateroom-wasm-host提供了一种从WebAssembly模块导入Stateroom服务的方法。

另请参阅

Aper是一个与Stateroom一起工作的状态同步库。