goliath-rack_proxy 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ca389756f31e83a5660faf6628a02cdc94c42431
-  data.tar.gz: 2b5c39cba40a5a989870b8e2acc2548b3e7c6bdc
+  metadata.gz: ab4ba13cd9def1d20578a29ffefabf79080598ff
+  data.tar.gz: 6ace1d22f5aba4ecd862dfa72ec959dd378b2cd4
 SHA512:
-  metadata.gz: 51840456dab796caa37a5390b58e85cf5b5a4be37c40cae3caaa094aae32a2c9514046425f27400654c2933af01fd532784873259432bb11888ec413bd732c67
-  data.tar.gz: 8c2fac7e1676038be1da9b58e38f5f27da879341324a6b5c810949ac8d18729d9c9f293b84cdba033b5ad61f472820fa3947c87bda1993372d91f0b552a170b9
+  metadata.gz: 0bacf146eea719d6e0e124cd99e1e1194a86d7d79a1d7931035c78bebcfca8e2a85be2a9693e51b0b304440c34d4eb90ecb5d4d26954569ece2719c5af2d2cec
+  data.tar.gz: 8e22fc46cf8edab53d430b017e8b6f3421ec7530a88d9963a83c5485f8e168cb9ee24102e3543707e655ce51128df65e1823dca39b74abfc0c8d2ce50bfa90a7

data/README.md

@@ -9,21 +9,27 @@ uploads and large downloads, I wanted to find an appropriate web server to
 recommend. I needed a web server that supports **streaming uploads**, allowing
 the Rack application to start processing the request while the request body is
 still being received, and that way giving it the ability to save whatever data
-it received before possible request interruptions. I also needed support for
-**streaming downloads**, sending response body in chunks back to the client.
+it received before possible potential request interruption. I also needed
+support for **streaming downloads**, sending response body in chunks back to
+the client.
 
 The only web server I found that supported all of this was [Unicorn]. However,
 Unicorn needs to spawn a whole process for serving each concurrent request,
-which isn't the most efficent use of server resources.
-
-Then I found [Goliath], which I found to provide the most flexibility in
-handling requests. It's built on top of [EventMachine], so it uses threads for
-serving requests, but it can also be run in hybrid mode. However, Goliath is
-more meant to be used standalone than in tandem with another Rack app.
-
-So I created a `Goliath::API` subclass that proxies incoming requests to the
-specified Rack app in a streaming fashion, making it act like a web server for
-the app.
+which isn't the most efficent use of server resources. It's also difficult to
+estimate how many workers you need, because once you disable request buffering
+in the application server, you become vulnerable to slow clients.
+
+Then I came across [Goliath], which gave me the control I needed for handling
+requests. It's built on top of [EventMachine], which uses the reactor pattern
+to schedule work efficiently. The most important feature is that long-running
+requests won't impact request throughput, as there are no web workers that are
+waiting for incoming data.
+
+However, Goliath itself is designed to be used standalone, not in tandem with
+another Rack app. So I created `Goliath::RackProxy`, which is a `Goliath::API`
+subclass that proxies incoming/outgoing requests/responses to/from the
+specified Rack app in a streaming fashion, essentially making it act like a web
+server for the Rack app.
 
 ## Installation
 
@@ -75,20 +81,6 @@ class MyGoliathApp < Goliath::RackProxy
 end
 ```
 
-If you want to report any exceptions that might occur with the Rack app, you can
-override `Goliath::RackProxy#log_exception`:
-
-```rb
-class MyGoliathApp < Goliath::RackProxy
-  rack_app MyRackApp
-
-  def log_exception(exception, env)
-    super
-    Airbrake.notify(exception)
-  end
-end
-```
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/goliath-rack_proxy.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name         = "goliath-rack_proxy"
-  gem.version      = "1.0.0"
+  gem.version      = "1.0.1"
 
   gem.required_ruby_version = ">= 2.1"
 

data/lib/goliath/rack_proxy.rb

@@ -11,7 +11,7 @@ module Goliath
       rack_proxy_options[:rack_app] = app
     end
 
-    # Whether the input should be rewindable, i.e. cached onto disk.
+    # Whether the request body should be rewindable.
     def self.rewindable_input(value)
       rack_proxy_options[:rewindable_input] = value
     end
@@ -21,7 +21,7 @@ module Goliath
       @rack_proxy_options ||= {}
     end
 
