async-rack 0.4.0.b

data/README.md

@@ -0,0 +1,128 @@
+# AsyncRack
+
+So, have you been amazed by thin's `async.callback`? If not, [go](http://macournoyer.com/blog/2009/06/04/pusher-and-async-with-thin/) [check](http://github.com/raggi/async_sinatra) [it](http://github.com/raggi/thin/blob/async_for_rack/example/async_app.ru) [out](http://m.onkey.org/2010/1/7/introducing-cramp). Come back here when you start missing your middleware.
+
+So what is the issue with Rack and `async.callback`? Currently there are two ways of triggering a async responds. The first is to `throw :async`, the latter to return a status code of -1 (even though thin and ebb do disagree on that). Opposed to what others say, I would recommend using `throw`, as it simply skips middleware not able to handle `:async`. Also, it works on all servers supporting `async.callback` – thin, ebb, rainbows! and zbatery – about the same and copes better with middleware that is unable to handle an async respond.
+
+That's the issue with async.callback: Most middleware is not aware of it. Let's say you got an app somewhat like that:
+
+    class Farnsworth
+      def when_there_is_good_news
+        Thread.new do # Well, actually, you want to hook into your event loop instead, I guess.
+          wait_for_good_news
+          yield
+        end
+      end
+      
+      def call(env)
+        when_there_is_good_news do
+          env["async.callback"].call [200, {'Content-Type' => 'text/plain'}, ['Good news, everyone!']]
+        end
+        throw :async
+      end
+    end
+
+Ok, now, since this app could end up on Reddit, you better prepare yourself for some heavy traffic. Say, you want to use the `Rack::Deflate` middleware, so you set it up in your config.ru and add the link to reddit yourself. The next day you get a call from your server admin. Why don't you at least compress your http response? Well what happened? The problem is, that by sending your response via `env["async.callback"].call` you talk directly to your web server (i.e. thin), bypassing all potential middleware.
+
+Well, how do you avoid that? Simple: By just using middleware that plays well with `async.callback`. However, most middleware does not play well with it. In fact, most middleware that ships with rack does not play well with it. That's what I wrote this little library for. If you load `async-rack` it modifies all middleware that ships with rack, so it will work just fine with you throwing around your :async.
+
+How does that work? Simple, whenever necessary, `async-rack` will replace `async.callback` with an appropriate proc object, so it has the chance to do it's response modifications whenever you feel like answering the http request.
+
+Note: This library only 'fixes' the middleware that ships with rack, not other rack middleware. However, you can use the included helper classes to easily make other libraries handle `async.callback`.
+
+## How to make a middleware async-proof?
+There are three types of middleware:
+
+### Middleware doing stuff before handing on the request
+Example: `Rack:::MethodOverride`
+
+Such middleware already works fine with `async.callback`. Also, from our perspective, middleware either creating a own response and not calling your app at all, or calling your app without modifying neither request nor response falls into this category, too.
+
+Such middleware can easily be identified by having `@app.call(env)` or something similar as last line or always prefixed with a `return` inside the `call` method.
+
+### Middleware doing stuff after handing on the request
+Example: `Rack:::ETag`
+
+Here it is a bit tricky. Essentially what you want is running `#call` again on an `async.callback` but replace `@app.call(env)` with the parameter passed to `async.callback`. Well, apparently this is the most common case inside rack, so I created a mixin for that:
+
+    # Ok, Rack::FancyStuff does currently not work with async responses
+    require 'rack/fancy_stuff'
+    
+    class FixedFancyStuff < AsyncRack::AsyncCallback(:FancyStuff)
+      include AsyncRack::AsyncCallback::SimpleWrapper
+    end
+
+See below to get an idea what actually happens here.
+
+### Middleware meddling with both your request and your response
+Example: `Rack::Runtime`
+
+    # Let's assume there is some not so async middleware.
+    module Rack
+      class FancyStuff
+        def initialize(app)
+          @app = app
+        end
+        
+        def call(env)
+          prepare_fancy_stuff env
+          result = @app.call env
+          perform_fancy_stuff result
+        end
+        
+        def prepare_fancy_stuff(env)
+          # ...
+        end
+        
+        def perform_fancy_stuff(result)
+          # ...
+        end
+      end
+    end
+    
+    # What happens here is the following: We will subclass Rack::FancyStuff
+    # and then set Rack::FancyStuff = FixedFancyStuff. AsyncRack::AsyncCallback
+    # makes sure we don't screw that up.
+    class FixedFancyStuff < AsyncRack::AsyncCallback(:FancyStuff)
+      # this method will handle async.callback
+      def async_callback(result)
+        # pass it on to thin / ebb / other middleware
+        super perform_fancy_stuff(result)
+      end
+    end
+    
+    Rack::FancyStuff == FixedFancyStuff # => true
+
+## Setup
+In general: Place a `require 'async-rack'` before setting up any middleware or you will end up with the synchronous version!
+
+Please keep in mind that it only "fixes" middleware that ships with rack. Read: It works very well with Sinatra. With Rails and Merb, not so much!
+
+### With Rack
+In your `config.ru`:
+
+    require 'async-rack'
+    require 'your-app'
+    
+    use Rack::SomeMiddleware
+    run YourApp
+
+### With Sinatra
+In your application file:
+
+    require 'async-rack'
+    require 'sinatra'
+    
+    get '/' do
+      # do some async stuff here
+    end
+
+### With Rails 2.x
+In your `config/environment.rb`, add inside the `Rails::Initializer.run` block:
+
+    config.gem 'async-rack'
+
+### With Rails 3.x
+In your `Gemfile`, add:
+
+    gem 'async-rack'

