gorsse 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bffb89b9e63f2abe4eea6f3b91f65c4f8b08d24d
+  data.tar.gz: fee3dec259477b40b7cf65dfe5b1b53ad6bbe364
+SHA512:
+  metadata.gz: 4c1aa5c596190dc4c21ccfd30c5d99ca9a0431d47955de8191d6fbe0600c134c340c18e402040a9d59b726733585f2e7278eee12f08636c724fd664e9e04d9f7
+  data.tar.gz: 6229d81e78d340d42cd3a9b51a4818b55abe557036d5c7021123e9d02d53cb4c6c001d96fb04a26ee698708d9bf3fae75b102a41061e58ca658a82ed9f4d1cc9

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENCE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README.md

@@ -0,0 +1,219 @@
+# Gorsse (Go Ruby SSE)
+
+<a href="http://twitter.com/nicoolas25"><img src="http://www.pairprogramwith.me/assets/badge.svg" style="height:40px" title="We can pair on this!" /></a>
+
+This is an proof of concept for an SSE system that will support many
+users without compromising a Ruby server that isn't that good to handle
+a lot of alive connections.
+
+The typical flow is:
+
+1. The server povides an application
+2. The client needs realtime informations from the server
+3. The client establish a SSE connection to the application
+4. The server send the informations via the SSE connection
+5. The client is happy to have real-time updates
+
+If your application get too many client, your server will have to handle
+as much as connections. Since Ruby isn't very well suited for parallelism,
+the existing webservers forks and/or threads the application to handle
+multiple requests at a time. To serve two clients exactly at the same time,
+you have to run two instances of your application. If those two client need
+to keep the connection alive then your application is down to the rest of
+the world...
+
+This may be not the case on all the Ruby implementation and for all
+webservers, see the alternative section for more details about it.
+
+## Usage examples
+
+This project can be useful when you're using:
+
+* chat systems,
+* asynchronous job notifications,
+* live monitoring,
+* et cetera
+
+
+## Architecture
+
+The whole idea is to keep your Ruby application as it is, adding one
+or two other elements to your existing architecture.
+
+### The connection handler
+
+When you run the connection handler, it will accept HTTP requests and
+stream the response to the client. It will maintain the connection to the
+client open.
+
+The connection handler will also listen events from your application. When
+a such event is received, it is forwarded to the relevent clients.
+
+The connection handler lives in a separate project. It's written in a
+language that have a more advanced concurrency and parallelism model than
+Ruby.
+
+See the documentation of the connection handler to configure it.
+
+### The callback receiver (optionnal)
+
+This element receive callback from the connection handler. Those
+callbacks can trigger business Ruby code depending on your needs.
+
+If you don't need the callback receiver, you should disable them in
+the connection handler configuration. In this case, you dont have to
+run this component at all.
+
+### Communication
+
+ZeroMQ allows the communication between:
+
+* your application, that send event to the connection handler,
+* the connection handler, that receive those events via SSE and
+* the callback receiver.
+
+## Integration
+
+This is probably the part that you've been waiting...
+
+### Configuration
+
+First of all, your application must require 'gorsse' and configure it
+properly:
+
+~~~ruby
+require 'gorsse'
+
+Gorsse.configure do |config|
+  config.receiver = 'tcp://127.0.0.1:4567'
+  config.handler  = 'tcp://127.0.0.1:4568'
+end
+~~~
+
+The addresses are directly passed to ZeroMQ, feel free to take advantage
+of it.
+
+The receiver line isn't required unless you use the callback receiver.
+
+### Protocols & scopes
+
+Gorsse is using two concepts to create SSE channels where it is possible
+to publish informations.
+
+*Protocols* match a specific communication pattern from your server to
+your clients. This is an example of a two empty protocol:
+
+~~~ruby
+class PostFeed < Gorsse::Protocol ; end
+class ChatFeed < Gorsse::Protocol ; end
+~~~
+
+*Scopes* are like an instance of the protocol, it's narrowing it. For
+instance, if your application is a blog provider SaaS then you'll have
+one `PostFeed` scope per blog. Or, if your application is a chat server
+then you'll have one `ChatFeed` scope per channel.
+
+~~~ruby
+endpoint = ChatFeed.new('room42')
+~~~
+
+You can see the protocol and scope as an endpoint like `/ChatFeed/room42`.
+
+### Sending events
+
+From the previous example, you can publish a message to all the connected
+clients with the following code:
+
+~~~ruby
+class Message < Struct.new(:author, :content)
+  # This is required to be send as an event by Gorsse.
+  # @return String
+  def to_sse
+    "#{author}|#{content}"
+  end
+end
+
+message = Message.new('Bob', 'Hello!')
+endpoint.signal(message)
+~~~
+
+The previous code will generate the following lines in the SSE stream:
+
+~~~
+event: Message
+data: Bob|Hello!
+ 
+~~~
+
+### Private messages
+
+You can achieve private messages with scopes.
+
+There is also a notion of Client that allows you to do something like this:
+
+~~~ruby
+client = Gorsse::Client.new('124df54b0')
+message = Message.new('Alice', 'Goodbye...')
+endpoint.signal(message, target: client)
+~~~
+
+*This section should be completed.*
+
+The missing piece here is that we need something to pass the client identity
+from the server to the client then to the connection handler...
+
+## Installation
+
+Add the classic line to your Gemfile:
+
+~~~
+gem 'gorsse'
+~~~
+
+Compile your own binaries for the connection handler (see the dedicated README
+in the `gorsse_server` directory). You can also ask me for a binary version.
+
+## Alternative
+
+There are many other solutions out there that are aiming the same goal.
+You can try to fix the server with Goliath or you can rely on external
+components with Faye.
+
+There is a good article about [SSE in Ruby][ruby-sse] with Goliath and
+EventMachine. The implementation now relies on EM channels that are
+something native in Go. The backend of Gorsse could have been written as
+described here.
+
+I don't think webservers like Puma are a viable alternative even if it
+is using threads to handle requests. I'll be glad to have your feedback
+on it.
+
+Of course all of this project is tied to the Ruby world. You can have
+it all for free with other platforms like Meteor...
+
+## TODOs
+
+* Documentation about proxying via nginx
+* Tests both for the Go code and the Ruby code
+* Benchmarking versus the alternatives
+* Any other useful stuff that I didn't think of...
+
+## Contributions
+
+They're welcome! Just know that this is a toy project for me yet.
+Even if I'll be glad to receive contributions and advices about it
+I may not be able to provide a excellent level of support.
+
+## Licence
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+[ruby-sse]: http://robots.thoughtbot.com/chat-example-app-using-server-sent-events

