Gem for Pusher Channels 使用技术文档

1. 安装指南

支持平台

• Ruby：支持 Ruby 2.6 或更高版本。

安装方式

将 pusher 添加到您的 Gemfile 中，然后运行 bundle install：

gem 'pusher'

或者通过 gem 进行安装：

gem install pusher

在 Pusher 上注册后，使用安全凭证配置您的 Channels 应用。

实例化 Pusher Channels 客户端

创建一个新的 Pusher Channels client 可以按照以下方式进行。

require 'pusher'

pusher = Pusher::Client.new(
  app_id: '你的应用ID',
  key: '你的应用密钥',
  secret: '你的应用密钥',
  cluster: '你的应用集群',
  use_tls: true
)

cluster 值将设置 host 为 api-<cluster>.pusher.com。use_tls 值是可选的，默认为 true。它将设置 scheme 和 port。自定义 port 值优先于 use_tls。

如果你想要为你的客户端设置一个自定义 host 值，可以在实例化 Pusher Channels 客户端时进行：

require 'pusher'

pusher = Pusher::Client.new(
  app_id: '你的应用ID',
  key: '你的应用密钥',
  secret: '你的应用密钥',
  host: '你的应用host'
)

如果你同时传递 host 和 cluster 选项，host 将优先考虑，并且 cluster 将被忽略。

最后，如果你在 PUSHER_URL 环境变量中设置了配置，可以使用：

pusher = Pusher::Client.from_env

全局配置

库还可以在 Pusher 类上全局配置。

Pusher.app_id = '你的应用ID'
Pusher.key = '你的应用密钥'
Pusher.secret = '你的应用密钥'
Pusher.cluster = '你的应用集群'

如果存在 PUSHER_URL 环境变量，全局配置将自动设置为该变量的值。该值应采用 http://KEY:SECRET@HOST/apps/APP_ID 的形式。在 Heroku 上，这个环境变量已经设置好了。

如果你需要通过 HTTP 代理发送请求，可以配置：

Pusher.http_proxy = 'http://(用户):(密码)@(主机):(端口)'

默认情况下，API 请求通过 HTTPS 发送。如果将 use_tls 设置为 false，则可以使用 HTTP。

Pusher.use_tls = false

从版本 0.12 开始，在使用同步 HTTP 客户端时，SSL 证书会被验证。如果你出于任何原因需要禁用此行为，可以使用：

Pusher.default_client.sync_http_client.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE

2. 项目使用说明

请参考以下部分以了解如何使用 Pusher Channels Gem。

交互 Channels HTTP API

pusher gem 包含了与 API 进行交互的多个助手方法。通常，库遵循我们旨在使其普遍适用的一组约定。

处理错误

通过捕获 Pusher::Error（所有错误都是此错误的子类）来处理错误。

begin
  pusher.trigger('a_channel', 'an_event', :some => 'data')
rescue Pusher::Error => e
  # (Pusher::AuthenticationError, Pusher::HTTPError, 或 Pusher::Error)
end

日志

错误记录到 Pusher.logger。默认情况下，它使用标准库中的 Logger 以 info 级别记录到 STDOUT，但你可以指定任何记录器：

Pusher.logger = Rails.logger

发送事件

可以将事件发布到一个或多个通道（最多 10 个）的一次 API 调用中：

pusher.trigger('channel', 'event', foo: 'bar')
pusher.trigger(['channel_1', 'channel_2'], 'event_name', foo: 'bar')

可选的第四个参数可用于向 API 发送额外参数，例如用于 排除单个连接接收事件。

pusher.trigger('channel', 'event', {foo: 'bar'}, {socket_id: '123.456'})

批处理

还可以使用单个 API 调用发送多个事件（在多租户集群上每调用最多 10 个事件）：

pusher.trigger_batch([
  {channel: 'channel_1', name: 'event_name', data: { foo: 'bar' }},
  {channel: 'channel_1', name: 'event_name', data: { hello: 'world' }}
])

不推荐的发布者 API

大多数示例和文档将引用以下语法来触发事件：