data/lib/async-rack.rb

@@ -0,0 +1 @@
+require "async_rack"

data/lib/async_rack.rb

@@ -0,0 +1,46 @@
+require "rack"
+require "async_rack/async_callback"
+
+module AsyncRack
+  module BaseMixin
+    ::Rack.extend self
+    ::Rack::Session.extend self
+    def autoload(class_name, path)
+      super unless autoload?(class_name) =~ /async_rack/
+    end
+  end
+
+  module ExtensionMixin
+    ::AsyncRack.extend self
+    def autoload(class_name, path)
+      super
+      if Rack.autoload? class_name then Rack.autoload(class_name, path)
+      elsif Rack.const_defined? class_name then require path
+      end
+    end
+  end
+
+  # Wrapped rack middleware
+  autoload :Chunked,        "async_rack/chunked"
+  autoload :CommonLogger,   "async_rack/commonlogger"
+  autoload :ConditionalGet, "async_rack/conditionalget"
+  autoload :ContentLength,  "async_rack/content_length"
+  autoload :ContentType,    "async_rack/content_type"
+  autoload :Deflater,       "async_rack/deflater"
+  autoload :ETag,           "async_rack/etag"
+  autoload :Head,           "async_rack/head"
+  autoload :Lock,           "async_rack/lock"
+  autoload :Logger,         "async_rack/logger"
+  # autoload :Recursive, "async_rack/recursive"
+  autoload :Runtime,        "async_rack/runtime"
+  autoload :Sendfile,       "async_rack/sendfile"
+  autoload :ShowStatus,     "async_rack/showstatus"
+
+  module Session
+    extend ExtensionMixin
+    autoload :Cookie,   "async_rack/session/cookie"
+    autoload :Pool,     "async_rack/session/pool"
+    autoload :Memcache, "async_rack/session/memcache"
+  end
+
+end

data/lib/async_rack/async_callback.rb