data/lib/gorsse.rb

@@ -0,0 +1,41 @@
+module Gorsse
+  {
+    :Client     => 'client',
+    :Command    => 'command',
+    :Config     => 'config',
+    :Connection => 'connection',
+    :Event      => 'event',
+    :Protocol   => 'protocol',
+    :VERSION    => 'version',
+  }.each { |mod, file| autoload mod, "gorsse/#{file}" }
+
+  def self.configure(&block)
+    block.call(config)
+  end
+
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.close_connections
+    @conn && @conn.close
+    @receiver_conn && @receiver_conn.close
+    Connection::ZCTX.terminate
+  end
+
+  def self.conn
+    @conn ||= Connection.new(config.handler, mode: :push, method: :connect)
+  end
+
+  def self.receiver_conn
+    @receiver_conn ||= Connection.new(config.receiver, mode: :pull, method: :bind)
+  end
+
+  def self.start_receiver_loop!
+    loop do
+      message = receiver_conn.receive
+      command = Command.new(message)
+      command.run!
+    end
+  end
+end

data/lib/gorsse/client.rb

@@ -0,0 +1,13 @@
+module Gorsse
+  class Client
+    attr_reader :uid
+
+    def initialize(uid)
+      @uid = uid
+    end
+
+    def eql?(other)
+      other.is_a?(Client) && uid == other.uid
+    end
+  end
+end

data/lib/gorsse/command.rb

@@ -0,0 +1,16 @@
+require 'json'
+
+module Gorsse
+  class Command
+    def initialize(command)
+      @command = JSON.parse(command)
+    end
+
+    def run!
+      protocol_class = Object.const_get(@command['Protocol'])
+      protocol = protocol_class.new(@command['Scope'])
+      client = Client.new(@command['Client'])
+      protocol.__send__(@command['Callback'], client)
+    end
+  end
+end

data/lib/gorsse/config.rb

@@ -0,0 +1,5 @@
+module Gorsse
+  class Config
+    attr_accessor :receiver, :handler
+  end
+end

data/lib/gorsse/connection.rb

@@ -0,0 +1,40 @@
+require 'ffi-rzmq'
+
+module Gorsse
+  # This class hide the ZMQ library but it is closely tied to it.
+  class Connection
+    ZCTX = ZMQ::Context.new(1)
+
+    CONNECTION_MODE = {
+      rep: ZMQ::REP,
+      req: ZMQ::REQ,
+      pub: ZMQ::PUB,
+      sub: ZMQ::SUB,
+      pull: ZMQ::PULL,
+      push: ZMQ::PUSH,
+    }
+
+    # Open a connection to an URL. You can act as a server or as
+    # a client by tunning the 'server' parameter.
+    def initialize(url, mode: :push, method: :connect)
+      @zmq_socket = ZCTX.socket(CONNECTION_MODE[mode])
+      @zmq_socket.__send__(method, url)
+      puts '%s with %s to %s' % [method, mode, url]
+    end
+
+    def send(string, flags: 0)
+      puts 'Sending: %s' % string
+      @zmq_socket.send_string(string, flags)
+    end
+
+    def receive(flags: 0)
+      message = ''
+      @zmq_socket.recv_string(message, flags)
+      message
+    end
+
+    def close
+      @zmq_socket.close
+    end
+  end
+end

data/lib/gorsse/event.rb