Pusher['a_channel'].trigger('an_event', :some => 'data')

这将继续工作，但已被 pusher.trigger 替换，后者支持一个或多个通道。

获取关于您的 Pusher Channels 应用程序中的通道信息

此 gem 提供了用于从 Channels HTTP API 访问信息的方法。文档还展示了每个 API 端点的响应示例。

gem 提供了以下方法：

• pusher.channel_info('channel_name', {info:"user_count,subscription_count"}) 返回描述通道状态的哈希（文档）。

• pusher.channel_users('presence-channel_name') 返回订阅到通道的所有用户的列表（仅适用于存在通道）（文档）。

• pusher.channels({filter_by_prefix: 'presence-', info: 'user_count'}) 返回占用的通道哈希（可选地通过前缀过滤，例如 presence-），并可选地为此通道提供属性（文档）。

异步请求

使用 _async 方法的两个主要原因是：

• 在 web 应用程序中，响应从 Channels HTTP API 中不需要使用，但你希望避免在请求-响应周期中阻塞调用
• 你的应用程序在事件循环中运行，你需要避免阻塞反应器

异步调用通过使用事件循环（eventmachine，首选）或线程来支持。

以下方法可用（每个方法的调用接口与非异步版本匹配）：

• pusher.get_async
• pusher.post_async
• pusher.trigger_async

当然，还可以通过作业队列发送对 Channels HTTP API 的调用。如果你发送大量事件，建议使用这种方法。

使用 EventMachine

• 将 em-http-request gem 添加到 Gemfile（它不是 gem 依赖）。
• 运行 EventMachine 反应器（使用 EM.run 或在事件服务器如 Thin 中运行）。

_async 方法返回一个 EM::Deferrable，你可以绑定回调：

pusher.get_async("/channels").callback { |response|
  # 使用 reponse[:channels]
}.errback { |error|
  # 错误是一个 Pusher::Error 实例
}

HTTP 错误或 Channels 的错误响应将导致使用适当的错误对象调用 errback。

不使用 EventMachine

如果 EventMachine 反应器没有运行，异步请求将使用线程（由 httpclient gem 管理）。

立即返回一个 HTTPClient::Connection 对象，可以对其进行 查询 以发现请求的状态。完成请求时，通常不会进行响应检查和处理，坦白说，当你不关心响应时，这种方法最有用。

3. 项目 API 使用文档

请参考以下部分以了解如何使用 Pusher Channels Gem 的 API。

认证订阅请求

可以使用 gem 对私人或存在通道的订阅请求进行认证。authenticate 方法用于此目的，并返回一个 JSON 对象，该对象可以返回给发起请求的客户端。关于此认证方案的更多信息可以在 https://pusher.com/docs/channels/server_api/authenticating-users 的文档中找到。

私人通道

pusher.authenticate('private-my_channel', params[:socket_id])

存在通道

这些工作方式非常类似，但需要为被认证的用户提供一个唯一标识符，以及可选的用户信息，这些信息通过存在事件提供给客户端：

pusher.authenticate('presence-my_channel', params[:socket_id],
  user_id: '用户ID',
  user_info: {} # 可选
)

接收 WebHooks

可以创建一个 WebHook 对象来验证接收到的 WebHooks 是否符合您的应用凭据，并提取事件。它应该用 Rack::Request 对象（例如，在 Rails 控制器或 Sinatra 处理器中可用）创建。

webhook = pusher.webhook(request)
if webhook.valid?
  webhook.events.each do |event|
    case event["name"]
    when 'channel_occupied'
      puts "通道占用：#{event["channel"]}"
    when 'channel_vacated'
      puts "通道释放：#{event["channel"]}"
    end
  end
  render text: 'ok'
else
  render text: 'invalid', status: 401
end

端到端加密

此库支持 端到端加密通道。这意味着只有你和你的连接客户端能够读取你的消息。Pusher 无法解密它们。通过以下步骤可以启用此功能：

1. 将 rbnacl gem 添加到你的 Gemfile（它不是 gem 依赖）。

2. 安装 Libsodium，我们依赖它来进行繁重的工作。