Initial Dever 0.0.1

lib/doc/dever-websocket.md

@@ -0,0 +1,112 @@
+# WebSocket
+
+使用 HTTP/1 升级，连接随创建任务或服务 handler 结束而关闭。不支持 HTTP/2 升级、子协议或压缩。
+
+## dever.websocket.Limits
+
+限制完整消息、接收等待和写入期限。
+
+字段：
+- `message_bytes`：完整消息字节上限
+- `idle_ms`：一次接收的毫秒期限
+- `write_ms`：写入和握手的毫秒期限
+
+## dever.websocket.Message
+
+协议引擎交付完整消息；Ping 和 Pong 最多 125 字节。
+
+分支：
+- `Text(value: Text)`：文本
+- `Binary(value: Bytes)`：二进制
+- `Ping(value: Bytes)`：保活请求
+- `Pong(value: Bytes)`：保活响应
+
+## dever.websocket.ConnectResult
+
+WebSocket 连接或协议升级的结果。
+
+分支：
+- `Connected(socket: dever.system.WebSocket)`：已连接
+- `error Failed(message: Text)`：连接失败
+
+## dever.websocket.ReceiveState
+
+区分完整消息与正常关闭。
+
+分支：
+- `Read(message: Message)`：完整消息
+- `End`：正常关闭
+
+## dever.websocket.ReceiveResult
+
+接收操作的显式捕获结果。
+
+分支：
+- `Done(state: ReceiveState)`：接收状态
+- `error Failed(message: Text)`：接收失败
+
+## dever.websocket.SystemReceiveResult
+
+系统边界结果在库内转换为公开接收状态。
+
+分支：
+- `Read(message: Message)`：完整消息
+- `End`：正常关闭
+- `error Failed(message: Text)`：接收失败
+
+## dever.websocket.MessageEvent
+
+流在故障时产生一次失败后结束。
+
+分支：
+- `Read(message: Message)`：完整消息
+- `error Failed(message: Text)`：终止失败
+
+## dever.websocket.defaultLimits
+
+默认消息 1 MiB、接收 60 秒、写入与握手 5 秒。
+
+## dever.websocket.accept
+
+只升级当前 HTTP/1.1 请求。失败时仍可回复普通 HTTP 响应；handler 退出关闭所有 socket 别名。
+
+## dever.websocket.connect
+
+连接数字 IP 和 origin-form 路径，不自动重试。
+
+## dever.websocket.open
+
+支持 ws/wss 和 DNS；WSS 校验证书和目标名称，拒绝用户信息及 fragment。
+未声明端口时使用协议默认端口；显式端口非法时在连接前报错。
+
+## dever.websocket.connected
+
+取出 WebSocket；连接失败时继续传播错误。
+
+## dever.websocket.send
+
+发送一次完整消息；方向锁与写入共用期限，已开始写帧的取消会关闭连接。
+
+## dever.websocket.wrote
+
+消息发送成功时继续执行，失败时传播错误。
+
+## dever.websocket.receive
+
+按需读取协议帧，先回复 Ping 再交付应用；接收超时关闭资源。
+
+## dever.websocket.receiveState
+
+正常关闭映射为 End，协议失败保持 ReceiveResult 身份。
+
+## dever.websocket.messages
+
+惰性消费消息；正常关闭结束，终止故障只产生一次 Failed；关闭流释放源别名。
+
+## dever.websocket.close
+
+校验关闭码和至多 123 UTF-8 字节原因，并在写期限内等待对端关闭。
+
+## dever.websocket.closed
+
+关闭成功时继续执行，失败时传播错误。