rack-stream 0.0.2 → 0.0.3

data/.gitignore

@@ -1,3 +1,4 @@
 .yardoc
 doc
 Gemfile.lock
+pkg

data/README.md

@@ -58,7 +58,8 @@ To run the example:
 ```
 
 This same endpoint can be accessed via WebSockets or EventSource, see
-'Multi-Protocol Support' below.
+'Multi-Protocol Support' below. Full examples can be found in the `examples`
+directory.
 
 ## Connection Lifecycle
 
@@ -82,7 +83,8 @@ Each state is described below.
 When a request first comes in, rack-stream processes any downstream
 rack apps and uses their status and headers for its response. Any
 downstream response bodies are queued for streaming once the headers
-and status have been sent.
+and status have been sent. Any calls to `#chunk` before a connection
+is opened is queued to be sent after a connection opens.
 
 ```ruby
 use Rack::Stream
@@ -155,7 +157,7 @@ An instance enters the `:errored` state if an illegal action is
 performed in one of the states. Legal actions for the different states
 are:
 
-* **new** - `#status=`, `#headers=`
+* **new** - `#chunk`, `#status=`, `#headers=`
 * **open** - `#chunk`, `#close`
 
 All other actions are considered illegal. Manipulating headers after
@@ -264,13 +266,15 @@ source.addEventListener('message', function(e) {
 * 1.9.3
 
 If a runtime is not listed above, it may still work. It just means I
-haven't tried it yet.
+haven't tried it yet. The only app server I've tried running is Thin.
 
 ## Roadmap
 
 * more protocols / custom protocols http://en.wikipedia.org/wiki/HTTP_Streaming
 * integrate into [grape](http://github.com/intridea/grape)
 * add sinatra example that serves page that uses JS to connect
+* deployment guide
+* better integration with rails
 
 ## Further Reading
 

data/lib/rack/stream.rb

@@ -1,4 +1,5 @@
 require 'eventmachine'
+require 'em-synchrony'
 require 'faye/websocket'
 
 require 'rack/stream/handlers'

data/lib/rack/stream/app.rb

@@ -22,24 +22,7 @@ module Rack
       end
 
       def call(env)
-        @env = env
-        @env['rack.stream'] = self
-
-        app_status, app_headers, app_body = @app.call(@env)
-
-        @status  = app_status
-        @headers = app_headers
-        @handler = Handlers.find(self)
-
-        # apply before_chunk to any response bodies
-        @callbacks[:after_open].unshift(lambda {chunk(*app_body)})
-
-        # By default, close a connection if no :after_open is specified
-        after_open {close} if @callbacks[:after_open].size == 1
-
-        EM.next_tick {
-          open!
-        }
+        EM.next_tick {open!(env)}
         ASYNC_RESPONSE
       end
 
@@ -54,7 +37,7 @@ module Rack
       end
 
       def chunk(*chunks)
-        require_state :open
+        require_state :new, :open
         run_callbacks(:chunk, chunks) {|mutated_chunks|
           @handler.chunk(*mutated_chunks)
         }
@@ -74,6 +57,11 @@ module Rack
         }
       end
 
+      # @return [String] name of the handler for this request
+      def stream_transport
+        @handler and @handler.class.name.split('::').last
+      end
+
       def new?;     @state == :new     end
       def open?;    @state == :open    end
       def closed?;  @state == :closed  end
@@ -92,12 +80,29 @@ module Rack
       # Transition state from :new to :open
       #
       # Freezes headers to prevent further modification
-      def open! #(server)
+      def open!(env)
+        @env = env
+        @env['rack.stream'] = self
         raise UnsupportedServerError.new "missing async.callback. run within thin or rainbows" unless @env['async.callback']
+
         run_callbacks(:open) {
+          @handler = Handlers.find(self)
+          @status, @headers, app_body = @app.call(@env)
+
+          app_body = if app_body.respond_to?(:body_parts)
+            app_body.body_parts
+          elsif app_body.respond_to?(:body)
+            app_body.body
+          else
+            app_body
+          end
+
+          chunk(*app_body) # chunk any downstream response bodies
+          after_open {close} if @callbacks[:after_open].empty?
+
+          @handler.open!
           @state = :open
           @headers.freeze
-          @handler.open!
         }
       end
 
@@ -123,11 +128,13 @@ module Rack
       define_callbacks :close, :before, :after
 
       def run_callbacks(name, *args)
-        modified = @callbacks["before_#{name}".to_sym].inject(args) do |memo, cb|
-          [cb.call(*memo)]
+        EM.synchrony do
+          modified = @callbacks["before_#{name}".to_sym].inject(args) do |memo, cb|
+            [cb.call(*memo)]
+          end
+          yield(*modified) if block_given?
+          @callbacks["after_#{name}".to_sym].each {|cb| cb.call(*args)}
         end
-        yield(*modified) if block_given?
-        @callbacks["after_#{name}".to_sym].each {|cb| cb.call(*args)}
       rescue StateConstraintError => e
         error!(e)
       end

data/lib/rack/stream/deferrable_body.rb

@@ -29,9 +29,12 @@ module Rack
 
       def close!(flush = true)
         EM.next_tick {
-          succeed if !flush
-          succeed if flush && empty?
-          schedule_dequeue if flush && !empty?
+          if !flush || empty?
+            succeed
+          else
+            schedule_dequeue
+            close!(flush)
+          end
         }
       end
 

data/lib/rack/stream/dsl.rb

@@ -6,7 +6,7 @@ module Rack
       def self.included(base)
         base.class_eval do
           extend Forwardable
-          def_delegators :rack_stream, :after_open, :before_chunk, :chunk, :after_chunk, :before_close, :close, :after_close
+          def_delegators :rack_stream, :after_open, :before_chunk, :chunk, :after_chunk, :before_close, :close, :after_close, :stream_transport
 
           def rack_stream
             env['rack.stream']

data/lib/rack/stream/handlers.rb

@@ -1,6 +1,10 @@
 module Rack
   class Stream
+    # A Handler is responsible for opening and closing connections
+    # to stream content.
     module Handlers
+      # @private
+      # TODO: allow registration of custom protocols
       def find(app)
         if Faye::WebSocket.websocket?(app.env)
           WebSocket.new(app)
@@ -12,49 +16,68 @@ module Rack
       end
       module_function :find
 
+      # All handlers should inherit from `AbstractHandler`
       class AbstractHandler
+
+        # @param app [Rack::Stream::App] reference to current request
         def initialize(app)
-          @app = app
+          @app  = app
+          @body = DeferrableBody.new
         end
 
+        # Enqueue content to be streamed at a later time.
+        #
+        # Optionally override this method if you need to control
+        # the content at a protocol level.
         def chunk(*chunks)
-          raise NotImplementedError
+          @body.chunk(*chunks)
         end
 
+        # @private
         def open!
+          open
+        end
+
+        # Implement `#open` to initiate a connection
+        def open
           raise NotImplementedError
         end
 
+        # @private
         def close!(flush = true)
+          close
+          @body.close!(flush)
+        end
+
+        # Implement `#close` for cleanup
+        # `#close` is called before the DeferrableBody is succeeded.
+        def close
           raise NotImplementedError
         end
       end
 
+      # This Handler works under EventMachine aware Rack servers like Thin
+      # and Rainbows! It does chunked transfer encoding.
       class Http < AbstractHandler
         TERM = "\r\n".freeze
         TAIL = "0#{TERM}#{TERM}".freeze
 
-        def initialize(app)
-          super
-          @app.headers['Transfer-Encoding'] = 'chunked'
-          @app.headers.delete('Content-Length')
-          @body = DeferrableBody.new  # swap this out for different body types
-        end
-
         def chunk(*chunks)
-          @body.chunk(*chunks.map {|c| encode_chunk(c)})
+          super(*chunks.map {|c| encode_chunk(c)})
         end
 
-        def open!
+        def open
+          @app.headers['Transfer-Encoding'] = 'chunked'
+          @app.headers.delete('Content-Length')
           @app.env['async.callback'].call [@app.status, @app.headers, @body]
         end
 
-        def close!(flush = true)
+        def close
           @body.chunk(TAIL)  # tail is special and already encoded
-          @body.close!(flush)
         end
 
         private
+
         def encode_chunk(c)
           return nil if c.nil?
 
@@ -65,32 +88,36 @@ module Rack
         end
       end
 
+      # This handler uses delegates WebSocket requests to faye-websocket
       class WebSocket < AbstractHandler
-        def chunk(*chunks)
-          # this is not called until after #open!, so @ws is always defined
-          chunks.each {|c| @ws.send(c)}
-        end
-
-        def close!(flush = true)
-          @ws.close(@app.status)
+        def close
+          @body.callback {
+            @ws.close(@app.status)
+          }
         end
 
-        def open!
+        def open
           @ws = Faye::WebSocket.new(@app.env)
+          @ws.onopen = lambda do |event|
+            @body.each {|c| @ws.send(c)}
+          end
         end
       end
 
-      class EventSource < WebSocket
-        def chunk(*chunks)
-          chunks.each {|c| @es.send(c)}
+      # This handler uses delegates EventSource requests to faye-websocket
+      class EventSource < AbstractHandler
+        # TODO: browser initiates connection again, isn't closed
+        def close
+          @body.callback {
+            @es.close
+          }
         end
 
-        def close!(flush = true)
-          @es.close
-        end
-
-        def open!
+        def open
           @es = Faye::EventSource.new(@app.env)
+          @es.onopen = lambda do |event|
+            @body.each {|c| @es.send(c)}
+          end
         end
       end
     end

data/rack-stream.gemspec

@@ -2,7 +2,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "rack-stream"
-  s.version     = "0.0.2"
+  s.version     = "0.0.3"
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Jerry Cheung"]
   s.email       = ["jerry@intridea.com"]
@@ -16,8 +16,9 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'rack'
   s.add_runtime_dependency 'eventmachine'
   s.add_runtime_dependency 'faye-websocket'
+  s.add_runtime_dependency 'em-synchrony'
 
-  s.files         = `git ls-files`.split("\n")
+  s.files         = `git ls-files`.split("\n").select {|f| f !~ /^example/}
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]

data/spec/integration/views/index.erb

@@ -8,28 +8,26 @@
   <h2>EventSource</h2>
   <ul id='es'></ul>
 
-  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
   <script type='text/javascript'>
     var socket, source;
 
-    function ws(m) {
-      $('<li>').text(m).appendTo('#ws');
+    function log(id, message) {
+      var li = document.createElement('li');
+      li.textContent = message;
+      document.getElementById(id).appendChild(li);
     }
 
-    function es(m) {
-      $('<li>').text(m).appendTo('#es');
-    }
+    function ws(m) {log('ws', m)}
+    function es(m) {log('es', m)}
 
-    $(function() {
-      socket = new WebSocket("ws://localhost:8888/");
-      socket.onopen    = function()  {ws('socket opened');}
-      socket.onmessage = function(m) {ws(m.data);}
-      socket.onclose   = function()  {ws('socket closed');}
+    socket = new WebSocket("ws://localhost:8888/");
+    socket.onopen    = function()  {ws('socket opened');}
+    socket.onmessage = function(m) {ws(m.data);}
+    socket.onclose   = function()  {ws('socket closed');}
 
-      source = new EventSource('http://localhost:8888/');
-      source.addEventListener('message', function(e) {
-        es(e.data);
-      });
+    source = new EventSource('http://localhost:8888/');
+    source.addEventListener('message', function(e) {
+      es(e.data);
     });
   </script>
 </body>

data/spec/lib/rack/stream_spec.rb

@@ -45,6 +45,42 @@ describe Rack::Stream do
     end
   end
 
+  context "queued content" do
+    let(:endpoint) {
+      lambda {|env|
+        env['rack.stream'].chunk "Chunky"
+        [200, {}, ['']]
+      }
+    }
+
+    it "should allow chunks to be queued outside of callbacks" do
+      last_response.body.should == "6\r\nChunky\r\n0\r\n\r\n"
+    end
+  end
+
+  context "synchrony" do
+    let(:endpoint) {
+      lambda {|env|
+        f = Fiber.current
+        EM.next_tick do
+          f.resume [200, {}, ["Chunky"]]
+        end
+
+        env['rack.stream'].instance_eval do
+          after_open do
+            chunk "Monkey"
+            close
+          end
+        end
+        Fiber.yield
+      }
+    }
+
+    it "should wrap evaluation in a fiber" do
+      last_response.body.should == "6\r\nChunky\r\n6\r\nMonkey\r\n0\r\n\r\n"
+    end
+  end
+
   context "basic streaming" do
     let(:endpoint) {
       lambda {|env|
@@ -122,4 +158,14 @@ describe Rack::Stream do
       $after_close_called = nil
     end
   end
+
+  context "stream transport" do
+    let(:endpoint) {
+      lambda {|env| [200, {}, [env['rack.stream'].stream_transport]]}
+    }
+
+    it "should be http by default" do
+      last_response.body.should == "4\r\nHttp\r\n0\r\n\r\n"
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack-stream
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-14 00:00:00.000000000 Z
+date: 2012-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -59,6 +59,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: em-synchrony
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Rack middleware for building multi-protocol streaming rack endpoints
 email:
 - jerry@intridea.com
@@ -75,10 +91,6 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- examples/basic.ru
-- examples/loop.ru
-- examples/no_stream.ru
-- examples/websocket_client.rb
 - lib/rack/stream.rb
 - lib/rack/stream/app.rb
 - lib/rack/stream/deferrable_body.rb

data/examples/basic.ru

@@ -1,7 +0,0 @@
-require 'rack/stream'
-
-use Rack::Stream
-
-run lambda {|env|
-  [200, {'Content-Type' => 'text/plain'}, ['hello', ' ', 'world']]
-}

data/examples/loop.ru

@@ -1,20 +0,0 @@
-require 'rack/stream'
-
-use Rack::Stream
-
-run lambda {|env|
-  env["rack.stream"].instance_eval do
-    count = 0
-    after_open do
-      timer = EM::PeriodicTimer.new(0.1) do
-        if count > 10
-          timer.cancel
-          close
-        end
-        chunk "Chunky\n"
-        count += 1
-      end
-    end
-  end
-  [200, {}, []]
-}

data/examples/no_stream.ru

@@ -1,4 +0,0 @@
-use Rack::Chunked
-run lambda {|env|
-  [200, {'Content-Type' => 'text/plain'}, ['hello', 'world']]
-}

data/examples/websocket_client.rb

@@ -1,15 +0,0 @@
-require 'faye/websocket'
-
-EM.run {
-  ws = Faye::WebSocket::Client.new('ws://localhost:3000/')
-  ws.onopen = lambda do |event|
-    ws.send("hello world")
-  end
-  ws.onmessage = lambda do |event|
-    puts "message: #{event.data}"
-  end
-  ws.onclose = lambda do |event|
-    puts "websocket closed"
-    EM.stop
-  end
-}