rack-timeout 0.1.0beta2 → 0.1.0beta3

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZGY0YjFmYWYzMTAzY2E4NWUzMWQyM2ZlN2YwY2E2Yzk0ZGVkZGRlNA==
-  data.tar.gz: !binary |-
-    MjE3NDM5ZTdlMWU4NTQ0OGEzNGYyYzU2MTc4MjczNTNhZDhhYWE0Mw==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    YTVlYTViYjc0ZDdlYzBiYjNhYzJiOTc4ZTQ4OTVlYjNkOWM5MTFmMmRmNzIw
-    MTM0OWI3ZWVmODRiY2M3ZDAwMGY3OGViNmJkMTZiYzlkYzI0ZTJhYThhYTEy
-    MWJlNTUzZTZjYzc2Y2ViMThlMjJlMDdiMTM5Mzg0MzNjMzM0ZTc=
-  data.tar.gz: !binary |-
-    ZTc3Yzk3MmE4YWE0NjQwNjliNjNmZmY1Zjc0ZTdjODYwYThhYmJjNjI0NTRh
-    ZTk5ZGU0YjE1YmQ3ZWY0YTg4N2I1MWUwOGExYTk4M2Q1ZGI0NWRmM2YxMjAw
-    MjFiMzJlOTQ0NjVkYWZmMWRhYzMzN2UwOGRmYjkwZDc0MTc0MjA=
+SHA1:
+  metadata.gz: d8cadc6366c07e2e809ab55bbcbc66ea82e387cd
+  data.tar.gz: 600c25828d8e91b1556cd4b458833e109c02788d
+SHA512:
+  metadata.gz: a4f2117b12ddac87a0398622924219d12eaf84ec11fbcbb55e31f8fa9163eb579a1cb4c7a61d6ec3c0011de3699cf83a1688c80d40de173d1235294fa4b83184
+  data.tar.gz: b54a7b0085fbefa6ecad6e2438b7ec6c99ba3c907a806ef34b8b6e2238b442dd9050e92a47aa9e738138467c081f0965419f085950570d6316bd8fa3d6aa4959

data/README.markdown

@@ -1,14 +1,20 @@
+README is not entirely in sync with this release. E.g. the overtime stuff is not present in this
+release. There may be other discrepancies.
+
 Rack::Timeout
 =============
 
-Abort requests that are taking too long; a `Rack::Timeout::Error` will be raised.
+Abort requests that are taking too long; a subclass of `Rack::Timeout::Error` is raised.
+
+A generous timeout of 15s is the default. It's recommended to set the timeout as low as
+realistically viable for your application.
 
 
 Usage
 -----
 
-Setup for current versions of Rails, Rack, Ruby, and Bundler. See the Compatibility section at the
-end for legacy versions.
+The following covers currently supported versions of Rails, Rack, Ruby, and Bundler. See the
+Compatibility section at the end for legacy versions.
 
 ### Rails apps
 
@@ -33,27 +39,42 @@ Heroku Niceties
 ---------------
 
 *   Normally, Rack::Timeout always times out a request using the `Rack::Timeout.timeout` setting.
-    Heroku offers the [`X-Request-Start`][X-Request-Start] HTTP header, which is a timestamp
-    indicating the time the request first enters the routing infrastructure.
+    Heroku makes available the [`X-Request-Start`][X-Request-Start] HTTP header, which is a
+    timestamp indicating the time the request first enters the routing infrastructure.
 
     If the `X-Request-Start` HTTP header is present, Rack::Timeout will take the age of the request
     into consideration when determining the timeout to use. If a request is older than 30 seconds,
-    it's dropped immediately. Otherwise, the timeout is the number of seconds left to 30 seconds,
-    or the value of `Rack::Timeout.timeout`, whichever is shorter.
+    it's dropped immediately. Otherwise, the timeout is the number of seconds left for the request
+    to be 30 seconds old, or the value of `Rack::Timeout.timeout`, whichever is shorter.
 
     So, if a request has been sitting in the queue for 25s, and `Rack::Timeout.timeout` is set to
     10s, the timeout used will be 5s, because `30 − 25 = 5`, and `5 < 10`.
 