@@ -0,0 +1,106 @@
+module AsyncRack
+
+  ##
+  # @see AsyncRack::AsyncCallback
+  def self.AsyncCallback(name, namespace = Rack)
+    @wrapped ||= Hash.new { |h,k| h[k] = {} }
+    @wrapped[namespace][name.to_sym] ||= namespace.const_get(name).tap do |klass|
+      klass.extend AsyncCallback::InheritanceHook
+      klass.alias_subclass name, namespace
+    end
+  end
+
+  ##
+  # Helps wrapping already existent middleware in a transparent manner.
+  #
+  # @example
+  #   module Rack
+  #     class FancyMiddleware
+  #     end
+  #   end
+  #
+  #   module AsyncRack
+  #     class FancyMiddleware < AsyncCallback(:FancyMiddleware)
+  #     end
+  #   end
+  #
+  #   Rack::FancyMiddleware # => AsyncRack::FancyMiddleware
+  #   AsyncRack::FancyMiddleware.ancestors # => [AsyncRack::AsyncCallback::Mixin, Rack::FancyMiddleware, ...]
+  module AsyncCallback
+
+    ##
+    # Aliases a subclass on subclassing, but only once.
+    # If that name already is in use, it will be replaced.
+    #
+    # @example
+    #   class Foo
+    #     def self.bar
+    #       23
+    #     end
+    #   end
+    #
+    #   Foo.extend AsyncRack::AsyncCallback::InheritanceHook
+    #   Foo.alias_subclass :Baz
+    #
+    #   class Bar < Foo
+    #     def self.bar
+    #       super + 19
+    #     end
+    #   end
+    #
+    #   Baz.bar # => 42
+    module InheritanceHook
+
+      ##
+      # @param [Symbol] name Name it will be aliased to
+      # @param [Class, Module] namespace The module the constant will be defined in
+      def alias_subclass(name, namespace = Object)
+        @alias_subclass = [name, namespace]
+      end
+
+      ##
+      # @see InheritanceHook
+      def inherited(klass)
+        super
+        if @alias_subclass
+          name, namespace = @alias_subclass
+          @alias_subclass = nil
+          namespace.send :remove_const, name if namespace.const_defined? name
+          namespace.const_set name, klass
+          klass.send :include, AsyncRack::AsyncCallback::Mixin
+        end
+      end
+    end
+
+    module Mixin
+      def async_callback(result)
+        @async_callback.call result
+      end
+
+      def setup_async(env)
+        return false if @async_callback
+        @async_callback = env['async.callback']
+        env['async.callback'] = method :async_callback
+        @env = env
+      end
+
+      def call(env)
+        setup_async env
+        super
+      end
+    end
+
+    ##
+    # A simple wrapper is useful if the first thing a middleware does is something like
+    # @app.call and then modifies the response.
+    #
+    # In that case you just have to include SimpleWrapper in your async wrapper class.
+    module SimpleWrapper
+      include AsyncRack::AsyncCallback::Mixin
+      def async_callback(result)
+        @app = proc { result }
+        super call(@env)
+      end
+    end
+  end
+end

data/lib/async_rack/chunked.rb

@@ -0,0 +1,7 @@
+require "rack/chunked"
+
+module AsyncRack
+  class Chunked < AsyncCallback(:Chunked)
+    include AsyncRack::AsyncCallback::SimpleWrapper
+  end
+end

data/lib/async_rack/commonlogger.rb

@@ -0,0 +1,17 @@
+require "rack/commonlogger"
+
+module AsyncRack
+  class CommonLogger < AsyncCallback(:CommonLogger)
+    def async_callback(result)
+      status, header, body = result
+      header = Rack::Utils::HeaderHash.new header
+      log env, status, header, @began_at
+      super [status, header, body]
+    end
+
+    def call(env)
+      @began_at = Time.now
+      super
+    end
+  end
+end

data/lib/async_rack/conditionalget.rb

@@ -0,0 +1,7 @@
+require "rack/conditionalget"
+
+module AsyncRack
+  class ConditionalGet < AsyncCallback(:ConditionalGet)
+    include AsyncRack::AsyncCallback::SimpleWrapper
+  end
+end

data/lib/async_rack/content_length.rb

