Private Pub 技术文档

Private Pub 是一个用于 Rails 的 Ruby gem，它通过 Faye 实现消息的发布和订阅。它允许你通过开放的套接字轻松提供实时更新，而不会占用 Rails 进程。所有频道都是私有的，因此用户只能收听你订阅的事件。

1. 安装指南

1.1 添加 Gem

首先，将 private_pub gem 添加到你的 Gemfile 中，并运行 bundle 命令来安装它。你可能还需要添加 thin gem 来服务 Faye。

gem "private_pub"
gem "thin"

1.2 生成初始文件

运行生成器以创建初始文件。

rails g private_pub:install

1.3 启动 Faye

使用生成的 rackup 文件启动 Faye。

rackup private_pub.ru -s thin -E production

1.4 添加 JavaScript 文件

在 Rails 3.1 中，将 JavaScript 文件添加到你的 application.js 文件清单中。

//= require private_pub

在 Rails 3.0 中，将生成的 private_pub.js 文件添加到你的布局中。

<%= javascript_include_tag "private_pub" %>

不需要手动包含 faye.js，因为它会自动处理。

2. 使用说明

2.1 订阅频道

使用 subscribe_to 辅助方法在任何页面上订阅频道。

<%= subscribe_to "/messages/new" %>

2.2 发布消息

使用 publish_to 辅助方法向该频道发送 JavaScript。这通常在 JavaScript AJAX 模板（如 create.js.erb 文件）中完成。

<% publish_to "/messages/new" do %>
  $("#chat").append("<%= j render(@messages) %>");
<% end %>

此 JavaScript 将立即在所有订阅该频道的客户端上执行。在这个例子中，他们将看到新的聊天消息实时显示，而无需刷新浏览器。

2.3 使用 JSON 发布消息

如果你更喜欢通过 JSON 而不是 .js.erb 模板工作，你可以将哈希传递给 publish_to，而不是块，它将在后台转换为 to_json。这可以在任何地方完成（例如控制器中）。

PrivatePub.publish_to "/messages/new", :chat_message => "Hello, world!"

然后在客户端通过 JavaScript 处理。

PrivatePub.subscribe("/messages/new", function(data, channel) {
  $("#chat").append(data.chat_message);
});

仍然需要使用 Ruby 的 subscribe_to 辅助方法来授予用户访问频道的权限。JavaScript 只是用于任何自定义行为的回调。

3. 项目 API 使用文档

3.1 subscribe_to 方法

subscribe_to 方法用于订阅指定的频道。它会在页面上生成一个脚本，将用户订阅到特定的频道和服务器。

<%= subscribe_to "/messages/new" %>

3.2 publish_to 方法

publish_to 方法用于向指定的频道发布消息。它可以接受一个块或一个哈希。

<% publish_to "/messages/new" do %>
  $("#chat").append("<%= j render(@messages) %>");
<% end %>

或

PrivatePub.publish_to "/messages/new", :chat_message => "Hello, world!"

3.3 PrivatePub.subscribe 方法

在客户端，你可以使用 PrivatePub.subscribe 方法来订阅频道并处理接收到的数据。

PrivatePub.subscribe("/messages/new", function(data, channel) {
  $("#chat").append(data.chat_message);
});

4. 项目安装方式

4.1 通过 Gemfile 安装

将 private_pub gem 添加到你的 Gemfile 中，并运行 bundle install 命令来安装它。

gem "private_pub"

4.2 通过命令行安装

你也可以通过命令行直接安装 private_pub gem。

gem install private_pub

4.3 配置 Faye

在 config/private_pub.yml 文件中为每个环境设置配置。以下是可用的选项：

• server: Faye 服务器的 URL，例如 http://localhost:9292/faye。
• secret_token: 用于保护服务器的秘密哈希。可以是任何字符串。
• signature_expiration: 订阅签名过期的时间长度（以秒为单位）。如果未设置，则不会过期。注意：如果 Faye 与 Rails 应用程序位于不同的服务器上，则系统时钟必须同步才能使过期正常工作。

4.4 通过 HTTPS 服务 Faye

要通过 HTTPS 服务 Faye，你可以创建一个类似于以下的 Thin 配置文件 config/private_pub_thin.yml：

---
port: 4443
ssl: true
ssl_key_file: /path/to/server.pem
ssl_cert_file: /path/to/certificate_chain.pem
environment: production
rackup: private_pub.ru

certificate_chain.pem 文件应包含你的签名证书，后跟中间证书（如果有）和签署密钥的 CA 的根证书。

接下来，在 config/private_pub.yml 中重新配置 URL，使其类似于 https://your.hostname.com:4443/faye。

最后，从项目根目录启动 Thin。

thin -C config/private_pub_thin.yml start

项目状态

目前，该项目已不再维护。如果你发现关键问题，请通过 Twitter 联系作者。

开发与反馈

如有问题或意见，请使用 issue tracker。可以通过 bundle 和 rake 命令运行测试。