Merge pull request #143 from lxzan/dev

update readme

Author: lxzan

README.md

@@ -5,7 +5,7 @@
 	<img src="assets/logo.png" alt="logo" width="300px">
 </div>
 
-<h3 align="center">Simple, Fast, Reliable WebSocket Server & Client</h3>
+<h3 align="center">Simple · High Performance · Reliable WebSocket Server & Client Library</h3>
 
 <div align="center">
 
@@ -21,32 +21,28 @@
 
 ### Introduction
 
-GWS (Go WebSocket) is a very simple, fast, reliable and feature-rich WebSocket implementation written in Go. It is
-designed to be used in highly-concurrent environments, and it is suitable for
-building `API`, `Proxy`, `Game`, `Live Video`, `Message`, etc. It supports both server and client side with a simple API
-which mean you can easily write a server or client by yourself.
+GWS (Go WebSocket) is a **simple, high‑performance and feature‑complete** WebSocket library written in Go.  
+It is designed for **high‑concurrency** scenarios and is ideal for building **API gateways, long‑lived connection hubs, reverse proxies, IM / chat, online games, real‑time streaming, and push / subscribe systems**.  
+GWS exposes an extremely **minimal, event‑driven API**, so you can build a stable WebSocket server or client with very little code.
 
-GWS developed base on Event-Driven model. every connection has a goroutine to handle the event, and the event is able
-to be processed in a non-blocking way.
+GWS is built on an event‑driven model: every connection has its own goroutine to drive the event loop, and events can be processed in a non‑blocking way.
 
 ### Why GWS
 
-- <font size=3>Simplicity and Ease of Use</font>
+- <font size=3>Simplicity & Developer Experience</font>
 
-    - **User-Friendly**: Simple and clear `WebSocket` Event API design makes server-client interaction easy.
-    - **Code Efficiency**: Minimizes the amount of code needed to implement complex WebSocket solutions.
+    - **Event‑driven & intuitive**: The `Event` interface (`OnOpen / OnMessage / OnClose / OnPing / OnPong`) mirrors how you think about WebSocket lifecycles.
+    - **High coding efficiency**: Protocol details are hidden behind a small, clear API, so you can focus almost entirely on business logic.
 
-- <font size=3>High-Performance</font>
+- <font size=3>High Performance</font>
 
-    - **High IOPS Low Latency**: Designed for rapid data transmission and reception, ideal for time-sensitive
-      applications.
-    - **Low Memory Usage**: Highly optimized memory multiplexing system to minimize memory usage and reduce your cost of
-      ownership.
+    - **High throughput & low latency**: Carefully tuned for WebSocket workloads such as echo servers and long‑lived push streams, making it a great fit for latency‑sensitive applications.
+    - **Low memory footprint**: Aggressive buffer reuse and compression strategies significantly reduce memory and CPU cost under heavy concurrency.
 
-- <font size=3>Reliability and Stability</font>
-    - **Robust Error Handling**: Advanced mechanisms to manage and mitigate errors, ensuring continuous operation.
-    - **Well-Developed Test Cases**: Passed all `Autobahn` test cases, fully compliant with `RFC 7692`. Unit test
-      coverage is almost 100%, covering all conditional branches.
+- <font size=3>Reliability & Standards Compliance</font>
+
+    - **Robust error handling**: Clear, well‑defined behaviors for connection errors, protocol violations, compression failures, etc.
+    - **Battle‑tested**: Passes all `Autobahn` test cases and is compliant with `RFC 6455` / `RFC 7692`. Unit tests cover almost all conditional branches.
 
 ### Benchmark
 
@@ -100,19 +96,20 @@ ok      github.com/lxzan/gws    17.231s
 
 ### Feature
 
