goliath 0.9.2 → 0.9.4

data/lib/goliath/{synchrony → deprecated}/mongo_receiver.rb

@@ -1,7 +1,16 @@
-require 'goliath/synchrony/response_receiver'
+require 'goliath/deprecated/response_receiver'
+require 'em-synchrony/em-mongo'
 
 module Goliath
   module Synchrony
+    #
+    # Note: This class is deprecated. Please instead use BarrierAroundware
+    # (orchestrates multiple concurrent requests) or SimpleAroundware (like
+    # AsyncMiddleware, but with a simpler interface).
+    #
+    # There are more notes on the lib/goliath/deprecated/async_aroundware docs.
+    #
+    # ___________________________________________________________________________
     #
     # Currently, you must provide in the env a method 'mongo' that returns a mongo
     # collection or collection proxy (probably by setting it up in the config).
@@ -31,18 +40,29 @@ module Goliath
         # ... requests aren't deferrables so they're tracked in @pending_queries
       end
 
-      def find(collection, selector={}, opts={}, &block)
-        @pending_queries += 1
-        db.collection(collection).find(selector, opts) do |result|
-          yield result
-          @pending_queries -= 1
-          self.succeed if finished?
+      if defined?(EM::Mongo::Cursor)
+        def find(collection, selector={}, opts={}, &block)
+          @pending_queries += 1
+          db.collection(collection).afind(selector, opts).to_a.callback do |result|
+            yield result
+            @pending_queries -= 1
+            self.succeed if finished?
+          end
+        end
+      else
+        def find(collection, selector={}, opts={}, &block)
+          @pending_queries += 1
+          db.collection(collection).afind(selector, opts) do |result|
+            yield result
+            @pending_queries -= 1
+            self.succeed if finished?
+          end
         end
       end
 
       def first(collection, selector={}, opts={}, &block)
         opts[:limit] = 1
-        find(collection, selector, opts) do |result|
+        self.find(collection, selector, opts) do |result|
           yield result.first
         end
       end

data/lib/goliath/deprecated/response_receiver.rb

@@ -0,0 +1,97 @@
+module Goliath
+  module Synchrony
+
+    #
+    # Note: This class is deprecated. Please instead use BarrierAroundware
+    # (orchestrates multiple concurrent requests) or SimpleAroundware (like
+    # AsyncMiddleware, but with a simpler interface).
+    #
+    # There are more notes on the lib/goliath/deprecated/async_aroundware docs.
+    #
+    module ResponseReceiver
+      # The request environment, set in the initializer
+      attr_reader :env
+      # The response, set by the ResponseReceiver's downstream
+      attr_accessor :status, :headers, :body
+
+      # Override this method in your middleware to perform any preprocessing
+      # (launching a deferred request, perhaps).
+      #
+      # @return [Array] array contains [status, headers, body]
+      def pre_process
+        Goliath::Connection::AsyncResponse
+      end
+
+      # Override this method in your middleware to perform any postprocessing.
+      # This will only be invoked when all deferred requests (including the
+      # response) have completed.
+      #
+      # @return [Array] array contains [status, headers, body]
+      def post_process
+        [status, headers, body]
+      end
+
+      # Virtual setter for the downstream middleware/endpoint response
+      def downstream_resp=(status_headers_body)
+        @status, @headers, @body = status_headers_body
+      end
+
+      # Invoked by the async_callback chain. Stores the [status, headers, body]
+      # for post_process'ing
+      def call resp
+        return resp if resp.first == Goliath::Connection::AsyncResponse.first
+        self.downstream_resp = resp
+        check_progress(nil)
+      end
+
+      # Have we received a response?
+      def response_received?
+        !! @status
+      end
+
+    protected
+
+      def check_progress(fiber)
+        if finished?
+          succeed
+          # continue processing
+          fiber.resume(self) if fiber && fiber.alive? && fiber != Fiber.current
+        end
+      end
+    end
+
+    #
+    # Note: This class is deprecated. Please instead use BarrierAroundware
+    # (orchestrates multiple concurrent requests) or SimpleAroundware (like
+    # AsyncMiddleware, but with a simpler interface).
+    #
+    # There are more notes on the lib/goliath/deprecated/async_aroundware docs.
+    #
+    class MultiReceiver < EM::Synchrony::Multi
+      include ResponseReceiver
+
+      # Create a new MultiReceiver
+      # @param env [Goliath::Env] the current environment
+      def initialize env
+        @env = env
+        super()
+      end
+
+      alias_method :enqueue, :add
+
+      def successes
+        responses[:callback]
+      end
+
+      def failures
+        responses[:errback]
+      end
+
+      # Finished if we received a response and the multi request is finished
+      def finished?
+        super && response_received?
+      end
+    end
+
+  end
+end

