Firehose 技术文档

Firehose 是一个基于 Ruby 和 JavaScript 的实时 Web 应用程序构建工具。它既是一个 Rack 应用程序，也是一个 JavaScript 库，能够帮助开发者轻松构建实时 Web 应用。本文将详细介绍 Firehose 的安装、使用、API 以及配置等内容。

1. 安装指南

1.1 安装 Redis

Firehose 依赖于 Redis 2.6 或更高版本，因为 Firehose 使用了 Redis 的 Lua/EVAL 功能。请确保已安装并运行 Redis 2.6。

# 下载并安装 Redis
$ wget http://download.redis.io/releases/redis-2.6.0.tar.gz
$ tar xzf redis-2.6.0.tar.gz
$ cd redis-2.6.0
$ make

1.2 安装 Firehose

通过 RubyGems 安装 Firehose：

$ gem install firehose

1.3 使用 Docker 安装

如果你更喜欢使用 Docker，可以通过以下命令构建并启动 Firehose：

$ docker-compose build
$ docker-compose up

2. 项目的使用说明

2.1 启动 Firehose 服务器

启动 Firehose 服务器非常简单，只需运行以下命令：

$ firehose server

服务器启动后，默认监听 127.0.0.1:7474。

2.2 发布和订阅消息

Firehose 提供了一个简单的 HTTP 发布-订阅机制。你可以通过 curl 命令来测试这一功能。

在一个终端窗口中订阅消息：

$ curl "http://localhost:7474/hello"

在另一个终端窗口中发布消息：

$ curl -X PUT -d "Greetings fellow human being..." "http://localhost:7474/hello"

你将在第一个终端窗口中看到发布的消息。

2.3 运行测试

Firehose 提供了测试套件，可以通过以下命令运行测试：

$ docker-compose run firehose bundle exec rspec spec

3. 项目 API 使用文档

3.1 JavaScript 消费者

Firehose 提供了一个功能齐全的 JavaScript 客户端，允许你订阅频道以获取实时更新。

以下是一个简单的 JavaScript 消费者示例：

new Firehose.Consumer({
  message: function(msg){
    console.log(msg);
  },
  connected: function(){
    console.log("Great Scotts!! We're connected!");
  },
  disconnected: function(){
    console.log("Well shucks, we're not connected anymore");
  },
  error: function(){
    console.log("Well then, something went horribly wrong.");
  },
  uri: '//localhost:7474/hello'
}).connect();

3.2 多路复用消费者

如果你需要同时订阅多个频道，可以使用多路复用消费者：

new Firehose.MultiplexedConsumer({
  connected: function(){
    console.log("Great Scotts!! We're connected!");
  },
  disconnected: function(){
    console.log("Well shucks, we're not connected anymore");
  },
  error: function(){
    console.log("Well then, something went horribly wrong.");
  },
  uri: '//localhost:7474/',
  channels: {
    "/my/channel/1": {
      message: function(msg) {
        console.log("got message on channel 1:");
        console.log(msg);
      }
    },
    "/my/channel/2": {
      message: function(msg) {
        console.log("got message on channel 2:");
        console.log(msg);
      }
    }
  }
}).connect();

3.3 Ruby 发布者

Firehose 还提供了一个 Ruby 客户端，用于轻松发布消息：

require 'firehose'
require 'json'
json = {'hello'=> 'world'}.to_json
firehose = Firehose::Client::Producer::Http.new('//127.0.0.1:7474')
firehose.publish(json).to("/my/messages/path")

你还可以通过传递选项来设置自定义 HTTP 头，例如 TTL、缓冲区大小等。

firehose.publish(json).to("/my/messages/path", ttl: 120, buffer_size: 1, deprecated: true, persist: true)

4. 项目配置

4.1 环境变量配置

Firehose 可以通过环境变量进行配置。参考 .env.sample 文件获取更多信息。

4.2 服务器配置

你可以通过 Firehose::Server.configuration 对象来配置 Firehose 服务器：

require "firehose"

class MyFilter < Firehose::Server::MessageFilter
  def process(message)
    message.payload = message.payload.upcase
  end
end

Firehose::Server.configuration do |config|
  config.message_filter = MyFilter
  config.redis.url = ENV.fetch "FIREHOSE_REDIS_URL", "redis://redis:6379/10"
end

4.3 自定义消息过滤器

你可以通过继承 Firehose::Server::MessageFilter 类来实现自定义的消息过滤器，用于处理消息的认证和过滤逻辑。

class MyFilter < Firehose::Server::MessageFilter
  def initialize(channel)
    super(channel)
    MyLogger.info "Subscribing to channel: #{channel}"
  end

  def on_subscribe(params)
    @my_param = params["my-param"].to_i
  end

  def process(message)
    if @my_param > 10
      message.payload += "My-Param: #{@my_param}"
    end
  end

  def on_unsubscribe
  end
end

4.4 频道弃用日志

你可以通过配置将某些频道标记为弃用，并在订阅或发布时记录日志：

Firehose::Server.configuration do |config|
  config.deprecated_channels = ["/my/deprecated/channel"]
end

总结

Firehose 是一个功能强大且易于使用的实时 Web 应用程序构建工具。通过本文的指南，你应该能够轻松安装、配置和使用 Firehose，并利用其丰富的 API 构建实时应用。