Firehose - 构建实时Ruby web应用程序

Firehose - 构建实时Ruby web应用程序

__ _ _ / _(_) | || |_ _ _ __ ___| |__ ___ ___ ___| _| | '__/ _ \ '_ \ / _ \/ __|/ _ \| | | | | | __/ | | | (_) \__ \ __/|_| |_|_| \___|_| |_|\___/|___/\___|Build realtime web applications in Ruby and js

What is Firehose?

Firehose is both a Rack application and JavaScript library that makes building real-time web applications possible.

Getting Started

First, you'll need to install and run Redis 2.6. Version 2.6 is required because Firehose uses Lua/EVAL for its transactions, which is not available in earlier versions of Redis.

Then install the gem.

$ gem install firehose

The Server

Now fire up the server.

$ firehose server>> Thin web server (v1.3.1 codename Triple Espresso)>> Maximum connections set to 1024>> Listening on 127.0.0.1:7474, CTRL+C to stop

In case you're wondering, the Firehose application server runs the Rack app Firehose::Rack::App.new inside of Thin or Rainbows! Firehose::Rack::App consists of a bunch of smaller apps and a middleware, which is useful for hacking.

Publish a message to a bunch of subscribers

Lets test it out! Open two terminal windows. In one window, curl:

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

Then run the following in the other terminal:

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

and you should see the message in the other terminal.

Greetings fellow human being...

Yeah, so?

You have a dirt simple HTTP pub-sub feed. You could setup an after_commit hook on ActiveRecord to push JSON to an end-point. On the other side, you could have a Backbone.js application that picks up the changes and updates the client-side UI.

Holy mackerel! Its a nice, clean, RESTful way to build real-time web applications.

The JavaScript Consumer

Firehose doesn't just stop at curl; it has a full-featured JavaScript client that lets you subscribe to channels for live updates.

Still have the server running? Copy and paste the code below into Firebug or the WebKit console.

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."); }, // Note that we do NOT specify a protocol here because we don't // know that yet. uri: '//localhost:7474/hello'}).connect();

There's also a Consumer that uses channel multiplexing. The multiplexed consumer is useful for scenarios where you want to subscribe to messages from many channels at once, without having to use one connection per channel. You can specify a list of channels to subscribe to, including a handler function per channel that gets called with all messages coming from that channel.

Example:

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."); }, // Note that we don't specify a general message handler function // but instead define one per channel below // Note that we do NOT specify a protocol here because we don't // know that yet. We also don't specify a specific channel name as part of // the URI but instead pass in a list of subscriptions below uri: '//localhost:7474/', // List of channel subscriptions: channels: { "/my/channel/1": { last_sequence: 10, // defaults to 0 and can be ommitted 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();

Then publish another message.

$ curl -X PUT -d "\"This is almost magical\"" "http://localhost:7474/hello"

How is it different from socket.io?

socket.io attempts to store connection state per node instance. Firehose makes no attempt to store connection state.

Also, socket.io attempts to abstract a low-latency full-duplex port. Firehose assumes that its impossible to simulate this in older web browsers that don't support WebSockets. As such, Firehose focuses on low-latency server-to-client connections and encourages the use of existing HTTP transports, like POST and PUT, for client-to-server communications.

The Ruby Publisher

While you can certainly make your own PUT requests when publishing messages, Firehose includes a Ruby client for easy publishing.

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

Publishing Options

You can pass additional options to the publisher that set specific custom configuration http headers. The options available are:

TTL (how long should the message be buffered for)Buffer size (how many messages for the channel should be kept in the buffer)Deprecated (if marked as deprecated, any publications or subscriptions to the channel will be logged with a deprecation warning)Persist (persisting causes the channel & message to not be expired after a given or the default TTL)

The corresponding HTTP headers and allowed values are:

Cache-Control: intX-Firehose-Buffer-Size: intX-Firehose-Deprecated: true | falseX-Firehose-Persist: true | false

firehose = Firehose::Client::Producer::Http.new('//127.0.0.1:7474')# mark channel as deprecatedfirehose.publish(json).to("/my/messages/path", deprecated: true)# expire after 120 secondsfirehose.publish(json).to("/my/messages/path", ttl: 120)# only keep last itemfirehose.publish(json).to("/my/messages/path", buffer_size: 1)# persist channel & message forever (or until a new message for this channel declares a new TTL and persist != true)firehose.publish(json).to("/my/messages/path", persist: true)

These options can be of course be combined within a single request.

Configuration

Firehose can be configured via environmental variables. Take a look at the .env.sample file for more info.

Server Configuration

The Firehose server may be configured via the Firehose::Server.configuration object as follows:

require "firehose"# Implement a custom message handler.class MyFilter < Firehose::Server::MessageFilter def process(message) # SHOUT AT ALL THE SUBSCRIBERS! name = params["name"] message.payload = "HEY #{name}!, #{message.payload.upcase}!" endendFirehose::Server.configuration do |config| # Custom message filter. This is useful if you want to implement # authorization per-message for Firehose. config.message_filter = MyFilter # Configure redis connection. config.redis.url = ENV.fetch "FIREHOSE_REDIS_URL", "redis://redis:6379/10"end

Custom MessageFilters

As mentioned above you can define custom MessageFilters which allow you to add custom logic for things like authentication & filtering of content. By default, the Firehose::Server::MessageFilter base class is used, which does nothing to the messages being published. You can override the following methods in your own implementations:

class MyFilter < Firehose::Server::MessageFilter # Optional override if you need to do any other setup operation. # Make sure to call super(channel). # - channel: name of the channel (String) def initialize(channel) super(channel) MyLogger.info "Subscribing to channel: #{channel}" end # Optional, called once before process(). # - params: Hash of params of the subscription message the client sent def on_subscribe(params) @my_param = params["my-param"].to_i # You can also optionally raise an instance of # Firehose::Server::ChannelSubscription::Failed # this will cause the client to receive an error message of the form: # { error: "Subscription failed", reason: error_reason } # and the client will call its `subscriptionFailed` callback (if configured) end # Custom logic for a message to be published to client. # - message: Firehose::Server::Message instance def process(message) if @my_param > 10 message.payload += "My-Param: #{@my_param}" end end # optional cleanup logic def on_unsubscribe endend

Deprecation logging for channels

Client publishing option

You can mark a message as deprecated (to be logged by Firehose) by passing deprecated: true as an option to Firehose::Client::Producer::HTTP#put.

firehose = Firehose::Client::Producer::Http.new('//127.0.0.1:7474')firehose.publish("{'hello': 'world'}").to("/my/messages/path", deprecated: true)

Server side config

You can specify a list of channels that are marked as deprecated and will cause subscription and publish events on any of those channels to be logged with a special deprecation message.

Example config:

Firehose::Server.configuration do |config| # set a static list of deprecated channels: config.deprecated_channels = ["/foo/bar.json", "/foo/bar/baz.json"] # provide a block to determine if a channel is deprecated via custom logic: config.deprecated_channel do |channel| channel =~ /^\/foo\/*\.json$/ endend

Rack Configuration

There are two rack applications that are included with Firehose: Firehose::Rack::Producer which a client can PUT HTTP request with message payloads to publish information on Firehose and the Firehose::Rack::Consumer application which a client connects to via HTTP long polling or WebSockets to consume a message.

Consumer Configuration

# Kitchen-sink rack configuration file examplerequire 'firehose'consumer = Firehose::Rack::Consumer.new do |app| # Configure how long the server should wait before send the client a 204 # with a request to reconnect. Typically browsers time-out the client connection # after 30 seconds, so we set the `Firehose.Consumer` JS client to 25, and the # server to 20 to make sure latency or timing doesn't cause any problems. app.http_long_poll.timeout = 20endrun consumer

Publisher Configuration

# Kitchen-sink rack configuration file examplerequire 'firehose'# There's nothing to configure with the Publisher, but its possible that# you might include rack middleware authorization mechanisms here to control# who can publish to Firehose.run Firehose::Rack::Publisher.new

Sprockets

Using Sprockets is the recommended method of including the included client-side assets in a web page.

Add the firehose gem in your app's Gemfile. Append the firehose gem's assets to the sprockets path. In a Rails app, this is usually done in an initializer.

# Add firehose to a custom sprockets configuration.my_sprockets_env = Sprockets::Environment.newFirehose::Assets::Sprockets.configure my_sprockets_env

Require your config file and the firehose gem. This would look something like this:

#= require some/other/js/file#= require lib/firehose_config#= require firehose#= require some/more/js/files

It is important that your firehose config file comes first.

Not using sprockets?

If you don't intend to use the Firehose JavaScript client in a Ruby stack where Sprockets is available, you can grab the unminified source by running:

$ firehose javascript > firehose.js

Copy the firehose.js where needed in your project.

Web Server

Firehose currently supports Thin and Rainbows! (which is the default). Neither is listed as a dependency in the gemspec so that you don't need to install whichever one you aren't using. You can set which server to use via the .env file (recommended) or with the -s option to bin/firehose.

Exception Notification

If you'd like to be notified of exceptions, add something like this in your custom config.ru file.

# Use exceptional to handle anything missed by Rack::Exceptionalif exceptional_key = ENV['EXCEPTIONAL_KEY'] require 'exceptional' EM.error_handler do |e| Firehose.logger.error "Unhandled exception: #{e.class} #{e.message}\n#{e.backtrace.join "\n"}" ::Exceptional.handle(e) endend

Deployment

The recommended method of deploying Firehose is to deploy it separately from your main app.

Create a new project with a Gemfile such as

gem "firehose"gem "airbrake"gem "rainbows", :require => falsegem "rack", "~> 1.4.0" # if you're using Rainbows. See https://github.com/firehoseio/firehose/commit/dfe55fffgem "foreman", :require => falsegem "capistrano", :require => false

Of course, you could use exceptional instead of airbrake and thin instead of rainbows.

Set up config/deploy.rb to your liking. You can follow most directions for using Capistrano and Foreman to deploy Rack apps, such as https://gist.github.com/1027117 Set up config/rainbows.rb (if you are using Rainbows!). The gem includes example configurations scripts to get you started. There's also an example at https://gist.github.com/bradgessler/f2416efdbb1771e983b3.

New releases & version bump

For a new release of Firehose, bump the version number in lib/firehose/version.rb as well as package.json. Make sure, they have the same version number.

Support

Ruby version

Firehose will support the latest minor 2.x revisions of Ruby that are officially supported by the Ruby community. More details at https://ruby-lang.org/.

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。