data/lib/goliath/env.rb

@@ -6,6 +6,7 @@ module Goliath
   # Goliath::Env also provides access to the logger, configuration information
   # and anything else set into the config data during initialization.
   class Env < Hash
+    attr_accessor :event_handler
     include Constants
 
     # Create a new Goliath::Env object
@@ -121,6 +122,10 @@ module Goliath
       super
     end
 
+    def defer_stack
+      @defer_stack ||= []
+    end
+
     # The Goliath::Env will provide any of it's keys as a method. It will also provide
     # any of the keys in the config object as methods. The methods will return
     # the value of the key. If the key doesn't exist in either hash this will

data/lib/goliath/rack.rb

@@ -1,7 +1,8 @@
 module Goliath
   module Rack
-    autoload :AsyncAroundware,        'goliath/rack/async_aroundware'
     autoload :AsyncMiddleware,        'goliath/rack/async_middleware'
+    autoload :BarrierAroundware,      'goliath/rack/barrier_aroundware'
+    autoload :BarrierAroundwareFactory, 'goliath/rack/barrier_aroundware_factory'
     autoload :Builder,                'goliath/rack/builder'
     autoload :DefaultMimeType,        'goliath/rack/default_mime_type'
     autoload :DefaultResponseFormat,  'goliath/rack/default_response_format'
@@ -10,9 +11,13 @@ module Goliath
     autoload :JSONP,                  'goliath/rack/jsonp'
     autoload :Params,                 'goliath/rack/params'
     autoload :Render,                 'goliath/rack/render'
+    autoload :SimpleAroundware,       'goliath/rack/simple_aroundware'
+    autoload :SimpleAroundwareFactory, 'goliath/rack/simple_aroundware_factory'
     autoload :Templates,              'goliath/rack/templates'
     autoload :Tracer,                 'goliath/rack/tracer'
     autoload :Validator,              'goliath/rack/validator'
     autoload :Validation,             'goliath/rack/validation'
+    #
+    autoload :AsyncAroundware,        'goliath/deprecated/async_aroundware'
   end
 end

data/lib/goliath/rack/async_middleware.rb

@@ -21,13 +21,13 @@ module Goliath
     #     include Goliath::Rack::AsyncMiddleware
     #
     #     def call(env)
-    #       awesomness_quotient = 3
+    #       awesomeness_quotient = 3
     #       # the extra args sent to super are passed along to post_process
-    #       super(env, awesomness_quotient)
+    #       super(env, awesomeness_quotient)
     #     end
     #
-    #     def post_process(env, status, headers, body, awesomness_quotient)
-    #       new_body = make_totally_awesome(body, awesomness_quotient)
+    #     def post_process(env, status, headers, body, awesomeness_quotient)
+    #       new_body = make_totally_awesome(body, awesomeness_quotient)
     #       [status, headers, new_body]
     #     end
     #   end
@@ -41,6 +41,8 @@ module Goliath
     #   next request. Everything that you need to store needs to be stored in
     #   local variables.
     module AsyncMiddleware
+      include Goliath::Rack::Validator
+
       # Called by the framework to create the middleware.
       #
       # @param app [Proc] The application
@@ -65,19 +67,38 @@ module Goliath
       # @param env [Goliath::Env] The goliath environment
       # @return [Array] The [status_code, headers, body] tuple
       def call(env, *args)
-        async_cb = env['async.callback']
 
-        env['async.callback'] = Proc.new do |status, headers, body|
-          async_cb.call(post_process(env, status, headers, body, *args))
-        end
+        hook_into_callback_chain(env, *args)
 
-        status, headers, body = @app.call(env)
+        downstream_resp = @app.call(env)
 
-        if status == Goliath::Connection::AsyncResponse.first
-          [status, headers, body]
-        else
+        if final_response?(downstream_resp)
+          status, headers, body = downstream_resp
           post_process(env, status, headers, body, *args)
+        else
+          return Goliath::Connection::AsyncResponse
+        end
+      end
+
+      # Put a callback block in the middle of the async_callback chain:
+      # * save the old callback chain;
+      # * have the downstream callback send results to our proc...
+      # * which fires old callback chain when it completes
+      def hook_into_callback_chain(env, *args)
+        async_callback = env['async.callback']
+
+        # The response from the downstream app is sent to post_process
+        # and then directly up the callback chain
+        downstream_callback = Proc.new do |status, headers, body|
+          new_resp = safely(env){ post_process(env, status, headers, body, *args) }
+          async_callback.call(new_resp)
         end