@@ -0,0 +1,7 @@
+require "rack/content_length"
+
+module AsyncRack
+  class ContentLength < AsyncCallback(:ContentLength)
+    include AsyncRack::AsyncCallback::SimpleWrapper
+  end
+end

data/lib/async_rack/content_type.rb

@@ -0,0 +1,7 @@
+require "rack/content_type"
+
+module AsyncRack
+  class ContentType < AsyncCallback(:ContentType)
+    include AsyncRack::AsyncCallback::SimpleWrapper
+  end
+end

data/lib/async_rack/deflater.rb

@@ -0,0 +1,7 @@
+require "rack/deflater"
+
+module AsyncRack
+  class Deflater < AsyncCallback(:Deflater)
+    include AsyncRack::AsyncCallback::SimpleWrapper
+  end
+end

data/lib/async_rack/etag.rb

@@ -0,0 +1,7 @@
+require "rack/etag"
+
+module AsyncRack
+  class ETag < AsyncCallback(:ETag)
+    include AsyncRack::AsyncCallback::SimpleWrapper
+  end
+end

data/lib/async_rack/head.rb

@@ -0,0 +1,7 @@
+require "rack/head"
+
+module AsyncRack
+  class Head < AsyncCallback(:Head)
+    include AsyncRack::AsyncCallback::SimpleWrapper
+  end
+end

data/lib/async_rack/lock.rb

@@ -0,0 +1,9 @@
+require "rack/lock"
+
+module AsyncRack
+  class Lock < AsyncCallback(:Lock)
+    def async_callback(result)
+      raise RuntimeError, "does not support async.callback"
+    end
+  end
+end

data/lib/async_rack/logger.rb

@@ -0,0 +1,21 @@
+require "rack/logger"
+
+module AsyncRack
+  class Logger < AsyncCallback(:Logger)
+    def async_callback(result)
+      @logger.close
+      super
+    end
+
+    def call(env)
+      @logger = ::Logger.new(env['rack.errors'])
+      @logger.level = @level
+      env['rack.logger'] = @logger
+      @app.call(env) # could throw :async
+      @logger.close
+    rescue Exception => error # does not get triggered by throwing :async (ensure does)
+      @logger.close
+      raise error
+    end
+  end
+end

data/lib/async_rack/runtime.rb

@@ -0,0 +1,17 @@
+require "rack/runtime"
+
+module AsyncRack
+  class Runtime < AsyncCallback(:Runtime)
+    def async_callback(result)
+      status, headers, body =result
+      request_time = Time.now - start_time
+      headers[@header_name] = "%0.6f" % request_time if !headers.has_key?(@header_name)
+      [status, headers, body]
+    end
+
+    def call(env)
+      @start_time = Time.now
+      super
+    end
+  end
+end

data/lib/async_rack/sendfile.rb

@@ -0,0 +1,7 @@
+require "rack/sendfile"
+
+module AsyncRack
+  class Sendfile < AsyncCallback(:Sendfile)
+    include AsyncRack::AsyncCallback::SimpleWrapper
+  end
+end

data/lib/async_rack/session/cookie.rb

@@ -0,0 +1,11 @@
+require "rack/cookie"
+
+module AsyncRack
+  module Session
+    class Cookie < AsyncCallback(:Cookie, Rack::Session)
+      def async_callback(result)
+        super commit_session(@env, *result)
+      end
+    end
+  end
+end

data/lib/async_rack/session/memcache.rb

@@ -0,0 +1,11 @@
+require "rack/memcache"
+
+module AsyncRack
+  module Session
+    class Memcache < AsyncCallback(:Memcache, Rack::Session)
+      def async_callback(result)
+        super commit_session(@env, *result)
+      end
+    end
+  end
+end

data/lib/async_rack/session/pool.rb

@@ -0,0 +1,11 @@
+require "rack/pool"
+
+module AsyncRack
+  module Session
+    class Pool < AsyncCallback(:Pool, Rack::Session)
+      def async_callback(result)
+        super commit_session(@env, *result)
+      end
+    end
+  end
+end