-    The reasoning for this behavior is that the Heroku router drops requests if no response is
-    received within 30s, so it makes no sense for the application to process a request it'll never
-    be able to respond to.
+    The reasoning for this behavior is that the Heroku router drops requests if no data is
+    transferred within 30s, so it makes no sense for the application to process a request it'll
+    never be able to respond to. (This is actually [a bit more involved][heroku-routing].)
 
-    The 30s maximum age is set in in `Rack::Timeout::MAX_REQUEST_AGE`, and should generally not be
+    The 30s maximum age is set in `Rack::Timeout::MAX_REQUEST_AGE`, and should generally not be
     altered.
 
-*   With every line logged, Rack::Timeout includes a request ID. Generally it'll generate its own
-    ID, but before that, it'll look for the `Heroku-Request-ID` header. If present, this is the ID
-    that'll get logged.
+    An exception to this is made for requests that have a non-empty body, e.g. POST, PUT, and PATCH
+    requests. X-Request-Start is set when the Heroku router begins receiving the request, but rack
+    will generally only see the request after it's been fully received by the application server
+    (i.e. thin, unicorn, etc). For short requests such as GET requests, this is irrelevant. But
+    with a slow client (say, a mobile app performing a file upload) the request can take a long
+    time to be fully received. A request that took longer than 30s to transmit would be dropped
+    immediately by Rack::Timeout because it'd be considered too old. The Heroku router, however,
+    would not have dropped this request because it would have been transmitting data all along.
+
+    For requests with a body, Rack::Timeout provides additional overtime before expiring them. The
+    default overtime is 60s, on top of the 30s `MAX_REQUEST_AGE`. This is user-configurable with
+    the `Rack::Timeout.overtime` setting:
+
+        Rack::Timeout.overtime = 10 # seconds over MAX_REQUEST_AGE
+
+*   With every line logged, Rack::Timeout includes a request ID. It'll first look for an ID in the
+    `Heroku-Request-ID` header; if not present, it'll then check `X-Request-ID`; and lastly, it'll
+    generate its own.
 
     `Heroku-Request-ID` is not present by default on Heroku apps, but can be enabled through the
     [http-request-id labs feature][http-request-id]. It's recommended to enable http-request-id as
@@ -61,6 +82,7 @@ Heroku Niceties
     downsides to enabling http-request-id.
 
 [X-Request-Start]: https://devcenter.heroku.com/articles/http-routing#heroku-headers
+[heroku-routing]:  https://devcenter.heroku.com/articles/http-routing#timeouts
 [http-request-id]: https://devcenter.heroku.com/articles/http-request-id
 
 Both these features are strictly reliant on the presence of the HTTP headers and make no effort to
@@ -76,30 +98,42 @@ Throughout a request's lifetime, Rack::Timeout keeps details about the request i
 The value of that entry is an instance of `Rack::Timeout::RequestDetails`, which is a `Struct`
 containing the following fields:
 
-*   `id`: a unique ID per request. Either `Heroku-Request-ID` or a random ID generated internally.
+*   `id`: a unique ID per request. Either `Heroku-Request-ID`, `X-Request-ID`, or a random ID
+    generated internally.
 
 *   `age`: time in seconds since `X-Request-Start` when the request is first seen by Rack::Timeout.
     Only set if `X-Request-Start` is present.
 
 *   `timeout`: timeout to be used, in seconds. Generally `Rack::Timeout.timeout`, unless
-    `X-Request-Start` is present. See discussion above under the Heroku Niceties section.
+    `X-Request-Start` is present. See discussion above, under the Heroku Niceties section.
 
