websocket-std

这是一个利用Rust标准库实现的WebSocket。其目标是运行在低资源设备上，如微控制器，尽管它也可以应用于高性能计算机程序。我开始这个项目主要有三个原因

• 学习Rust。
• 在crates.io上发布一个库。
• 如何从其他语言中使用这个库。

项目目前处于测试阶段，尽管它功能齐全，但仍需进一步工作才能推出最终版本。由于我是一名独立开发者，无法投入我期望的时间，因此我决定将其发布给那些想尝试它并为其做出贡献的人 CONTRIBUTING.md。

您可以使用以下方式使用此库

• 在任何允许使用标准库的Rust项目中，例如支持std的esp-rs。有关更多信息，请参阅esp-rs文档。
• 在任何C项目中，因为它具有兼容的FFI（Foreign Function Interface）。您需要将项目作为静态库编译并适当地链接。有关详细信息，请参阅此指南静态库使用。

请自由探索该项目并做出贡献！🚀

静态库

在ffi/文件夹中，您可以找到websocket-std.h头文件以及Espressif的esp32微控制器的xtensa架构编译的静态库。

您可以在esp idf和arduino项目中使用此静态库进行esp32开发。有关更多信息，请参阅ffi/xtensa-esp32-idf。

示例

示例文件夹包含了如何使用websocket-std的多种示例。

特性

同步客户端

同步客户端管理一个内部事件循环，当您调用一个函数来执行WebSocket操作（init、send等）时，它将被排队，一旦您调用event_loop函数，它将在一次执行中执行一个输入（接收到了某些内容）和一个输出（需要发送到服务器的某些内容）操作。

您还可以使用threads与库一起工作。请参阅示例以获取更多信息。

功能

• 发送文本消息。
• 处理接收到的文本消息。
• 处理连接事件。
• 处理关闭事件。
• 与WebSocket协议一起工作。
• 设置WebSocket为每个数据帧发送文本的最大长度。

即将推出

• WebSocket over SSL。
• 发送和接收二进制数据。
• WebSocket扩展。

同步服务器

我计划在库中引入一个与同步客户端相同理念的sync server。

已测试的MCU

• ESP32使用esp-rs与标准支持
• ESP32使用arduino框架在PlatformIO项目中。（也应在esp-idf项目中工作）。

测试

由于这是我第一个Rust大型项目，我开始使用以下工具进行测试和代码覆盖率，但我希望定义另一种方法，因为测试覆盖率报告不是最好的。我愿意听取更好的Rust测试方法。

执行所有测试

cargo test

生成覆盖率报告

要求

安装grcov工具

1. 安装llvm-tools或llvm-tools-preview组件

rustup component add llvm-tools-preview

2. 确保以下环境变量已设置

export RUSTFLAGS="-Cinstrument-coverage"

3. 确保每个测试运行都通过定义LLVM_PROFILE_FILE环境变量来获得自己的配置文件信息（%p将被进程ID替换，%m将被二进制签名替换）

export LLVM_PROFILE_FILE="websocket-std-%p-%m.profraw"

4. 安装grcov

cargo install grcov

生成报告

确保没有编译或测试错误。

1. 构建代码

cargo build

2. 运行测试并确保所有都是OK

cargo test

3. 确保变量已导出。

• RUSTFLAGS
• LLVM_PROFILE_FILE

4. 生成HTML覆盖率报告

grcov . --binary-path ./target/debug/deps/ -s . -t html --branch --ignore-not-existing --ignore '../*' --ignore "/*" -o target/coverage --excl-line grcov-excl-line

报告将在target/coverage/生成，用浏览器打开index.html以查看结果。

Python WebSocket服务器

由于库没有创建WebSocket服务器的方法，这里提供了一个Python echo服务器示例来测试客户端。

要求

• pip install websockets==11.0.3

代码

import asyncio
from websockets.server import serve

HOST  = "0.0.0.0"
PORT  = 3000
protocol = ["superchat", "app", "chat"]

async def echo(websocket):
    async for message in websocket:
        if websocket.open:
            await websocket.send(message)

async def main():
    async with serve(echo, HOST, PORT, subprotocols=protocol):
        print(f"Websocket server running on: {HOST}:{PORT}")
        await asyncio.Future()  # run forever

asyncio.run(main())