data/lib/async_rack/showstatus.rb

@@ -0,0 +1,7 @@
+require "rack/showstatus"
+
+module AsyncRack
+  class ShowStatus < AsyncCallback(:ShowStatus)
+    include AsyncRack::AsyncCallback::SimpleWrapper
+  end
+end

data/spec/async_rack/async_callback_spec.rb

@@ -0,0 +1,55 @@
+require File.expand_path("../../spec_helper", __FILE__)
+
+describe AsyncRack::AsyncCallback do
+  before do
+    @namespace = Module.new
+    @namespace.const_set :Foo, Class.new
+  end
+
+  it "wraps rack middleware by replacing it" do
+    non_async_middleware = @namespace::Foo
+    @namespace::Foo.should == non_async_middleware
+    async_middleware = Class.new AsyncRack::AsyncCallback(:Foo, @namespace)
+    @namespace::Foo.should_not == non_async_middleware
+    @namespace::Foo.should == async_middleware
+    AsyncRack::AsyncCallback(:Foo, @namespace).should == non_async_middleware
+  end
+
+  describe :InheritanceHook do
+    it "alows aliasing subclasses automatically" do
+      @namespace::Foo.extend AsyncRack::AsyncCallback::InheritanceHook
+      @namespace::Foo.alias_subclass :Bar, @namespace
+      subclass = Class.new(@namespace::Foo)
+      @namespace::Bar.should == subclass
+    end
+  end
+
+  describe :SimpleWrapper do
+    it "runs #call again on async callback, replacing app" do
+      klass = Class.new do
+        include AsyncRack::AsyncCallback::SimpleWrapper
+        attr_accessor :app, :env
+        def call(env)
+          setup_async env
+          @app.call(env) + 5
+        end
+      end
+      middleware = klass.new
+      middleware.app = proc { throw :async }
+      catch(:async) do
+        middleware.call "async.callback" => proc { |x| x + 10 }
+        raise "should not get here"
+      end
+      middleware.env["async.callback"].call(0).should == 15
+    end
+  end
+
+  describe :Mixin do
+    it "wrapps async.callback" do
+      @middleware = proc { |env| env['async.callback'].call [200, {'Content-Type' => 'text/plain'}, ['OK']] }
+      @middleware.extend AsyncRack::AsyncCallback::Mixin
+      @middleware.should_receive(:async_callback)
+      @middleware.call "async.callback" => proc { }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+require "async-rack"

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification 
+name: async-rack
+version: !ruby/object:Gem::Version 
+  prerelease: true
+  segments: 
+  - 0
+  - 4
+  - 0
+  - b
+  version: 0.4.0.b
+platform: ruby
+authors: 
+- Konstantin Haase
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-09 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rack
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 1
+        - 0
+        version: 1.1.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id002
+description: Makes middleware that ships with Rack bullet-proof for async responses.
+email: konstantin.mailinglists@googlemail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/async-rack.rb
+- lib/async_rack/async_callback.rb
+- lib/async_rack/chunked.rb
+- lib/async_rack/commonlogger.rb
+- lib/async_rack/conditionalget.rb
+- lib/async_rack/content_length.rb
+- lib/async_rack/content_type.rb
+- lib/async_rack/deflater.rb
+- lib/async_rack/etag.rb
+- lib/async_rack/head.rb
+- lib/async_rack/lock.rb
+- lib/async_rack/logger.rb
+- lib/async_rack/runtime.rb
+- lib/async_rack/sendfile.rb
+- lib/async_rack/session/cookie.rb
+- lib/async_rack/session/memcache.rb
+- lib/async_rack/session/pool.rb
+- lib/async_rack/showstatus.rb
+- lib/async_rack.rb
+- spec/async_rack/async_callback_spec.rb
+- spec/spec_helper.rb
+- README.md
+has_rdoc: yard
+homepage: http://github.com/rkh/async-rack
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Makes middleware that ships with Rack bullet-proof for async responses.
+test_files: []
+