-*   `duration`: set after a request completes (or times out). The time in seconds it took.
+*   `duration`: set after a request completes (or times out). The time in seconds it took. This is
+    also updated while a request is still active, around every second, with the time it's taken so
+    far.
 
 *   `state`: the possible states are:
 
     *   `expired`: the request is considered too old and is skipped entirely. This happens when
         `X-Request-Start` is present and older than 30s. When this happens, a
-        `Rack::Timeout::RequestExpiryError` exception is raised.
+        `Rack::Timeout::RequestExpiryError` exception is raised. See earlier discussion about the
+        `Rack::Timeout.overtime` setting, too.
 
     *   `ready`: this is the initial state a request is in, before it's passed down the middleware
-        chain. After that, it'll either end up as `timed_out` or `completed`.
+        chain. While it's being processed, it'll move on to `active`, and then on to `timed_out`
+        and/or `completed`.
+
+    *   `active`: the request is being actively processed in the application thread. This is
+        signaled repeatedly every ~1s until the request completes or times out.
 
     *   `timed_out`: the request had run for longer than the determined timeout and was aborted. A
         `Rack::Timeout::RequestTimeoutError` error is raised in the application when this occurs.
+        If this error gets caught and handled and not re-raised in the app or framework (which will
+        generally happen with Rails and Sinatra), this state will not be final, `completed` will be
+        set after the framework is done with it.
 
     *   `completed`: the request completed in time and Rack::Timeout is done with it. This does not
         mean the request completed *successfully*. Rack::Timeout does not concern itself with that.
+        As mentioned just above, a timed out request may still end up with a `completed` state.
 
 
 Errors
