faye-websocket 技术文档

本文档旨在帮助用户了解和使用 faye-websocket 项目。faye-websocket 是一个通用的 WebSocket 实现，提取自 Faye 项目。它提供了用于在 Ruby 中轻松构建 WebSocket 服务器和客户端的类。本文档将涵盖以下内容：

1. 安装指南
2. 项目的使用说明
3. 项目 API 使用文档
4. 项目安装方式

1. 安装指南

要安装 faye-websocket，可以使用以下命令：

$ gem install faye-websocket

2. 项目的使用说明

2.1 在 Rack 中处理 WebSocket 连接

在服务器端，您可以通过监听请求并使用 Faye::WebSocket.websocket? 方法来处理 WebSocket 连接。然后，您可以为请求创建一个新的 WebSocket 对象。该对象暴露了用于接收和发送消息的常用 WebSocket 方法。以下是一个简单的回显服务器示例：

# app.rb
require 'faye/websocket'

App = lambda do |env|
  if Faye::WebSocket.websocket?(env)
    ws = Faye::WebSocket.new(env)

    ws.on :message do |event|
      ws.send(event.data)
    end

    ws.on :close do |event|
      p [:close, event.code, event.reason]
      ws = nil
    end

    # 返回异步 Rack 响应
    ws.rack_response

  else
    # 普通 HTTP 请求
    [200, { 'Content-Type' => 'text/plain' }, ['Hello']]
  end
end

2.2 使用 WebSocket 客户端

faye-websocket 提供了 WebSocket 客户端，支持 ws 和 wss 协议。以下是一个简单的客户端示例：

require 'faye/websocket'
require 'eventmachine'

EM.run {
  ws = Faye::WebSocket::Client.new('ws://www.example.com/')

  ws.on :open do |event|
    p [:open]
    ws.send('Hello, world!')
  end

  ws.on :message do |event|
    p [:message, event.data]
  end

  ws.on :close do |event|
    p [:close, event.code, event.reason]
    ws = nil
  end
}

2.3 子协议协商

WebSocket 协议允许客户端和服务器选择并标识连接上使用的应用协议。在客户端，您可以在构造 WebSocket 对象时传递接受的协议列表：

ws = Faye::WebSocket::Client.new('ws://www.example.com/', ['irc', 'amqp'])

在服务器端，您也可以在构造 WebSocket 对象时传递支持的协议列表：

ws = Faye::WebSocket.new(env, ['irc', 'amqp'])

2.4 协议扩展

faye-websocket 支持通过 Sec-WebSocket-Extensions 头协商扩展。要添加扩展，可以在初始化时传递扩展数组：

require 'permessage_deflate'

ws = Faye::WebSocket.new(env, [], :extensions => [PermessageDeflate])

3. 项目 API 使用文档

3.1 WebSocket API

WebSocket 对象支持以下 API：

• on(:open) { |event| }：当连接建立时触发。
• on(:message) { |event| }：当接收到消息时触发。event.data 可以是字符串（文本帧）或字节数组（二进制帧）。
• on(:error) { |event| }：当协议错误时触发。
• on(:close) { |event| }：当连接关闭时触发。event.code 和 event.reason 分别表示状态码和原因。
• send(message)：发送消息，可以是字符串或字节数组。
• ping(message, &callback)：发送 ping 帧，并在接收到 pong 时触发回调。
• close(code, reason)：关闭连接，可选状态码和原因。
• version：连接使用的 WebSocket 协议版本。
• protocol：连接使用的子协议。

3.2 EventSource API

EventSource 对象支持以下 API：

• on(:open) { |event| }：当连接建立时触发。
• on(:close) { |event| }：当连接关闭时触发。
• send(message)：向客户端发送消息。

4. 项目安装方式

faye-websocket 可以通过 RubyGems 安装：

$ gem install faye-websocket

安装完成后，您可以在 Ruby 项目中引入并使用 faye-websocket。

---

本文档详细介绍了 faye-websocket 的安装、使用和 API，帮助用户快速上手并深入了解该项目。