@@ -0,0 +1,41 @@
+require 'json'
+
+module Gorsse
+  class Event
+    def initialize(protocol, target, entity)
+      @protocol = protocol
+      @target = target
+      @entity = entity
+    end
+
+    def send!
+      json = JSON.generate(msg)
+      Gorsse.conn.send(json)
+    end
+
+    private
+
+    def msg
+      hash = {
+        'proto' => sse_class_for(@protocol),
+        'scope' => @protocol.scope,
+        'client' => @target.kind_of?(Client) ? @target.uid : 'all',
+      }
+
+      if @entity.respond_to?(:to_sse)
+        hash['title'] = sse_class_for(@entity)
+        hash['content'] = @entity.to_sse
+      else
+        hash['title'] = @entity.to_s
+        hash['content'] = ''
+      end
+
+      hash
+    end
+
+    def sse_class_for(instance)
+      klass = instance.class
+      klass.respond_to?(:sse_name) ? klass.sse_name : klass.name
+    end
+  end
+end

data/lib/gorsse/protocol.rb

@@ -0,0 +1,23 @@
+module Gorsse
+  class Protocol
+    attr_reader :scope
+
+    def initialize(scope)
+      @scope = scope
+    end
+
+    # Send a message to the client through the Gorsse server.
+    def signal(entity, target: :all)
+      event = Event.new(self, target, entity)
+      event.send!
+    end
+
+    def after_connect(client_id)
+      # Do nothing. Override in subclasses.
+    end
+
+    def eql?(other)
+      self.class == other.class && self.scope == other.scope
+    end
+  end
+end

data/lib/gorsse/version.rb

@@ -0,0 +1,3 @@
+module Gorsse
+  VERSION = "0.0.1"
+end

data/spec/gorsse/event_spec.rb

@@ -0,0 +1,51 @@
+require 'test_helper.rb'
+
+describe Gorsse::Event do
+  let(:protocol_class) { stub_const('Protocol', Class.new(Gorsse::Protocol)) }
+  let(:event) { Gorsse::Event.new(protocol, target, entity) }
+
+  describe '#send!' do
+    before { allow(Gorsse.conn).to receive(:send).and_return(nil) }
+
+    subject { event.send! }
+
+    let(:scope) { 'scope' }
+    let(:protocol) { protocol_class.new(scope) }
+    let(:target) { :all }
+    let(:entity) { 'no_data' }
+
+    it 'sends json event data though the Gorsse.conn connection' do
+      expected_json = %Q({"proto":"Protocol","scope":"scope","client":"all","title":"no_data","content":""})
+      expect(Gorsse.conn).to receive(:send).with(expected_json)
+      subject
+    end
+
+    context 'when the target is a client' do
+      let(:target) { Gorsse::Client.new('1234') }
+
+      it 'sends the client uid in the "client" fields' do
+        expected_json = %Q({"proto":"Protocol","scope":"scope","client":"1234","title":"no_data","content":""})
+        expect(Gorsse.conn).to receive(:send).with(expected_json)
+        subject
+      end
+    end
+
+    context 'when the entity respond to the "to_sse" method' do
+      let(:entity) { double( class: double( name: 'Entity' ) ) }
+
+      it 'sends the entity class name as the "title" field' do
+        expected_json = %Q({"proto":"Protocol","scope":"scope","client":"all","title":"Entity","content":""})
+        allow(entity).to receive(:to_sse).and_return('')
+        expect(Gorsse.conn).to receive(:send).with(expected_json)
+        subject
+      end
+
+      it 'sends the result of the "to_sse" call as the "content" field' do
+        expected_json = %Q({"proto":"Protocol","scope":"scope","client":"all","title":"Entity","content":"data"})
+        allow(entity).to receive(:to_sse).and_return('data')
+        expect(Gorsse.conn).to receive(:send).with(expected_json)
+        subject
+      end
+    end
+  end
+end

data/spec/test_helper.rb

@@ -0,0 +1,14 @@
+require 'gorsse'
+
+Gorsse.configure do |config|
+  config.receiver = 'tcp://127.0.0.1:4567'
+  config.handler  = 'tcp://127.0.0.1:4568'
+end
+
+class FakeConnection ; end
+
+RSpec.configure do |config|
+  config.before(:example) do
+    allow(Gorsse).to receive(:conn).and_return(FakeConnection.new)
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: gorsse
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nicolas ZERMATI
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi-rzmq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- nicoolas25@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENCE
+- README.md
+- lib/gorsse.rb
+- lib/gorsse/client.rb
+- lib/gorsse/command.rb
+- lib/gorsse/config.rb
+- lib/gorsse/connection.rb
+- lib/gorsse/event.rb
+- lib/gorsse/protocol.rb
+- lib/gorsse/version.rb
+- spec/gorsse/event_spec.rb
+- spec/test_helper.rb
+homepage: ''
+licenses:
+- LGPL
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Have nice and fast SSE capabilities with any Ruby webserver.
+test_files:
+- spec/gorsse/event_spec.rb
+- spec/test_helper.rb