-- [x] Event API
-- [x] Broadcast
-- [x] Dial via Proxy
-- [x] Context-Takeover 
-- [x] Concurrent & Asynchronous Non-Blocking Write
-- [x] Segmented Writing of Large Files
-- [x] Passed Autobahn Test Cases [Server](https://lxzan.github.io/gws/reports/servers/) / [Client](https://lxzan.github.io/gws/reports/clients/)
+- [x] **Event‑driven API** based on the `Event` interface, similar to common WebSocket SDKs.
+- [x] **Broadcast support** via `Broadcaster`, which reuses compressed frames for efficient fan‑out.
+- [x] **Dial via proxy** using a customizable `Dialer` (e.g. SOCKS5 / HTTP proxy).
+- [x] **Context‑takeover (permessage‑deflate)** with configurable sliding window sizes.
+- [x] **Segmented writing of large files** with `WriteFile` to reduce peak memory during large transfers.
+- [x] **Concurrent & asynchronous non‑blocking write** with built‑in task queues and `Writev` / `WritevAsync`.
+- [x] **Strong standards compatibility**, passing all Autobahn test cases  
+  [Server report](https://lxzan.github.io/gws/reports/servers/) / [Client report](https://lxzan.github.io/gws/reports/clients/)
 
 ### Attention
 
-- The errors returned by the gws.Conn export methods are ignorable, and are handled internally.
-- Transferring large files with gws tends to block the connection.
-- If HTTP Server is reused, it is recommended to enable goroutine, as blocking will prevent the context from being GC.
+- For most business use‑cases, errors returned by exported methods on `gws.Conn` can be treated as **informational**: the library has already taken appropriate action internally (e.g. closing the connection, emitting events).
+- When transferring **very large files**, a single connection may occupy bandwidth and I/O for a long time; you may want throttling, sharding or other flow‑control at the business layer.
+- If you reuse `net/http` (e.g. call `Upgrade` inside an HTTP handler), always call `ReadLoop` inside a **separate goroutine**, otherwise blocking will prevent the request context from being garbage‑collected in time.
 
 ### Install
 

README_CN.md

@@ -3,7 +3,7 @@
 	<img src="assets/logo.png" alt="logo" width="300px">
 </div>
 
-<h3 align="center">简单, 快速, 可靠的 WebSocket 服务器和客户端</h3>
+<h3 align="center">简单 · 高性能 · 可靠 的 WebSocket 服务器与客户端库</h3>
 
 <div align="center">
 
@@ -19,24 +19,26 @@
 
 ### 介绍
 
-GWS（Go WebSocket）是一个用 Go 编写的非常简单、快速、可靠且功能丰富的 WebSocket 实现。它设计用于高并发环境，构建"接口", "代理", "游戏", "流媒体", "消息发布订阅"等服务。它提供非常简单的 API,
-您可以轻松编写自己的服务器或客户端。
+GWS（Go WebSocket）是一个使用 Go 编写的、**简单、高性能且功能完备**的 WebSocket 库。  
+它专为高并发场景设计，非常适合构建 **接口服务、长连接网关、代理、IM / 聊天室、游戏、实时流媒体、消息推送 / 订阅** 等系统。  
+GWS 提供了**极简的事件驱动 API**，你可以用极少的代码构建出稳定可靠的 WebSocket 服务器或客户端。
 
 ### 为什么选择 GWS
 
 - <font size=3>简单易用</font>
 
-  - **用户友好**: 简洁明了的 `WebSocket` 事件接口设计，让服务器和客户端的交互变得轻松简单.
-  - **编码效率**: 最大限度地减少实施复杂的解决方案所需的代码量.
+  - **事件友好**：基于 `Event` 接口的事件驱动模型，`OnOpen / OnMessage / OnClose / OnPing / OnPong` 一目了然。
+  - **编码效率高**：隐藏协议细节，最大限度减少业务代码量，上手几乎零成本。
 
 - <font size=3>性能出众</font>
 
-  - **高吞吐低延迟**: 专为快速传输和接收数据而设计，是时间敏感型应用的理想之选.
-  - **低内存占用**: 高度优化的内存复用系统, 最大限度降低内存使用量，降低您的成本.
+  - **高吞吐 / 低延迟**：针对 WebSocket 场景深度优化，在 Echo、长连接推送等场景下表现优秀。
+  - **低内存占用**：内建高效的 buffer 复用和压缩策略，在高并发场景下显著降低内存与 CPU 成本。
 
 - <font size=3>稳定可靠</font>
-  - **健壮的错误处理**: 管理和减少错误的先进机制，确保持续运行.
-  - **完善的测试用例**: 通过了所有 `Autobahn` 测试用例, 符合 `RFC 7692` 标准. 单元测试覆盖率几乎达到 100%, 覆盖所有条件分支.
+
+  - **健壮的错误处理**：对连接异常、协议错误、压缩异常等都提供清晰的处理路径。
+  - **测试完备**：通过全部 `Autobahn` 用例，兼容 `RFC 6455` / `RFC 7692`，单元测试覆盖率接近 100%，覆盖所有条件分支。
 
 ### 基准测试
 
@@ -90,19 +92,20 @@ ok      github.com/lxzan/gws    17.231s
 
 ### 特性
 
-- [x] 事件驱动式 API
-- [x] 广播
-- [x] 代理拨号
-- [x] 上下文接管 
-- [x] 大文件分段写入
-- [x] 支持并发和异步非阻塞写入
-- [x] 通过所有 Autobahn 测试用例 [Server](https://lxzan.github.io/gws/reports/servers/) / [Client](https://lxzan.github.io/gws/reports/clients/)
+- [x] **事件驱动式 API**：基于 `Event` 接口，使用体验类似常见的 WebSocket SDK。
+- [x] **广播能力**：提供 `Broadcaster`，支持高效复用压缩结果进行大规模广播。
+- [x] **代理拨号**：支持自定义 `Dialer`，可与 SOCKS5 / HTTP 代理等一起使用。
+- [x] **上下文接管（permessage-deflate）**：支持按需配置上下文接管与滑动窗口大小。
+- [x] **大文件分段写入**：`WriteFile` 采用分段策略，减少大文件写入时的峰值内存。
+- [x] **并发与异步写入**：内置任务队列，支持异步写、多切片写 `Writev` / `WritevAsync`。
+- [x] **标准兼容性强**：通过所有 Autobahn 用例  
+  [Server 报告](https://lxzan.github.io/gws/reports/servers/) / [Client 报告](https://lxzan.github.io/gws/reports/clients/)
 
 ### 注意
 
-- 所有 gws.Conn 导出方法返回的错误都是可忽略的, 它们在内部已经被妥善处理了
-- 传输大文件有阻塞连接的风险
-- 如果复用 HTTP 服务器, 建议开启新的 Goroutine 来调用 ReadLoop, 以避免请求上下文内存不能及时回收.
+- 所有 `gws.Conn` 的导出方法返回的错误**在多数业务场景下可忽略**：库内部已经根据错误类型做了适当处理（例如关闭连接、上报事件等）。
+- 传输**超大文件**时，底层连接在传输过程中可能会长时间占用带宽与 IO，需结合业务做限流或切分。
+- 如果复用 `net/http` 服务器（例如 `http.HandleFunc` 中升级），强烈建议在 **新的 Goroutine** 中调用 `ReadLoop`，避免请求上下文无法及时 GC。
 
 ### 安装
 

types.go

@@ -114,14 +114,24 @@ type Event interface {
 
 type BuiltinEventHandler struct{}
 
+// OnOpen 默认连接建立事件回调
+// Default callback when a WebSocket connection is established
 func (b BuiltinEventHandler) OnOpen(socket *Conn) {}
 
+// OnClose 默认连接关闭事件回调
+// Default callback when a WebSocket connection is closed
 func (b BuiltinEventHandler) OnClose(socket *Conn, err error) {}
 
+// OnPing 默认心跳探测事件回调, 自动回复 Pong 帧
+// Default callback when a ping frame is received, automatically replies with a pong frame
 func (b BuiltinEventHandler) OnPing(socket *Conn, payload []byte) { _ = socket.WritePong(nil) }
 
+// OnPong 默认心跳响应事件回调
+// Default callback when a pong frame is received
 func (b BuiltinEventHandler) OnPong(socket *Conn, payload []byte) {}
 
+// OnMessage 默认消息事件回调
+// Default callback when a text/binary message is received
 func (b BuiltinEventHandler) OnMessage(socket *Conn, message *Message) {}
 
 type frameHeader [frameHeaderSize]byte