redisse 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5799fb06db34c512846d7e6d11fd403c7bc2b8a7
+  data.tar.gz: 798680edb40005c798ab67fc4d13dc1d690209ab
+SHA512:
+  metadata.gz: 61edfb6b8f496dfe5497d565dc0e6a7de62d9d1a104e827f589c364188c70126f0a521d597667802a183c3be4e33df1c8387a73ef6dcd9935ed31b7c7e619f87
+  data.tar.gz: 2014e85400758f2a0a1b0eb149668ad36b5b20b95dc18a32822c30f307aede8a879075f4de88ff626fa1efc76255c0056a130d413f09710e2e7d68be63036757

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+/example/nginx.log
+/example/nginx.pid

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--order rand

data/.ruby-version

@@ -0,0 +1 @@
+2.1.2

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.1.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in redisse.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Tigerlily
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# Redisse
+
+Redisse is a Redis-backed Ruby library for creating [Server-Sent
+Events](http://www.w3.org/TR/eventsource/), publishing them from your
+application, and serving them to your clients.
+
+* **Homepage:**
+  [github.com/tigerlily/redisse](https://github.com/tigerlily/redisse)
+* **Documentation:**
+  [tigerlily.github.io/redisse](https://tigerlily.github.io/redisse/)
+
+## Features
+
+* Pub/Sub split into **channels** for privacy & access rights handling.
+
+* **SSE history** via the `Last-Event-Id` header and the `lastEventId` query
+  parameter, with a limit of 100 events per channel.
+
+* **Long-polling** via the `polling` query parameter. Allows to send several
+  events at once for long-polling clients by waiting one second before closing
+  the connection.
+
+* **Lightweight**: only one Redis connection for history and one for all
+  subscriptions, no matter the number of connected clients.
+
+* **`missedevents` event fired** when the full requested history could not be
+  found, to allow the client to handle the case where events were missed.
+
+* **Event types** from SSE are left untouched for your application code, but
+  keep in mind that a client will receive events of all types from their
+  channels. To handle access rights, use channels instead.
+
+## Rationale
+
+Redisse’s design comes from these requirements:
+
+* The client wants to listen to several channels but use only one connection.
+  (e.g. a single `EventSource` object is created in the browser but you want
+  events coming from different Redis channels.)
+
+* A server handles the concurrent connections so that the application servers
+  don't need to (e.g. Unicorn workers).
+
+* The application is written in Ruby, so there needs to be a Ruby API to
+  publish events.
+
+* The application is written on top of Rack, so the code that lists the Redis
+  Pub/Sub channels to subscribe to needs to be able to use Rack middlewares and
+  should receive a Rack environment. (e.g. you can use
+  [Warden](https://github.com/hassox/warden) as a middleware and simply use
+  `env['warden'].user` to decide which channels the user can access.)
+
+### Redirect endpoint
+
+The simplest way that last point can be fulfilled is by actually loading and
+running your code in the Redisse server. Unfortunately since it’s
+EventMachine-based, if your method takes a while to returns the channels, all
+the other connected clients will be blocked too. You'll also have some
+duplication between your [Rack config](https://github.com/tigerlily/redisse/blob/9052630e57081714365188a8f55f0549aee03d56/example/config.ru#L30)
+and [Redisse server config](https://github.com/tigerlily/redisse/blob/9052630e57081714365188a8f55f0549aee03d56/example/lib/sse_server.rb#L15).
+
+Another way if you use nginx is instead to use a endpoint in your main
+application that will use the header X-Accel-Redirect to redirect to the
+Redisse server, which is now free from your blocking code. The channels will be
+sent instead via the redirect URL. See the [section on nginx](#behind-nginx)
+for more info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'redisse', '~> 0.4.0'
+
+## Usage
+
+Configure Redisse (e.g. in `config/initializers/redisse.rb`):
+
+    require 'redisse'
+
+    Redisse.channels do |env|
+      %w[ global ]
+    end
+
+Use the endpoint in your main application (in config.ru or your router):
+
+    # config.ru Rack
+    map "/events" do
+      run Redisse.redirect_endpoint
+    end
+
+    # config/routes.rb Rails
+    get "/events" => Redisse.redirect_endpoint
+
+Run the server:
+
+    $ redisse --stdout --verbose
+
+Get ready to receive events:
+
+    $ curl localhost:8080 -H 'Accept: text/event-stream'
+
+Send a Server-Sent Event:
+
+    Redisse.publish('global', success: "It's working!")
+
+### Testing
+
+In the traditional Rack app specs or tests, use `Redisse.test_mode!`:
+
+    describe "SSE" do
+      before do
+        Redisse.test_mode!
+      end
+
+      it "should send a Server-Sent Event" do
+        post '/publish', channel: 'global', message: 'Hello'
+        expect(Redisse.published.size).to be == 1
+      end
+    end
+
+See [the example app
+specs](https://github.com/tigerlily/redisse/blob/master/example/spec/app_spec.rb).
+
+### Behind nginx
+
+When running behind nginx as a reverse proxy, you should disable buffering
+(`proxy_buffering off`) and close the connection to the server when the client
+disconnects (`proxy_ignore_client_abort on`) to preserve resources (otherwise
+connections to Redis will be kept alive longer than necessary).
+
+You should take advantage of the [redirect endpoint](#redirect-endpoint)
+instead of directing the SSE requests to the SSE server. Let your Rack
+application determine the channels, but have the request served by the SSE
+server with a redirect (X-Accel-Redirect) to an internal location.
+
+In this case, and if you have a large number of long-named channels, the
+internal redirect URL will be long and you might need to increase
+`proxy_buffer_size` from its default in your Rack application location
+configuration. For example, 8k will allow you about 200 channels with UUIDs as
+names, which is quite a lot.
+
+You can check the [nginx conf of the
+example](https://github.com/tigerlily/redisse/blob/master/example/nginx.conf)
+for all the details.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,28 @@
+require "bundler/gem_tasks"
+
+begin
+  require 'yard'
+  YARD::Config.load_plugin 'tomdoc'
+  YARD::Rake::YardocTask.new do |t|
+    t.name = :doc
+  end
+
+  task :gh_pages => :doc do
+    sh 'git checkout gh-pages'
+    sh 'rsync -a doc/* .'
+    sh 'git add .'
+    version = "v#{Bundler::GemHelper.gemspec.version}"
+    sh "git commit -m 'Documentation for #{version}'"
+    sh 'git checkout -'
+  end
+rescue LoadError
+end
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec) do |task|
+    task.pattern = "{example/,}" + task.pattern
+  end
+  task :default => :spec
+rescue LoadError
+end

data/bin/redisse

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require 'redisse/server'
+Redisse.run

data/example/.env

@@ -0,0 +1,3 @@
+REDIS_PORT=6380
+REDISSE_REDIS=redis://localhost:$REDIS_PORT/
+REDISSE_PORT=8082

data/example/README.md

@@ -0,0 +1,37 @@
+# Redisse example: Rack app
+
+Get the dependencies:
+
+    $ bundle
+
+Note that the example uses [dotenv](https://github.com/bkeepers/dotenv):
+
+    $ cat .env
+
+Change .env to point to a running Redis server, or simply run the dedicated
+Redis server:
+
+    $ bin/redis
+
+Run the Rack application server:
+
+    $ bundle exec dotenv rackup --port 8081
+
+Run the SSE server:
+
+    $ bundle exec dotenv redisse --stdout --verbose
+
+Finally run nginx to glue them together:
+
+    $ nginx -p $PWD -c nginx.conf
+
+Open [http://localhost:8080/](http://localhost:8080/) in multiple browsers and
+tabs and then send messages to see them replicated.
+
+A Rack session cookie is used to randomly select one of four channels
+(`channel_1` to `channel_4`) and simulate different access rights for
+different users of your application.
+
+You can also send events from the command line:
+
+    $ bin/publish global message 'Hello CLI'

data/example/bin/publish

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+require 'bundler/setup'
+require 'dotenv'
+Dotenv.load
+require 'redisse'
+
+if count = ARGV.detect {|arg| arg.start_with?('N=') }
+  ARGV.delete(count)
+  count = count[/(\d+)/, 1].to_i
+else
+  count = 1
+end
+count.times do
+  puts "Event ##{ Redisse.publish ARGV[0], ARGV[1] => ARGV[2] } published"
+end

data/example/bin/redis

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+require 'bundler/setup'
+require 'dotenv'
+Dotenv.load
+
+puts "Starting Redis server on 127.0.0.1:#{ENV['REDIS_PORT']}"
+Process.exec 'redis-server ' \
+  '--daemonize yes '         \
+  '--pidfile redis.pid '     \
+  '--port $REDIS_PORT '      \
+  '--bind 127.0.0.1 '        \
+  '--logfile /dev/null '     \
+  '--databases 1'

data/example/config.ru

@@ -0,0 +1,40 @@
+require 'bundler/setup'
+require 'dotenv'
+Dotenv.load
+
+require 'redisse'
+
+Redisse.channels do |env|
+  env['rack.session']['channels'] ||=
+    %w[ global ] << "channel_#{rand(4)+1}"
+end
+
+class Application
+  def call(env)
+    request = Rack::Request.new env
+
+    if publish?(request)
+      Redisse.publish(request['channel'], request['message'])
+      return Rack::Response.new "No Content", 204
+    elsif subscriptions?(request)
+      return Rack::Response.new Redisse.channels(env).join(", "), 200
+    end
+
+    Rack::Response.new "Not Found", 404
+  end
+
+  def publish?(request)
+    request.post? && request.path_info == '/publish'
+  end
+
+  def subscriptions?(request)
+    request.get? && request.path_info == '/subscriptions'
+  end
+end
+
+use Rack::Session::Cookie, secret: 'not a secret'
+use Rack::Static, urls: {"/" => 'index.html'}, root: 'public', index: 'index.html'
+map "/events" do
+  run Redisse.redirect_endpoint
+end
+run Application.new

data/example/nginx.conf

@@ -0,0 +1,29 @@
+pid nginx.pid;
+error_log nginx.log error;
+daemon off;
+
+events {
+  worker_connections  1024;
+}
+
+http {
+  server {
+    listen 8080;
+
+    location / {
+      proxy_pass http://localhost:8081;
+
+      # necessary if lots of long-named channels
+      #proxy_buffer_size 8k;
+    }
+
+    location /redisse/ {
+      internal;
+      proxy_pass http://localhost:8082;
+      proxy_buffering off;
+      proxy_ignore_client_abort on;
+      proxy_http_version 1.1;
+    }
+  }
+  access_log off;
+}

data/example/public/index.html

@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html>
+<head><title>Redisse example: Rack app</title></head>
+<body>
+<h1>Redisse example: Rack app</h1>
+
+<p>Subscribed to: <span id=subscriptions></span></p>
+
+<form id=publish method=POST action=publish>
+  <label>Channel
+    <input name=channel value=global>
+  </label>
+  <label>Message
+    <input name=message value=Hello>
+  </label>
+  <input type=submit>
+</form>
+
+<pre id=log></pre>
+
+<script>
+  var subscriptions = document.getElementById('subscriptions')
+  var xhr = new XMLHttpRequest()
+  xhr.open('GET', '/subscriptions', false)
+  xhr.send(null)
+  subscriptions.innerHTML = xhr.responseText
+
+  var form = document.getElementById('publish')
+  form.addEventListener('submit', function(e) {
+    e.preventDefault()
+    var data = new FormData(form)
+    var xhr = new XMLHttpRequest()
+    xhr.open(form.method, form.action, false)
+    xhr.send(data)
+    return false
+  }, false)
+
+  var log = document.getElementById('log')
+  var source = new EventSource('/events')
+  source.addEventListener('message', function(e) {
+    log.innerHTML += e.data + "\n"
+  }, false)
+</script>
+
+</body>
+</html>