WebSocketServer(websocket 服务器)和WebSocket(websocket 对象)文档翻译
类：WebSocketServer
这个类表示一个 WebSocket 服务器。它继承自 EventEmitter 类。
构造函数：new WebSocketServer(options[, callback])
-
options {Object} - 配置选项：
backlog{Number} - 挂起连接队列的最大长度。当服务器忙于处理连接时，操作系统允许挂起（等待）的连接请求的最大数量。
clientTracking{Boolean} - 是否跟踪客户端。如果设置为 true，则
WebSocketServer.clients属性将包含所有连接到此服务器的客户端实例。handleProtocols{Function} - 处理 WebSocket 子协议的函数。当客户端请求带有子协议的握手时调用。接收一个字符串数组（表示可接受的子协议）和一个 HTTP 请求对象。应返回一个字符串（选择的子协议）或
false（拒绝请求）。host{String} - 绑定服务器的主机名。如果指定，服务器将仅在该主机上接受连接；否则接受所有传入连接。
maxPayload{Number} - 允许的最大消息大小（以字节为单位），默认值为 100 MiB（104857600 字节）。超过此限制的消息将被拒绝并关闭连接。
noServer{Boolean} - 启用无服务器模式。不创建 HTTP 或 HTTPS 服务器，而是直接绑定 WebSocket 连接到一个本地端口。
path{String} - 仅接受与此路径匹配的连接。如果未指定，服务器接受所有传入连接。
perMessageDeflate{Boolean|Object} - 启用/禁用 permessage-deflate。启用或禁用消息压缩扩展。如果为 true，使用默认选项；如果为对象，可配置
serverNoContextTakeover、clientNoContextTakeover等属性。port{Number} - 绑定服务器的端口。服务器将监听的端口号。
server{http.Server|https.Server} - 预先创建的 Node.js HTTP/S 服务器。使用现有服务器实例接收连接，忽略其他选项（如
host和port）。skipUTF8Validation{Boolean} - 是否跳过文本和关闭消息的 UTF-8 验证，默认值为false。提高性能，但降低安全性，仅在客户端可信时使用。
verifyClient{Function} - 验证传入连接的函数。每当有新的 WebSocket 连接请求时调用。建议在 HTTP 服务器的
'upgrade'事件中处理客户端身份验证。WebSocket{Function} - 指定要使用的 WebSocket 类。如果扩展了 WebSocket 类，可以通过此选项指定自定义类，否则使用默认的 WebSocket 类。
-
callback {Function} - 可选的回调函数，在服务器开始监听时调用。
创建一个新的 WebSocket 服务器实例。必须且只能提供 port、server 或 noServer 选项之一，否则将抛出错误。port 选项会自动创建并启动一个 HTTP 服务器。如果要使用外部 HTTP/S 服务器，请仅指定 server 或 noServer 选项。
注意： 不建议使用
verifyClient，应在 HTTP 服务器的'upgrade'事件中处理客户端身份验证。
事件：'close'
当服务器关闭时触发。如果 WebSocket 服务器内部创建了 HTTP 服务器，则依赖于 HTTP 服务器的 'close' 事件。在其他情况下，该事件独立触发。
事件：'connection'
- websocket {WebSocket} - 新的 WebSocket 连接。
- request {http.IncomingMessage} - 客户端的 HTTP GET 请求。
握手完成时触发。request 包含客户端的 HTTP GET 请求信息。
事件：'error'
- error {Error} - 发生的错误。
底层服务器发生错误时触发。
事件：'headers'
- headers {Array} - 响应头数组。
- request {http.IncomingMessage} - 客户端的 HTTP GET 请求。
在握手期间写入响应头之前触发，允许检查或修改头部信息。
事件：'listening'
底层服务器成功绑定时触发。
事件：'wsClientError'
- error {Error} - 发生的错误。
- socket {net.Socket|tls.Socket} - 发生错误的套接字。
- request {http.IncomingMessage} - 客户端的 HTTP 请求。
在建立 WebSocket 连接之前发生错误时触发。侦听器负责关闭套接字。
方法：server.address()
返回一个对象，包含服务器绑定的地址、地址族名称和端口信息。
属性：server.clients
- {Set} - 存储所有已连接客户端的集合。仅在
clientTracking为 true 时可用。
方法：server.close([callback])
停止服务器接受新连接并关闭 HTTP 服务器。如果使用外部 HTTP 服务器，则必须手动关闭它。现有连接不会自动关闭。所有连接关闭时触发 'close' 事件。
方法：server.handleUpgrade(request, socket, head, callback)
处理 HTTP 升级请求。在“noServer”模式下，必须手动调用此方法。
- request {http.IncomingMessage} - 客户端的 HTTP GET 请求。
- socket {net.Socket|tls.Socket} - 网络套接字。
- head {Buffer} - 升级流的第一个数据包。
- callback {Function} - 回调函数，接收 WebSocket 对象和请求。
方法：server.shouldHandle(request)
- request {http.IncomingMessage} - 客户端的 HTTP GET 请求。
类：WebSocket
这个类表示一个 WebSocket 对象，继承自 EventEmitter。
就绪状态常量
| 常量 | 值 | 描述 |
|---|---|---|
| CONNECTING | 0 | 连接尚未打开。 |
| OPEN | 1 | 连接已经打开，可以通信。 |
| CLOSING | 2 | 连接正在关闭中。 |
| CLOSED | 3 | 连接已经关闭。 |
构造函数：new WebSocket(address[, protocols][, options])
- address {String|url.URL} - 连接的 URL。
- protocols {String|Array} - 子协议列表。
- options {Object} - 配置选项：
finishRequest{Function} - 自定义每个 HTTP 请求发送前的头信息。followRedirects{Boolean} - 是否跟随重定向，默认值为false。generateMask{Function} - 生成掩码密钥的函数。handshakeTimeout{Number} - 握手请求的超时时间（毫秒）。maxPayload{Number} - 允许的最大消息大小（字节），默认值为 100 MiB。maxRedirects{Number} - 允许的最大重定向次数，默认值为 10。origin{String} -Origin或Sec-WebSocket-Origin头的值。perMessageDeflate{Boolean|Object} - 启用/禁用消息压缩。protocolVersion{Number} -Sec-WebSocket-Version头的值。skipUTF8Validation{Boolean} - 是否跳过 UTF-8 验证，默认值为false。- 其他允许在
http.request()或https.request()中使用的选项。
创建一个新的 WebSocket 实例。
事件：'close'
- code {Number} - 连接关闭的状态码。
- reason {Buffer} - 解释连接关闭原因的字符串。
事件：'error'
- error {Error} - 发生的错误。
事件：'message'
- data {Buffer|ArrayBuffer|Buffer[]} - 消息内容。
- isBinary {Boolean} - 是否为二进制数据。
事件：'open'
连接建立时触发。
事件：'ping'
- data {Buffer} - ping 消息内容。
事件：'pong'
- data {Buffer} - pong 消息内容。
事件：'redirect'
- url {String} - 重定向的 URL。
- request {http.ClientRequest} - HTTP GET 请求对象。
事件：'unexpected-response'
- request {http.ClientRequest} - HTTP 客户端请求对象。
- response {http.IncomingMessage} - HTTP 响应对象。
事件：'upgrade'
- response {http.IncomingMessage} - 服务器返回的 HTTP 响应头。
方法：websocket.addEventListener(type, listener[, options])
- type {String} - 事件类型。
- listener {Function|Object} - 事件监听器。
- options {Object} - 配置选项：
once{Boolean} - 是否只调用一次。
使用类似 EventTarget 接口的方式注册事件监听器。
属性：websocket.binaryType
- {String} - 连接传输的二进制数据类型，默认值为 "nodebuffer"。
属性：websocket.bufferedAmount
- {Number} - 已排队但尚未传输的数据字节数。
方法：websocket.close([code[, reason]])
- code {Number} - 关闭状态码。
- reason {String|Buffer} - 关闭原因。
发起一个关闭握手。
属性：websocket.isPaused
- {Boolean} - WebSocket 是否已暂停。
属性：websocket.extensions
- {Object} - 包含协商扩展的对象。
属性：websocket.onclose
- {Function} - 连接关闭时调用的事件监听器。
属性：websocket.onerror
- {Function} - 连接发生错误时调用的事件监听器。
属性：websocket.onmessage
- {Function} - 接收到消息时调用的事件监听器。
属性：websocket.onopen
- {Function} - 连接建立时调用的事件监听器。
方法：websocket.pause()
暂停 WebSocket 连接。
方法：websocket.ping([data[, mask]])
- data {Array|Number|Object|String|ArrayBuffer|Buffer|DataView|TypedArray} - ping 消息内容。
- mask {Boolean} - 是否掩码处理数据。
- callback {Function} - 可选的回调函数。
发送一个 ping 消息。
方法：websocket.pong([data[, mask]])
- data {Array|Number|Object|String|ArrayBuffer|Buffer|DataView|TypedArray} - pong 消息内容。
- mask {Boolean} - 是否掩码处理数据。
- callback {Function} - 可选的回调函数。
发送一个 pong 消息。
属性：websocket.protocol
- {String} - 服务器选择的子协议。
方法：websocket.resume()
恢复暂停的 WebSocket 连接。
属性：websocket.readyState
- {Number} - 当前连接状态。
方法：websocket.removeEventListener(type, listener)
- type {String} - 要移除的事件类型。
- listener {Function|Object} - 要移除的监听器。
移除注册的事件监听器。
方法：websocket.send(data[, options])
- data {Array|Number|Object|String|ArrayBuffer|Buffer|DataView|TypedArray} - 要发送的数据。
- options {Object} - 配置选项：
binary{Boolean} - 是否作为二进制数据发送。compress{Boolean} - 是否压缩数据。fin{Boolean} - 是否为消息的最后一个片段。mask{Boolean} - 是否掩码处理数据。
- callback {Function} - 可选的回调函数。
通过 WebSocket 连接发送数据。
方法：websocket.terminate()
强制关闭连接。
属性：websocket.url
- {String} - WebSocket 服务器的 URL。
函数：createWebSocketStream(websocket[, options])
- websocket {WebSocket} - 一个 WebSocket 对象。
- options {Object} - 传递给
Duplex构造函数的选项。
返回一个 Duplex 流，允许在给定的 WebSocket 上使用 Node.js 流 API。
环境变量
WS_NO_BUFFER_UTIL
设置为非空值时，防止需要可选的 bufferutil 依赖项。
WS_NO_UTF_8_VALIDATE
设置为非空值时，防止需要可选的 utf-8-validate 依赖项。
错误代码
WebSocket 发出的错误可能具有 .code 属性，描述特定类型的错误：
WS_ERR_EXPECTED_FIN
预期应设置 WebSocket 帧的 FIN 位，但未设置。
WS_ERR_EXPECTED_MASK
WebSocket 服务器接收到未经掩码处理的 WebSocket 帧。
WS_ERR_INVALID_CLOSE_CODE
收到带有无效关闭代码的 WebSocket 关闭帧。
WS_ERR_INVALID_CONTROL_PAYLOAD_LENGTH
接收到带有无效负载长度的控制帧。
WS_ERR_INVALID_OPCODE
接收到带有无效操作码的 WebSocket 帧。
WS_ERR_INVALID_UTF8
收到包含无效 UTF-8 数据的文本或关闭帧。
WS_ERR_UNEXPECTED_MASK
WebSocket 客户端接收到经过掩码处理的 WebSocket 帧。
WS_ERR_UNEXPECTED_RSV_1
接收到带有意外设置的 RSV1 位的 WebSocket 帧。
WS_ERR_UNEXPECTED_RSV_2_3
接收到带有意外设置的 RSV2 或 RSV3 位的 WebSocket 帧。
WS_ERR_UNSUPPORTED_DATA_PAYLOAD_LENGTH
接收到的数据帧长度超过最大支持长度（2^53 - 1，由于 JavaScript 语言限制）。
WS_ERR_UNSUPPORTED_MESSAGE_LENGTH
接收到的消息长度超过 maxPayload 配置的最大支持长度。
