Stateroom

Stateroom 是一个用于构建轻量级、单线程服务的极简框架，这些服务通过 WebSockets 发送和接收消息。

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

用法

要创建 Stateroom 服务，实现 SimpleStateroomService 特性。您必须实现的只有一个函数，即构造函数 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 上提供服务。然后，在您的浏览器中打开 https://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

如果有多个客户端连接，每个客户端都将接收到此消息。就这样，我们有了在客户端之间共享某些（非常基本的）应用程序状态的方法。

模块

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

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

参见

Aper是与客舱一起工作的状态同步库。