-    # Called when request headers were parsed.
+    # Starts the request to the given Rack application.
     def on_headers(env, headers)
       rack_app         = self.class.rack_proxy_options.fetch(:rack_app)
       rewindable_input = self.class.rack_proxy_options.fetch(:rewindable_input, true)
@@ -30,31 +30,48 @@ module Goliath
       env["rack_proxy.call"].resume
     end
 
-    # Called on each request body chunk received from the client.
+    # Resumes the Rack request with the received request body data.
     def on_body(env, data)
-      # write data to the input, which will be read by the Rack app
       env["rack_proxy.call"].resume(data)
     end
 
-    # Called at the end of the request (after #response) or on client disconnect.
+    # Resumes the Rack request with no more data.
     def on_close(env)
-      # reading the request body has finished, so we close write end of the input
       env["rack_proxy.call"].resume
     end
 
-    # Called after all the data has been received from the client.
+    # Resumes the Rack request with no more data.
     def response(env)
       env["rack_proxy.call"].resume
     end
 
     private
 
+    # Allows "curry-calling" the Rack application, resuming the call as we're
+    # receiving more request body data.
     class RackCall
       def initialize(app, env, rewindable_input: true)
-        @fiber = Fiber.new do
-          rack_input = RackInput.new(rewindable: rewindable_input) { Fiber.yield }
+        @app              = app
+        @env              = env
+        @rewindable_input = rewindable_input
+      end
+
+      def resume(data = nil)
+        @result = fiber.resume(data) if fiber.alive?
+        @result
+      end
+
+      private
+
+      # Calls the Rack application inside a Fiber, using the RackInput object as
+      # the request body. When the Rack application wants to read request body
+      # data that hasn't been received yet, the execution is automatically
+      # paused so that the event loop can go on.
+      def fiber
+        @fiber ||= Fiber.new do
+          rack_input = RackInput.new(rewindable: @rewindable_input) { Fiber.yield }
 
-          result = app.call env.merge(
+          result = @app.call @env.merge(
             "rack.input"     => rack_input,
             "async.callback" => nil, # prevent Roda/Sinatra from calling EventMachine while streaming the response
           )
@@ -64,25 +81,23 @@ module Goliath
           result
         end
       end
-
-      def resume(data = nil)
-        @result = @fiber.resume(data) if @fiber.alive?
-        @result
-      end
     end
 
-    # IO-like object that acts as a bidirectional pipe, which returns the data
-    # that has been written to it.
+    # IO-like object that conforms to the Rack specification for the request
+    # body ("rack input"). It takes a block which produces chunks of data, and
+    # makes this data retrievable through the IO#read interface. When rewindable
+    # caches the retrieved content onto disk.
     class RackInput
       def initialize(rewindable: true, &next_chunk)
         @next_chunk = next_chunk
-        @cache      = Tempfile.new("goliath-rack_input") if rewindable
+        @cache      = Tempfile.new("goliath-rack_input", binmode: true) if rewindable
         @buffer     = nil
         @eof        = false
       end
 
-      # Pops chunks of data from the queue and implements
-      # `IO#read(length = nil, outbuf = nil)` semantics.
+      # Retrieves data using the IO#read semantics. If rack input is declared
+      # rewindable, writes retrieved content into a Tempfile object so that
+      # it can later be re-read.
       def read(length = nil, outbuf = nil)
         data = outbuf.clear if outbuf
         data = @cache.read(length, outbuf) if @cache && !@cache.eof?
@@ -118,15 +133,15 @@ module Goliath
         data.to_s unless length && (data.nil? || data.empty?)
       end
 
-      # Rewinds the cache IO if it's configured, otherwise raises Errno::ESPIPE
-      # exception, which mimics the behaviour of caling #rewind on
-      # non-rewindable IOs such as pipes, sockets, and ttys.
+      # Rewinds the tempfile if rewindable. Otherwise raises Errno::ESPIPE
+      # exception, which is what other non-rewindable Ruby IO objects raise.
       def rewind
-        raise Errno::ESPIPE if @cache.nil? # raised by other non-rewindable IOs
+        raise Errno::ESPIPE if @cache.nil?
         @cache.rewind
       end
 
-      # Conforming to the Rack specification.
+      # Deletes the tempfile. The #close method is also part of the Rack
+      # specification.
       def close
         @cache.close! if @cache
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: goliath-rack_proxy
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-15 00:00:00.000000000 Z
+date: 2018-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: goliath