+
+        env['async.callback'] = downstream_callback
+      end
+
+      def final_response?(resp)
+        resp != Goliath::Connection::AsyncResponse
       end
 
       # Override this method in your middleware to perform any
@@ -88,6 +109,7 @@ module Goliath
       def post_process(env, status, headers, body)
         [status, headers, body]
       end
+
     end
   end
 end

data/lib/goliath/rack/barrier_aroundware.rb

@@ -0,0 +1,228 @@
+module Goliath
+  module Rack
+
+    #
+    # This module gives you ergonomics similar to traditional Rack middleware:
+    #
+    # * Use instance variables! Each SimpleAroundware is unique to its request.
+    # * You have accessors for env and (once in post_process) status, headers,
+    #   body -- no more shipping them around to every method.
+    #
+    # ...along with a new superpower: you can #enqueue requests in #pre_process,
+    # and the barrier will hold off on executing #post_process until both the
+    # downstream and your enqueued requests have completed.
+    #
+    # If in your traditional middleware you'd (with poor concurrency) do this:
+    #
+    #     class MyRackMiddleware
+    #       def call(env)
+    #         user_info = get_user_from_db
+    #         status, headers, body = @app.call(env)
+    #         new_body = put_username_into_sidebar_text(body, user_info)
+    #         [status, headers, new_body]
+    #       end
+    #     end
+    #
+    # You can now do this:
+    #
+    #     class MyAwesomeAroundware
+    #       include Goliath::Rack::BarrierAroundware
+    #       attr_accessor :user_info
+    #       def pre_process
+    #         enqueue :user_info, async_get_user_from_db
+    #       end
+    #       # !concurrency!
+    #       def post_process
+    #         new_body = put_username_into_sidebar_text(body, user_info)
+    #         [status, headers, new_body]
+    #       end
+    #     end
+    #
+    # Which you'd include in your endpoint like this:
+    #
+    #     class AwesomeApi < Goliath::API
+    #       use Goliath::Rack::BarrierAroundwareFactory, MyAwesomeAroundware
+    #     end
+    #
+    # The user record was retrieved from the db while other processing happened;
+    # once the async request named :user_info returned, goliath noticed that you
+    # had a #user_info= setter and so it set the variable appropriately. (It's
+    # also put in the #successes (or #failures) hash).
+    #
+    # You can also enqueue a non-EM::Deferrable request. #enqueue_acceptor gives
+    # you a dummy deferrable; send the response to its succeed method:
+    #
+    #     # a database lookup that takes a block
+    #     enqueue_acceptor(:bob) do |acc|
+    #       db.collection(:users).afind(:username => :bob) do |resp|
+    #         acc.succeed(resp.first)
+    #       end
+    #     end
+    #
+    # You're free to invoke the barrier whenever you like. Consider a bouncer
+    # who is polite to townies (he lets them order from the bar while he checks
+    # their ID) but a jerk to college kids (who have to wait in line before they
+    # can order):
+    #
+    #     class AuthAroundware
+    #       include Goliath::Rack::BarrierAroundware
+    #       attr_accessor :user_info
+    #       def pre_process
+    #         enqueue :user_info, async_get_user_from_db
+    #         unless lazy_authorization?
+    #           perform               # yield execution until user_info has arrived
+    #           check_authorization!  # then check the info *before* continuing
+    #         end
+    #       end
+    #       #
+    #       def post_process
+    #         check_authorization! if lazy_authorization?
+    #         [status, headers, new_body]
+    #       end
+    #       def lazy_authorization?
+    #         (env['REQUEST_METHOD'] == 'GET') || (env['REQUEST_METHOD'] == 'HEAD')
+    #       end
+    #     end
+    #     class AwesomeApi < Goliath::API
+    #       use Goliath::Rack::BarrierAroundwareFactory, AuthAroundware
+    #     end
+    #
+    # The `perform` statement puts up a barrier until all pending requests (in
+    # this case, :user_info) complete. The downstream request isn't enqueued
+    # until pre_process completes, so in the non-`GET` branch the AuthAroundware
+    # is able to verify the user *before* allowing execution to proceed. If the
+    # request is a harmless `GET`, though, both the user_info and downstream
+    # requests can proceed concurrently, and we instead `check_authorization!`
+    # in the post_process block.
+    #
+    # @example
+    #     class ShortenUrl
+    #       attr_accessor :shortened_url
+    #       include Goliath::Rack::BarrierAroundware
+    #
+    #       def pre_process
+    #         target_url        = PostRank::URI.clean(env.params['url'])
+    #         shortener_request = EM::HttpRequest.new('http://is.gd/create.php').aget(:query => { :format => 'simple', :url => target_url })
+    #         enqueue :shortened_url, shortener_request
+    #         Goliath::Connection::AsyncResponse
+    #       end
+    #
+    #       # by the time you get here, the AroundwareFactory will have populated
+    #       # the [status, headers, body] and the shortener_request will have
+    #       # populated the shortened_url attribute.
+    #       def post_process
+    #         if succeeded?(:shortened_url)
+    #           headers['X-Shortened-URI'] = shortened_url
+    #         end
+    #         [status, headers, body]
+    #       end
+    #     end
+    #
+    #     class AwesomeApiWithShortening < Goliath::API
+    #       use Goliath::Rack::Params
+    #       use Goliath::Rack::BarrierAroundwareFactory, ShortenUrl
+    #       def response(env)
+    #         # ... do something awesome
+    #       end
+    #     end
+    #
+    module BarrierAroundware
+      include EventMachine::Deferrable
+      include Goliath::Rack::SimpleAroundware
+
+      # Pool with handles of pending requests
+      attr_reader :pending_requests
+      # Pool with handles of sucessful requests
+      attr_reader :successes
+      # Pool with handles of failed requests
+      attr_reader :failures
+
+      # @param env [Goliath::Env] The request environment
+      # @return [Goliath::Rack::BarrierAroundware]
+      def initialize(env)
+        @env = env
+        @pending_requests = Set.new
+        @successes        = {}
+        @failures         = {}
+      end
+
+      # On receipt of an async result,
+      # * remove the tracking handle from pending_requests
+      # * and file the response in either successes or failures as appropriate
+      # * call the setter for that handle if any (on receipt of :shortened_url,
+      #   calls self.shortened_url = resp)
+      # * check progress -- succeeds (transferring controll) if nothing is pending.
+      def accept_response(handle, resp_succ, resp, req=nil, fiber=nil)
+        raise "received response for a non-pending request!" if not pending_requests.include?(handle)
+        pending_requests.delete(handle)
+        resp_succ ? (successes[handle] = [req, resp]) : (failures[handle] = [req, resp])
+        self.send("#{handle}=", resp) if self.respond_to?("#{handle}=")
+        check_progress(fiber)
+        resp
+      end
+
+      # Add a deferred request to the pending pool, and set a callback to
+      # #accept_response when the request completes
+      def enqueue(handle, deferred_req)
+        fiber = Fiber.current
+        add_to_pending(handle)
+        deferred_req.callback{|resp| safely(env){ accept_response(handle, true,  resp, deferred_req, fiber) } }
+        deferred_req.errback{|resp|  safely(env){ accept_response(handle, false, resp, deferred_req, fiber) } }
+      end
+
+      # Do you have a method that uses a block, not a deferrable?  This method
+      # gives you a deferrable 'acceptor' and enqueues it -- simply call
+      # #succeed (or #fail) on the acceptor from within the block, passing it
+      # your desired response.
+      #
+      # @example
+      #     # sleep for 1.0 seconds and then complete
+      #     enqueue_acceptor(:sleepy)do |acc|
+      #       EM.add_timer(1.0){ acc.succeed }
+      #     end
+      #
+      # @example
+      #     # a database lookup that takes a block
+      #     enqueue_acceptor(:bob) do |acc|
+      #       db.collection(:users).afind(:username => :bob) do |resp|
+      #         acc.succeed(resp.first)
+      #       end
+      #     end
+      #
+      def enqueue_acceptor(handle)
+        acceptor = EM::DefaultDeferrable.new
+        yield(acceptor)
+        enqueue handle, acceptor
+      end
+
+      # Register a pending request. If you call this from outside #enqueue, you
+      # must construct callbacks that eventually invoke accept_response
+      def add_to_pending(handle)
+        set_deferred_status(nil) # we're not done yet, even if we were
+        @pending_requests << handle
+      end
+
+      def finished?
+        pending_requests.empty?
+      end
+
+      # Perform will yield (allowing other processes to continue) until all
+      # pending responses complete.  You're free to enqueue responses, call
+      # perform,
+      def perform
+        Fiber.yield unless finished?
+      end
+
+    protected
+
+      def check_progress(fiber)
+        if finished?
+          succeed
+          # continue processing
+          fiber.resume(self) if fiber && fiber.alive? && fiber != Fiber.current
+        end
+      end
+
+    end
+  end
+end