@@ -109,20 +143,31 @@ Rack::Timeout can raise two types of exceptions. Both descend from `Rack::Timeou
 itself descends from `RuntimeError`. They are:
 
 *   `Rack::Timeout::RequestTimeoutError`: this is raised when a request has run for longer than the
-    specified timeout. This is raised in the application thread, as per the `::Timeout.timeout`
-    semantics, and can generally be caught within the application.
+    specified timeout. This is raised by the rack-timeout timer thread in the application thread,
+    at the point in the stack the app happens to be in when the timeout is triggered. This
+    exception can generally be caught within the application, but in doing so you're working past
+    the timeout. This is ok for quick cleanups but shouldn't be abused as Rack::Timeout will not
+    kick in twice for the same request.
 
 *   `Rack::Timeout::RequestExpiryError`: this is raised when a request is skipped for being too old
     (see the X-Request-Start bit under the Heroku Niceties section). This cannot generally be
-    rescued from in a Rails controller action as it happens before the request has a chance to reach
-    Rails.
+    rescued from inside a Rails controller action as it happens before the request has a chance to
+    reach Rails.
 
     This shouldn't be any different for other frameworks, unless you have something above
     Rack::Timeout in the middleware stack, which you generally shouldn't.
 
-You shouldn't generally care about rescuing from these errors. Instead, you can subscribe for state
+You shouldn't rescue from these errors for reporting purposes. Instead, you can subscribe for state
 change notifications with observers.
 
+If you're trying to test that a `Rack::Timeout::RequestTimeoutError` is raised in an action in your
+Rails application, you **must do so in integration tests**. Please note that Rack::Timeout will not
+kick in for functional tests as they bypass the rack middleware stack.
+
+[More details about testing middleware with Rails here][pablobm].
+
+[pablobm]: http://stackoverflow.com/a/8681208/13989
+
 
 Observers
 ---------
@@ -158,7 +203,10 @@ Logging
 
 Rack::Timeout logs a line every time there's a change in state in a request's lifetime.
 
-Changes into `timed_out` and `expired` are logged at the `ERROR` level, everything else is `INFO`.
+Changes into `timed_out` and `expired` are logged at the `ERROR` level, most other things are
+logged as `INFO`.
+
+Exceptionally, `active` state is logged as `DEBUG`, every ~1s while the request is still active.
 
 The default log level for Rack::Timeout is `INFO`, but can be affected via:
 
@@ -200,24 +248,6 @@ For applications running Ruby 1.8.x and/or Rails 2.x, use [version 0.0.4][v0.0.4
 [v0.0.4]: https://github.com/kch/rack-timeout/tree/v0.0.4
 
 
-Here Be Dragons
----------------
-
-*   Ruby's Timeout rely on threads. If your app or any of the libraries it depends on is not
-    thread-safe, you may run into issues using Rack::Timeout.
-
-    Concurrent web servers such as [Unicorn][] and [Puma][] should work fine with Rack::Timeout.
-
-*   If you're trying to test that a `Rack::Timeout::Error` is raised in an action in your Rails
-    application, you **must do so in integration tests**. Please note that Rack::Timeout will not
-    kick in for functional tests as they bypass the rack middleware stack.
-
-    [More details about testing middleware with Rails here][pablobm].
-
-[Unicorn]: http://unicorn.bogomips.org/
-[Puma]:    http://puma.io/
-[pablobm]: http://stackoverflow.com/a/8681208/13989
-
 ---
 Copyright © 2010-2013 Caio Chassot, released under the MIT license  
 <http://github.com/kch/rack-timeout>

data/lib/rack-timeout.rb

@@ -5,7 +5,6 @@ require 'rack/timeout/logger'
 if defined?(Rails) && [3,4].include?(Rails::VERSION::MAJOR)
   class Rack::Timeout::Railtie < Rails::Railtie
     initializer('rack-timeout.prepend') { |app| app.config.middleware.insert 0, Rack::Timeout }
-    initializer('rack-timeout.tracker') { |app| app.config.middleware.use Rack::Timeout::TimeoutTracker }
   end
 end
 

data/lib/rack/timeout.rb

@@ -1,5 +1,4 @@
 # encoding: utf-8
-require 'timeout'
 require 'securerandom'
 
 module Rack
@@ -8,14 +7,11 @@ module Rack
     class RequestExpiryError  < Error; end
     class RequestTimeoutError < Error; end
 
-    RequestDetails       = Struct.new(:id, :age, :timeout, :duration, :state)
-    ENV_INFO_KEY         = 'rack-timeout.info'
-    FRAMEWORK_ERROR_KEYS = %w(sinatra.error rack.exception) # No idea what actually sets rack.exception but a lot of other libraries seem to reference it.
-    FINAL_STATES         = [:expired, :timed_out, :completed]
-    ACCEPTABLE_STATES    = [:ready] + FINAL_STATES
-    MAX_REQUEST_AGE      = 30 # seconds
-
-    @timeout = 15
+    RequestDetails  = Struct.new(:id, :age, :timeout, :duration, :state)
+    ENV_INFO_KEY    = 'rack-timeout.info'
+    VALID_STATES    = [:ready, :active, :expired, :timed_out, :completed]
+    MAX_REQUEST_AGE = 30 # seconds
+    @timeout        = 15 # seconds
     class << self
       attr_accessor :timeout
     end
@@ -26,61 +22,53 @@ module Rack
 
     def call(env)
       info          = env[ENV_INFO_KEY] ||= RequestDetails.new
-      info.id     ||= env['HTTP_HEROKU_REQUEST_ID'] || SecureRandom.hex
+      info.id     ||= env['HTTP_HEROKU_REQUEST_ID'] || env['HTTP_X_REQUEST_ID'] || SecureRandom.hex
       request_start = env['HTTP_X_REQUEST_START'] # unix timestamp in ms
-      request_start = Time.at(request_start.to_i / 1000) if request_start
+      request_start = Time.at(request_start.to_f / 1000) if request_start
       info.age      = Time.now - request_start           if request_start
       time_left     = MAX_REQUEST_AGE - info.age         if info.age
       info.timeout  = [self.class.timeout, time_left].compact.select { |n| n >= 0 }.min
 
       if time_left && time_left <= 0
         Rack::Timeout._set_state! env, :expired
-        raise RequestExpiryError
+        raise RequestExpiryError, "Request older than #{MAX_REQUEST_AGE} seconds."
       end
 
       Rack::Timeout._set_state! env, :ready
-      ::Timeout.timeout(info.timeout, RequestTimeoutError) do
-        ready_time    = Time.now
-        response      = Rack::Timeout._perform_block_tracking_timeout_to_env(env) { @app.call(env) }
-        info.duration = Time.now - ready_time
-        Rack::Timeout._set_state! env, :completed
-        response
+      ready_time = Time.now
+
+      begin
+        app_thread     = Thread.current
+        timeout_thread = Thread.start do
+          loop do
+            info.duration = Time.now - ready_time
+            sleep_seconds = [1, info.timeout - info.duration].min
+            break if sleep_seconds <= 0
+            Rack::Timeout._set_state! env, :active
+            sleep(sleep_seconds)
+          end
+          Rack::Timeout._set_state! env, :timed_out
+          app_thread.raise(RequestTimeoutError, "Request ran for longer than #{info.timeout} seconds.")
+        end
+        response = @app.call(env)
+      ensure
+        timeout_thread.kill
+        timeout_thread.join
       end
-    end
 
-    # used in #call and TimeoutTracker
-    def self._perform_block_tracking_timeout_to_env(env)
-      yield
-    rescue RequestTimeoutError
-      timed_out = true
-      raise
-    ensure
-      # I do not appreciate having to handle framework business in a rack-level library, but can't see another way around sinatra's error handling.
-      timed_out ||= env.values_at(*FRAMEWORK_ERROR_KEYS).any? { |e| e.is_a? RequestTimeoutError }
-      _set_state! env, :timed_out if timed_out
+      info.duration = Time.now - ready_time
+      Rack::Timeout._set_state! env, :completed
+      response
     end
 
     # used internally
     def self._set_state!(env, state)
-      raise "Invalid state: #{state.inspect}" unless ACCEPTABLE_STATES.include? state
+      raise "Invalid state: #{state.inspect}" unless VALID_STATES.include? state
       info = env[ENV_INFO_KEY]
-      return if FINAL_STATES.include? info.state
       info.state = state
       notify_state_change_observers(env)
     end
 
-    # A second middleware to be added last in rails; ensures timed_out states get intercepted properly.
-    # This works as long as it's after ActionDispatch::ShowExceptions and ActionDispatch::DebugExceptions in the middleware list, which happens normally when added via `app.config.middleware.use`.
-    class TimeoutTracker
-      def initialize(app)
-        @app = app
-      end
-
-      def call(env)
-        Rack::Timeout._perform_block_tracking_timeout_to_env(env) { @app.call(env) }
-      end
-    end
-
 
     ### state change notification-related methods
 

data/lib/rack/timeout/logger.rb

@@ -12,6 +12,7 @@ module Rack
       SIMPLE_FORMATTER = ->(severity, timestamp, progname, msg) { "#{msg} at=#{severity.downcase}\n" }
       DEFAULT_LEVEL    = INFO
       STATE_LOG_LEVEL  = { ready:     INFO,
+                           active:    DEBUG,
                            completed: INFO,
                            expired:   ERROR,
                            timed_out: ERROR,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-timeout
 version: !ruby/object:Gem::Version
-  version: 0.1.0beta2
+  version: 0.1.0beta3
 platform: ruby
 authors:
 - Caio Chassot
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-08 00:00:00.000000000 Z
+date: 2013-07-01 00:00:00.000000000 Z
 dependencies: []
 description: Rack middleware which aborts requests that have been running for longer
   than a specified timeout.
@@ -32,12 +32,12 @@ 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: 1.3.1
 requirements: []