faye-rails 技术文档

1. 安装指南

1.1 安装依赖

在安装 faye-rails 之前，确保你已经安装了以下依赖：

• Ruby 2.0 或更高版本
• Rails 4.0 或更高版本
• Thin 服务器（因为 Faye 只能在 Thin 上运行）

1.2 安装 faye-rails

在你的 Rails 项目的 Gemfile 中添加以下内容：

gem 'faye-rails'

然后运行 bundle install 来安装 gem。

2. 项目的使用说明

2.1 嵌入 Faye 服务器

faye-rails 允许你将 Faye 的 Rack 服务器嵌入到 Rails 中间件栈中。你可以在 config/application.rb 文件中进行配置：

config.middleware.use FayeRails::Middleware, mount: '/faye', timeout: 25

你还可以通过传递一个块来调用 Faye::RackAdapter 的方法：

config.middleware.use FayeRails::Middleware, mount: '/faye', timeout: 25 do
  class MockExtension
    def incoming(message, callback)
      callback.call(message)
    end
  end

  add_extension(MockExtension.new)
end

2.2 路由配置

你可以使用 map 方法进行简单的路由配置：

config.middleware.use FayeRails::Middleware, mount: '/faye', timeout: 25 do
  map '/widgets/**' => WidgetsController  
  map :default => :block
end

3. 项目 API 使用文档

3.1 控制器

faye-rails 提供了一个控制器来处理模型事件与通道之间的绑定，并提供了 DSL 来管理基于通道的事件。

class WidgetController < FayeRails::Controller
end

3.2 模型观察者

你可以使用控制器的观察者 DSL 订阅模型的变化：

class WidgetController < FayeRails::Controller
  observe Widget, :after_create do |new_widget|
    WidgetController.publish('/widgets', new_widget.attributes)
  end
end

3.3 通道 DSL

控制器 DSL 优雅地封装了 Faye API 的通道相关部分，使你可以轻松地基于特定通道分组代码。

3.3.1 监控

你可以使用 Faye 的监控 API 来监控 :subscribe、:unsubscribe 和 :publish 事件：

class WidgetController < FayeRails::Controller
  channel '/widgets' do
    monitor :subscribe do
      puts "Client #{client_id} subscribed to #{channel}."
    end
    monitor :unsubscribe do
      puts "Client #{client_id} unsubscribed from #{channel}."
    end
    monitor :publish do
      puts "Client #{client_id} published #{data.inspect} to #{channel}."
    end
  end
end

3.3.2 过滤

你可以使用控制器的过滤 API 来快速过滤进入或离开服务器的消息：

class WidgetController < FayeRails::Controller
  channel '/widgets' do
    filter :in do
      puts "Inbound message #{message}."
      pass
    end
  end
end

3.3.3 订阅

你可以使用 subscribe 方法轻松订阅通道：

class WidgetController < FayeRails::Controller
  channel '/widgets' do
    subscribe do
      puts "Received on channel #{channel}: #{message.inspect}"
    end
  end
end

4. 项目安装方式

4.1 在非服务器环境中运行

如果你在没有服务器运行的环境中运行 Rails（例如后台任务处理或控制台），你需要确保 EventMachine 反应堆正在运行。你可以在 config/initializers 中创建一个初始化文件，调用 Faye.ensure_reactor_running!。

Faye.ensure_reactor_running!

4.2 在 Phusion Passenger 上运行

如果你想在 Phusion Passenger 上运行 faye-rails，请确保你使用的是 Passenger 4.0 独立版或 Passenger 4.0 在 nginx 1.4+ 上运行，并支持 WebSocket。Passenger 在 Apache 上不受支持。由于 Passenger 使用多进程模型，你必须使用 Faye 的 Redis 后端。在 Gemfile 中添加 gem 'faye-redis' 并配置路由：

config.middleware.use FayeRails::Middleware, mount: '/faye', timeout: 25, server: 'passenger', engine: {type: Faye::Redis, host: 'localhost'}

通过以上步骤，你可以成功安装、配置并使用 faye-rails 来管理你的实时通信需求。