rack-timeout 0.5.0.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c00ec7f108e18dc2e47ccc177092f7465de8078c97da84d3ab1d968bef2243b7
-  data.tar.gz: 67740a7b4081ec5ed229b68ff677051e4ae293667ca89d2a84a31f36bdefd51b
+  metadata.gz: 642f765e106069393a85355bb1b205479b125e9e4fb639c4b8b7f8309b5563ea
+  data.tar.gz: 0d8dc45b11b4561760d7163526b9926f8c566ed8c29ff83f7665cc890360da9e
 SHA512:
-  metadata.gz: c895a313d1426ae878cf38dd16edf60e4480eeca47790fe5c8385875ce22ec439e9ba640c9687596a9dc440d6242e880c28c5677ae9aeecb5a40d896eff2ebe6
-  data.tar.gz: 5ad082993cdfbee11f8ac4bd4482027f021ebe47a272be1b2a86e2ef67c651e0f82417dae369002e4702a50f4a15f5703703af5d19ca4259a3e1afd26fc024ec
+  metadata.gz: 33ee501f48e9ab8a7399fca2ec9c2ec1c3c26b10e6352b4371e4ca4b01706186457146556dbdcf38e82483e4348eb8815bd77dd15ea7e350e473e56c6f784249
+  data.tar.gz: eaf9a7f04e9b2f1b3404d4fcf2a8f88d368cc0ed4e24b1c9df3cedd032ca41e63879c3064c02652e718fd0a6693756a2b303e832a4f1ffa03b595bfcc168c555

data/doc/exceptions.md

@@ -0,0 +1,24 @@
+Exceptions
+----------
+
+Rack::Timeout can raise three types of exceptions. They are:
+
+Two descend from `Rack::Timeout::Error`, which itself descends from `RuntimeError` and is generally caught by an unqualified `rescue`. The third, `RequestTimeoutException`, is more complicated and the most important.
+
+*   `Rack::Timeout::RequestTimeoutException`: this is raised when a request has run for longer than the specified timeout. This descends from `Exception`, not from `Rack::Timeout::Error` (it has to be rescued from explicitly). It's 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 could be caught explicitly within the application, but in doing so you're working past the timeout. This is ok for quick cleanup work but shouldn't be abused as Rack::Timeout will not kick in twice for the same request.
+
+    Rails will generally intercept `Exception`s, but in plain Rack apps, this exception will be caught by rack-timeout and re-raised as a `Rack::Timeout::RequestTimeoutError`. This is to prevent an `Exception` from bubbling up beyond rack-timeout and to the server.
+
+*   `Rack::Timeout::RequestTimeoutError` descends from `Rack::Timeout::Error`, but it's only really seen in the case described above. It'll not be seen in a standard Rails app, and will only be seen in Sinatra if rescuing from exceptions is disabled.
+
+*   `Rack::Timeout::RequestExpiryError`: this is raised when a request is skipped for being too old (see Wait Timeout section). This error cannot generally be rescued from inside a Rails controller action as it happens before the request has a chance to enter Rails.
+
+    This shouldn't be different for other frameworks, unless you have something above Rack::Timeout in the middleware stack, which you generally shouldn't.
+
+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::RequestTimeoutException` 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

data/doc/logging.md

@@ -0,0 +1,41 @@
+Logging
+-------
+
+Rack::Timeout logs a line every time there's a change in state in a request's lifetime.
+
+Request state changes into `timed_out` and `expired` are logged at the `ERROR` level, most other things are logged as `INFO`. The `active` state is logged as `DEBUG`, every ~1s while the request is still active.
+
+Rack::Timeout will try to use `Rails.logger` if present, otherwise it'll look for a logger in `env['rack.logger']`, and if neither are present, it'll create its own logger, either writing to `env['rack.errors']`, or to `$stderr` if the former is not set.
+
+When creating its own logger, rack-timeout will use a log level of `INFO`. Otherwise whatever log level is already set on the logger being used continues in effect.
+
+A custom logger can be set via `Rack::Timeout::Logger.logger`. This takes priority over the automatic logger detection:
+
+```ruby
+Rack::Timeout::Logger.logger = Logger.new
+```
+
+There are helper setters that replace the logger:
+
+```ruby
+Rack::Timeout::Logger.device = $stderr
+Rack::Timeout::Logger.level  = Logger::INFO
+```
+
+Although each call replaces the logger, these can be use together and the final logger will retain both properties. (If only one is called, the defaults used above apply.)
+
+Logging is enabled by default, but can be removed with:
+
+```ruby
+Rack::Timeout::Logger.disable
+```
+
+Each log line is a set of `key=value` pairs, containing the entries from the `env["rack-timeout.info"]` struct that are not `nil`. See the Request Lifetime section above for a description of each field. Note that while the values for `wait`, `timeout`, and `service` are stored internally as seconds, they are logged as milliseconds for readability.
+
+A sample log excerpt might look like:
+
+```
+source=rack-timeout id=13793c wait=369ms timeout=10000ms state=ready at=info
+source=rack-timeout id=13793c wait=369ms timeout=10000ms service=15ms state=completed at=info
+source=rack-timeout id=ea7bd3 wait=371ms timeout=10000ms state=timed_out at=error
+```

data/doc/observers.md

@@ -0,0 +1,22 @@
+Observers
+---------
+
+Observers are blocks that are notified about state changes during a request's lifetime. Keep in mind that the `active` state is set every ~1s, so you'll be notified every time.
+
+You can register an observer with:
+
+```ruby
+Rack::Timeout.register_state_change_observer(:a_unique_name) { |env| do_things env }
+```
+
+There's currently no way to subscribe to changes into or out of a particular state. To check the actual state we're moving into, read `env['rack-timeout.info'].state`. Handling going out of a state would require some additional logic in the observer.
+
+You can remove an observer with `unregister_state_change_observer`:
+
+```ruby
+Rack::Timeout.unregister_state_change_observer(:a_unique_name)
+```
+
+rack-timeout's logging is implemented using an observer; see `Rack::Timeout::StateChangeLoggingObserver` in logging-observer.rb for the implementation.
+
+Custom observers might be used to do cleanup, store statistics on request length, timeouts, etc., and potentially do performance tuning on the fly.

data/doc/request-lifecycle.md

@@ -0,0 +1,27 @@
+Request Lifetime
+----------------
+
+Throughout a request's lifetime, Rack::Timeout keeps details about the request in `env[Rack::Timeout::ENV_INFO_KEY]`, or, more explicitly, `env["rack-timeout.info"]`.
+
+The value of that entry is an instance of `Rack::Timeout::RequestDetails`, which is a `Struct` consisting of the following fields:
+
+*   `id`: a unique ID per request. Either the value of the `X-Request-ID` header or a random ID
+    generated internally.
+
+*   `wait`: time in seconds since `X-Request-Start` at the time the request was initially seen by Rack::Timeout. Only set if `X-Request-Start` is present.
+
+*   `timeout`: the final timeout value that was used or to be used, in seconds. For `expired` requests, that would be the `wait_timeout`, possibly with `wait_overtime` applied. In all other cases it's the `service_timeout`, potentially reduced to make up for time lost waiting. (See discussion regarding `service_past_wait` above, under the Wait Timeout section.)
+
+*   `service`: set after a request completes (or times out). The time in seconds it took being processed. This is also updated while a request is still active, around every second, with the time taken so far.
+
+*   `state`: the possible states, and their log level, are:
+
+    *   `expired` (`ERROR`): the request is considered too old and is skipped entirely. This happens when `X-Request-Start` is present and older than `wait_timeout`. When in this state, `Rack::Timeout::RequestExpiryError` is raised. See earlier discussion about the `wait_overtime` setting, too.
+
+    *   `ready` (`INFO`): this is the state a request is in right before it's passed down the middleware chain. Once it's being processed, it'll move on to `active`, and then on to `timed_out` and/or `completed`.
+
+    *   `active` (`DEBUG`): 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` (`ERROR`): the request ran for longer than the determined timeout and was aborted. `Rack::Timeout::RequestTimeoutException` is raised in the application when this occurs. This state is not the final one, `completed` will be set after the framework is done with it. (If the exception does bubble up, it's caught by rack-timeout and re-raised as `Rack::Timeout::RequestTimeoutError`, which descends from RuntimeError.)
+
+    *   `completed` (`INFO`): the request completed 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 will still end up with a `completed` state.

data/doc/risks.md

@@ -0,0 +1,36 @@
+Risks and shortcomings of using Rack::Timeout
+---------------------------------------------
+
+### Timing Out During IO Blocks
+
+Sometimes a request is taking too long to complete because it's blocked waiting on synchronous IO. Such IO does not need to be file operations, it could be, say, network or database operations. If said IO is happening in a C library that's unaware of ruby's interrupt system (i.e. anything written without ruby in mind), calling `Thread#raise` (that's what rack-timeout uses) will not have effect until after the IO block is gone.
+
+At the moment rack-timeout does not try to address this issue. As a fail-safe against these cases, a blunter solution that kills the entire process is recommended, such as unicorn's timeouts.
+
+More detailed explanations of the issues surrounding timing out in ruby during IO blocks can be found at:
+
+- http://redgetan.cc/understanding-timeouts-in-cruby/
+
+### Timing Out is Inherently Unsafe
+
+Raising mid-flight in stateful applications is inherently unsafe. A request can be aborted at any moment in the code flow, and the application can be left in an inconsistent state. There's little way rack-timeout could be aware of ongoing state changes. Applications that rely on a set of globals (like class variables) or any other state that lives beyond a single request may find those left in an unexpected/inconsistent state after an aborted request. Some cleanup code might not have run, or only half of a set of related changes may have been applied.
+
+A lot more can go wrong. An intricate explanation of the issue by JRuby's Charles Nutter can be found [here][broken-timeout].
+
+Ruby 2.1 provides a way to defer the result of raising exceptions through the [Thread.handle_interrupt][handle-interrupt] method. This could be used in critical areas of your application code to prevent Rack::Timeout from accidentally wreaking havoc by raising just in the wrong moment. That said, `handle_interrupt` and threads in general are hard to reason about, and detecting all cases where it would be needed in an application is a tall order, and the added code complexity is probably not worth the trouble.
+
+Your time is better spent ensuring requests run fast and don't need to timeout.
+
+That said, it's something to be aware of, and may explain some eerie wonkiness seen in logs.
+
+[broken-timeout]: http://headius.blogspot.de/2008/02/rubys-threadraise-threadkill-timeoutrb.html
+[handle-interrupt]: http://www.ruby-doc.org/core-2.1.3/Thread.html#method-c-handle_interrupt
+
+
+### Time Out Early and Often
+
+Because of the aforementioned issues, it's recommended you set library-specific timeouts and leave Rack::Timeout as a last resort measure. Library timeouts will generally take care of IO issues and abort the operation safely. See [The Ultimate Guide to Ruby Timeouts][ruby-timeouts].
+
+You'll want to set all relevant timeouts to something lower than Rack::Timeout's `service_timeout`. Generally you want them to be at least 1s lower, so as to account for time spent elsewhere during the request's lifetime while still giving libraries a chance to time out before Rack::Timeout.
+
+[ruby-timeouts]: https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts

data/doc/rollbar.md

@@ -0,0 +1,30 @@
+### Rollbar
+
+Because rack-timeout may raise at any point in the codepath of a timed-out request, the stack traces for similar requests may differ, causing rollbar to create separate entries for each timeout.
+
+The recommended practice is to configure [Custom Fingerprints][rollbar-customfingerprint] on Rollbar.
+
+[rollbar-customfingerprint]: https://docs.rollbar.com/docs/custom-grouping/
+
+Example:
+
+```json
+[
+  {
+    "condition": {
+      "eq": "Rack::Timeout::RequestTimeoutException",
+      "path": "body.trace.exception.class"
+    },
+    "fingerprint": "Rack::Timeout::RequestTimeoutException {{context}}",
+    "title": "Rack::Timeout::RequestTimeoutException {{context}}"
+   }
+]
+
+```
+
+This configuration will generate exceptions following the pattern: `Rack::Timeout::RequestTimeoutException controller#action
+`
+
+On previous versions this configuration was made using `Rack::Timeout::Rollbar` which was removed. [More details on the Issue #122][rollbar-removal-issue].
+
+[rollbar-removal-issue]: https://github.com/heroku/rack-timeout/issues/122

data/doc/settings.md

@@ -0,0 +1,49 @@
+# Settings
+
+Rack::Timeout has 4 settings, each of which impacts when Rack::Timeout
+will raise an exception, and which type of exception will be raised.
+
+### Service Timeout
+
+`service_timeout` is the most important setting.
+
+*Service time* is the time taken from when a request first enters rack to when its response is sent back. When the application takes longer than `service_timeout` to process a request, the request's status is logged as `timed_out` and `Rack::Timeout::RequestTimeoutException` or `Rack::Timeout::RequestTimeoutError` is raised on the application thread. This may be automatically caught by the framework or plugins, so beware. Also, the exception is not guaranteed to be raised in a timely fashion, see section below about IO blocks.
+
+Service timeout can be disabled entirely by setting the property to `0` or `false`, at which point the request skips Rack::Timeout's machinery (so no logging will be present).
+
+### Wait Timeout
+
+Before a request reaches the rack application, it may have spent some time being received by the web server, or waiting in the application server's queue before being dispatched to rack. The time between when a request is received by the web server and when rack starts handling it is called the *wait time*.
+
+On Heroku, a request will be dropped when the routing layer sees no data being transferred for over 30 seconds. (You can read more about the specifics of Heroku routing's timeout [here][heroku-routing] and [here][heroku-timeout].) In this case, it makes no sense to process a request that reaches the application after having waited more than 30 seconds. That's where the `wait_timeout` setting comes in. When a request has a wait time greater than `wait_timeout`, it'll be dropped without ever being sent down to the application, and a `Rack::Timeout::RequestExpiryError` is raised. Such requests are logged as `expired`.
+
+[heroku-routing]: https://devcenter.heroku.com/articles/http-routing#timeouts
+[heroku-timeout]: https://devcenter.heroku.com/articles/request-timeout
+
+`wait_timeout` is set at a default of 30 seconds, matching Heroku's router's timeout.
+
+Wait timeout can be disabled entirely by setting the property to `0` or `false`.
+
+A request's computed wait time may affect the service timeout used for it. Basically, a request's wait time plus service time may not exceed the wait timeout. The reasoning for that is based on Heroku router's behavior, that the request would be dropped anyway after the wait timeout. So, for example, with the default settings of `service_timeout=15`, `wait_timeout=30`, a request that had 20 seconds of wait time will not have a service timeout of 15, but instead of 10, as there are only 10 seconds left before `wait_timeout` is reached. This behavior can be disabled by setting `service_past_wait` to `true`. When set, the `service_timeout` setting will always be honored. Please note that if you're using the `RACK_TIMEOUT_SERVICE_PAST_WAIT` environment variable, any value different than `"false"` will be considered `true`.
+
+The way we're able to infer a request's start time, and from that its wait time, is through the availability of the `X-Request-Start` HTTP header, which is expected to contain the time since epoch in milliseconds. (A concession is made for nginx's sec.msec notation.)
+
+If the `X-Request-Start` header is not present `wait_timeout` handling is skipped entirely.
+
+### Wait Overtime
+
+Relying on `X-Request-Start` is less than ideal, as it computes the time since the request *started* being received by the web server, rather than the time the request *finished* being received by the web server. That poses a problem for lengthy requests.
+
+Lengthy requests are requests with a body, such as POST requests. These take time to complete being received by the application server, especially when the client has a slow upload speed, as is common for example with mobile clients or asymmetric connections.
+
+While we can infer the time since a request started being received, we can't tell when it completed being received, which would be preferable. We're also unable to tell the time since the last byte was sent in the request, which would be relevant in tracking Heroku's router timeout appropriately.
+
+A request that took longer than 30s to be fully received, but that had been uploading data all that while, would be dropped immediately by Rack::Timeout because it'd be considered too old. Heroku's router, however, would not have dropped this request because data was being transmitted all along.
+
+As a concession to these shortcomings, for requests that have a body present, we allow some additional wait time on top of `wait_timeout`. This aims to make up for time lost to long uploads.
+
+This extra time is called *wait overtime* and can be set via `wait_overtime`. It defaults to 60 seconds. This can be disabled as usual by setting the property to `0` or `false`. When disabled, there's no overtime. If you want lengthy requests to never get expired, set `wait_overtime` to a very high number.
+
+Keep in mind that Heroku [recommends][uploads] uploading large files directly to S3, so as to prevent the dyno from being blocked for too long and hence unable to handle further incoming requests.
+
+[uploads]: https://devcenter.heroku.com/articles/s3#file-uploads

data/lib/rack/timeout/core.rb

@@ -49,7 +49,7 @@ module Rack
     # helper methods to read timeout properties. Ensure they're always positive numbers or false. When set to false (or 0), their behaviour is disabled.
     def read_timeout_property value, default
       case value
-      when nil   ; default
+      when nil   ; read_timeout_property default, default
       when false ; false
       when 0     ; false
       else
@@ -147,8 +147,9 @@ module Rack
     # This is a code extraction for readability, this method is only called from a single point.
     RX_NGINX_X_REQUEST_START  = /^(?:t=)?(\d+)\.(\d{3})$/
     RX_HEROKU_X_REQUEST_START = /^(\d+)$/
+    HTTP_X_REQUEST_START = "HTTP_X_REQUEST_START".freeze
     def self._read_x_request_start(env)
-      return unless s = env["HTTP_X_REQUEST_START"]
+      return unless s = env[HTTP_X_REQUEST_START]
       return unless m = s.match(RX_HEROKU_X_REQUEST_START) || s.match(RX_NGINX_X_REQUEST_START)
       Time.at(m[1,2].join.to_f / 1000)
     end

data/test/basic_test.rb

@@ -1,32 +1,23 @@
-require "test/unit"
-require "rack/test"
-require "rack-timeout"
-
-class BasicTest < Test::Unit::TestCase
-  include Rack::Test::Methods
-
-  def app
-    Rack::Builder.new do
-      use Rack::Timeout, service_timeout: 1
-
-      map "/" do
-        run lambda { |env| [200, {'Content-Type' => 'text/plain'}, ['OK']] }
-      end
-
-      map "/sleep" do
-        run lambda { |env| sleep }
-      end
-    end
-  end
+require "test_helper"
 
+class BasicTest < RackTimeoutTest
   def test_ok
+    self.settings = { service_timeout: 1 }
     get "/"
     assert last_response.ok?
   end
 
   def test_timeout
+    self.settings = { service_timeout: 1 }
     assert_raises(Rack::Timeout::RequestTimeoutError) do
       get "/sleep"
     end
   end
+
+  def test_wait_timeout
+    self.settings = { service_timeout: 1, wait_timeout: 15 }
+    assert_raises(Rack::Timeout::RequestExpiryError) do
+      get "/", "", 'HTTP_X_REQUEST_START' => time_in_msec(Time.now - 100)
+    end
+  end
 end

data/test/env_settings_test.rb

@@ -0,0 +1,20 @@
+require 'test_helper'
+
+class EnvSettingsTest < RackTimeoutTest
+
+  def test_service_timeout
+    with_env(RACK_TIMEOUT_SERVICE_TIMEOUT: 1) do
+      assert_raises(Rack::Timeout::RequestTimeoutError) do
+        get "/sleep"
+      end
+    end
+  end
+
+  def test_zero_wait_timeout
+    with_env(RACK_TIMEOUT_WAIT_TIMEOUT: 0) do
+      get "/", "", 'HTTP_X_REQUEST_START' => time_in_msec(Time.now - 100)
+      assert last_response.ok?
+    end
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,46 @@
+require "test/unit"
+require "rack/test"
+require "rack-timeout"
+
+class RackTimeoutTest < Test::Unit::TestCase
+  include Rack::Test::Methods
+
+  attr_accessor :settings
+
+  def initialize(*args)
+    self.settings ||= {}
+    super(*args)
+  end
+
+  def app
+    settings = self.settings
+    Rack::Builder.new do
+      use Rack::Timeout, settings
+
+      map "/" do
+        run lambda { |env| [200, {'Content-Type' => 'text/plain'}, ['OK']] }
+      end
+
+      map "/sleep" do
+        run lambda { |env| sleep }
+      end
+    end
+  end
+
+  # runs the test with the given environment, but doesnt restore the original
+  # environment afterwards. This should be sufficient for rack-timeout testing.
+  def with_env(hash)
+    hash.each_pair do |k, v|
+      ENV[k.to_s] = v.to_s
+    end
+    yield
+    hash.each_key do |k|
+      ENV[k.to_s] = nil
+    end
+  end
+
+  def time_in_msec(t = Time.now)
+    "#{t.tv_sec}#{t.tv_usec/1000}"
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-timeout
 version: !ruby/object:Gem::Version
-  version: 0.5.0.1
+  version: 0.5.1
 platform: ruby
 authors:
 - Caio Chassot
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-21 00:00:00.000000000 Z
+date: 2018-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -59,11 +59,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- CHANGELOG
 - Gemfile
 - MIT-LICENSE
-- README.markdown
 - Rakefile
+- doc/exceptions.md
+- doc/logging.md
+- doc/observers.md
+- doc/request-lifecycle.md
+- doc/risks.md
+- doc/rollbar.md
+- doc/settings.md
 - lib/rack-timeout.rb
 - lib/rack/timeout/base.rb
 - lib/rack/timeout/core.rb
@@ -76,6 +81,8 @@ files:
 - lib/rack/timeout/support/scheduler.rb
 - lib/rack/timeout/support/timeout.rb
 - test/basic_test.rb
+- test/env_settings_test.rb
+- test/test_helper.rb
 homepage: http://github.com/heroku/rack-timeout
 licenses:
 - MIT
@@ -102,5 +109,7 @@ specification_version: 4
 summary: Abort requests that are taking too long
 test_files:
 - test/basic_test.rb
+- test/env_settings_test.rb
+- test/test_helper.rb
 - Gemfile
 - Rakefile

data/CHANGELOG

@@ -1,103 +0,0 @@
-0.5.0.1
-=======
-- Fix 0600 permissions in gem pushed to rubygems
-
-0.5.0
-=====
-
-Breaking Changes
-
-- Remove Rollbar module (#124)
-- Remove legacy class setters (#125)
-
-Other
-
-- Add support to configure via environment variables (#105)
-- Adds support for ActionDispatch::RequestId generated request ids (#115)
-- Changes uuid format to proper uuid (#115)
-
-0.4.2
-=====
-- Ruby 2.0 compatible
-
-0.4.1
-=====
-- Rails 5 support
-- Remove deprecation warning on timeout setter for Rails apps
-
-0.4.0
-=====
-- Using monotonic time instead of Time.now where available (/ht concurrent-ruby)
-- Settings are now passable to the middleware initializer instead of class-level
-- Rollbar module may take a custom fingerprint block
-- Rollbar module considered final
-- Fixed an issue where some heartbeats would live on forever (#103, /ht @0x0badc0de)
-
-0.3.2
-=====
-- Fixes calling timeout with a value of 0 (issue #90)
-
-0.3.1
-=====
-- Rollbar module improvements
-
-0.3.0
-=====
-- use a single scheduler thread to manage timeouts, instead of one timeout thread per request
-- instead of inserting middleware at position 0 for rails, insert before Rack::Runtime (which is right after Rack::Lock and the static file stuff)
-- reshuffle error types: RequestExpiryError is again a RuntimeError, and timeouts raise a RequestTimeoutException, an Exception, and not descending from Rack::Timeout::Error (see README for more)
-- don't insert middleware for rails in test environment
-- add convenience module Rack::Timeout::Logger (see README for more)
-- StageChangeLoggingObserver renamed to StateChangeLoggingObserver, works slightly differently too
-- file layout reorganization (see 6e82c276 for details)
-- CHANGELOG file is now in the gem (@dbackeus)
-- add optional and experimental support for grouping errors by url under rollbar. see "rack/timeout/rollbar" for usage
-
-0.2.4
-=====
-- Previous fix was borked.
-
-0.2.3
-=====
-- Ignore Rack::NullLogger when picking a logger
-
-0.2.1
-=====
-- Fix raised error messages
-
-0.2.0
-=====
-- Added CHANGELOG
-- Rack::Timeout::Error now inherits from Exception instead of StandardError, with the hope users won't rescue from it accidentally
-
-0.1.2
-=====
-- improve RequestTimeoutError error string so @watsonian is happy
-
-0.1.1
-=====
-- README updates
-- fix that setting properties to false resulted in an error
-
-0.1.0
-=====
-- Rewrote README
-
-0.1.0beta4
-==========
-- Renamed `timeout` setting to `service_timeout`; `timeout=` still works for backwards compatibility
-– `MAX_REQUEST_AGE` is gone, the `wait_timeout` setting more or less replaces it
-- Renamed `overtime` setting to `wait_overtime`
-- overtime setting should actually work (It had never made it to beta3)
-- In the request info struct, renamed `age` to `wait`, `duration` to `service`
-- Rack::Timeout::StageChangeLogger is gone, replaced by Rack::Timeout::StageChangeLoggingObserver, which is an observer class that composites with a logger, instead of inheriting from Logger. Anything logging related will likely be incompatible with previous beta release.
-- Log level can no longer be set with env vars, has to be set in the logger being used. (Which can now be custom / user-provided.)
-
-0.1.0beta1,2,3
-==============
-- Dropped ruby 1.8.x support
-- Dropped rails 2 support
-- Added rails 4 support
-- Added much logging
-– Added support for dropping requests that waited too long in the queue without ever handling them
-- Other things I can't remember, see git logs :P

data/README.markdown

@@ -1,317 +0,0 @@
-Rack::Timeout
-=============
-
-Abort requests that are taking too long; an exception 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. Most applications will do fine with a setting between 2 and 5 seconds.
-
-There's a handful of other settings, read on for details.
-
-Rack::Timeout is not a solution to the problem of long-running requests, it's a debug and remediation tool. App developers should track rack-timeout's data and address recurring instances of particular timeouts, for example by refactoring code so it runs faster or offsetting lengthy work to happen asynchronously.
-
-
-Basic Usage
------------
-
-The following covers currently supported versions of Rails, Rack, Ruby, and Bundler. See the Compatibility section at the end for legacy versions.
-
-### Rails apps
-
-```ruby
-# Gemfile
-gem "rack-timeout"
-```
-
-This will load rack-timeout and set it up as a Rails middleware using the default timeout of 15s. The middleware is not inserted for the test environment. You can modify the timeout by setting a `RACK_TIMEOUT_SERVICE_TIMEOUT` environment variable.
-
-### Rails apps, manually
-
-You'll need to do this if you removed `Rack::Runtime` from the middleware stack, or if you want to determine yourself where in the stack `Rack::Timeout` gets inserted.
-
-```ruby
-# Gemfile
-gem "rack-timeout", require:"rack/timeout/base"
-```
-
-```ruby
-# config/initializers/rack_timeout.rb
-
-# insert middleware wherever you want in the stack, optionally pass initialization arguments or use environment variables
-Rails.application.config.middleware.insert_before Rack::Runtime, Rack::Timeout, service_timeout: 5
-```
-
-### Sinatra and other Rack apps
-
-```ruby
-# config.ru
-require "rack-timeout"
-
-# Call as early as possible so rack-timeout runs before all other middleware.
-# Setting service_timeout or `RACK_TIMEOUT_SERVICE_TIMEOUT` environment variable is recommended. If omitted, defaults to 15 seconds.
-use Rack::Timeout, service_timeout: 5
-```
-
-
-The Rabbit Hole
----------------
-
-Rack::Timeout takes the following settings, shown here with their default values:
-
-```
-service_timeout:   15     # RACK_TIMEOUT_SERVICE_TIMEOUT
-wait_timeout:      30     # RACK_TIMEOUT_WAIT_TIMEOUT
-wait_overtime:     60     # RACK_TIMEOUT_WAIT_OVERTIME
-service_past_wait: false  # RACK_TIMEOUT_SERVICE_PAST_WAIT
-```
-
-As shown earlier, these settings can be overriden during middleware initialization or environment variables `RACK_TIMEOUT_*` mentioned above. Middleware parameters take precedence:
-
-```ruby
-use Rack::Timeout, service_timeout: 5, wait_timeout: false
-```
-
-### Service Timeout
-
-`service_timeout` is our most important setting.
-
-*Service time* is the time taken from when a request first enters rack to when its response is sent back. When the application takes longer than `service_timeout` to process a request, the request's status is logged as `timed_out` and `Rack::Timeout::RequestTimeoutException` or `Rack::Timeout::RequestTimeoutError` is raised on the application thread. This may be automatically caught by the framework or plugins, so beware. Also, the exception is not guaranteed to be raised in a timely fashion, see section below about IO blocks.
-
-Service timeout can be disabled entirely by setting the property to `0` or `false`, at which point the request skips Rack::Timeout's machinery (so no logging will be present).
-
-
-### Wait Timeout
-
-Before a request reaches the rack application, it may have spent some time being received by the web server, or waiting in the application server's queue before being dispatched to rack. The time between when a request is received by the web server and when rack starts handling it is called the *wait time*.
-
-On Heroku, a request will be dropped when the routing layer sees no data being transferred for over 30 seconds. (You can read more about the specifics of Heroku routing's timeout [here][heroku-routing] and [here][heroku-timeout].) In this case, it makes no sense to process a request that reaches the application after having waited more than 30 seconds. That's where the `wait_timeout` setting comes in. When a request has a wait time greater than `wait_timeout`, it'll be dropped without ever being sent down to the application, and a `Rack::Timeout::RequestExpiryError` is raised. Such requests are logged as `expired`.
-
-[heroku-routing]: https://devcenter.heroku.com/articles/http-routing#timeouts
-[heroku-timeout]: https://devcenter.heroku.com/articles/request-timeout
-
-`wait_timeout` is set at a default of 30 seconds, matching Heroku's router's timeout.
-
-Wait timeout can be disabled entirely by setting the property to `0` or `false`.
-
-A request's computed wait time may affect the service timeout used for it. Basically, a request's wait time plus service time may not exceed the wait timeout. The reasoning for that is based on Heroku router's behavior, that the request would be dropped anyway after the wait timeout. So, for example, with the default settings of `service_timeout=15`, `wait_timeout=30`, a request that had 20 seconds of wait time will not have a service timeout of 15, but instead of 10, as there are only 10 seconds left before `wait_timeout` is reached. This behavior can be disabled by setting `service_past_wait` to `true`. When set, the `service_timeout` setting will always be honored. Please note that if you're using the `RACK_TIMEOUT_SERVICE_PAST_WAIT` environment variable, any value different than `"false"` will be considered `true`.
-
-The way we're able to infer a request's start time, and from that its wait time, is through the availability of the `X-Request-Start` HTTP header, which is expected to contain the time since epoch in milliseconds. (A concession is made for nginx's sec.msec notation.)
-
-If the `X-Request-Start` header is not present `wait_timeout` handling is skipped entirely.
-
-
-### Wait Overtime
-
-Relying on `X-Request-Start` is less than ideal, as it computes the time since the request *started* being received by the web server, rather than the time the request *finished* being received by the web server. That poses a problem for lengthy requests.
-
-Lengthy requests are requests with a body, such as POST requests. These take time to complete being received by the application server, especially when the client has a slow upload speed, as is common for example with mobile clients or asymmetric connections.
-
-While we can infer the time since a request started being received, we can't tell when it completed being received, which would be preferable. We're also unable to tell the time since the last byte was sent in the request, which would be relevant in tracking Heroku's router timeout appropriately.
-
-A request that took longer than 30s to be fully received, but that had been uploading data all that while, would be dropped immediately by Rack::Timeout because it'd be considered too old. Heroku's router, however, would not have dropped this request because data was being transmitted all along.
-
-As a concession to these shortcomings, for requests that have a body present, we allow some additional wait time on top of `wait_timeout`. This aims to make up for time lost to long uploads.
-
-This extra time is called *wait overtime* and can be set via `wait_overtime`. It defaults to 60 seconds. This can be disabled as usual by setting the property to `0` or `false`. When disabled, there's no overtime. If you want lengthy requests to never get expired, set `wait_overtime` to a very high number.
-
-Keep in mind that Heroku [recommends][uploads] uploading large files directly to S3, so as to prevent the dyno from being blocked for too long and hence unable to handle further incoming requests.
-
-[uploads]: https://devcenter.heroku.com/articles/s3#file-uploads
-
-
-### Timing Out During IO Blocks
-
-Sometimes a request is taking too long to complete because it's blocked waiting on synchronous IO. Such IO does not need to be file operations, it could be, say, network or database operations. If said IO is happening in a C library that's unaware of ruby's interrupt system (i.e. anything written without ruby in mind), calling `Thread#raise` (that's what rack-timeout uses) will not have effect until after the IO block is gone.
-
-At the moment rack-timeout does not try to address this issue. As a fail-safe against these cases, a blunter solution that kills the entire process is recommended, such as unicorn's timeouts.
-
-More detailed explanations of the issues surrounding timing out in ruby during IO blocks can be found at:
-
-- http://redgetan.cc/understanding-timeouts-in-cruby/
-
-### Timing Out Inherently Unsafe
-
-Raising mid-flight in stateful applications is inherently unsafe. A request can be aborted at any moment in the code flow, and the application can be left in an inconsistent state. There's little way rack-timeout could be aware of ongoing state changes. Applications that rely on a set of globals (like class variables) or any other state that lives beyond a single request may find those left in an unexpected/inconsistent state after an aborted request. Some cleanup code might not have run, or only half of a set of related changes may have been applied.
-
-A lot more can go wrong. An intricate explanation of the issue by JRuby's Charles Nutter can be found [here][broken-timeout].
-
-Ruby 2.1 provides a way to defer the result of raising exceptions through the [Thread.handle_interrupt][handle-interrupt] method. This could be used in critical areas of your application code to prevent Rack::Timeout from accidentally wreaking havoc by raising just in the wrong moment. That said, `handle_interrupt` and threads in general are hard to reason about, and detecting all cases where it would be needed in an application is a tall order, and the added code complexity is probably not worth the trouble.
-
-Your time is better spent ensuring requests run fast and don't need to timeout.
-
-That said, it's something to be aware of, and may explain some eerie wonkiness seen in logs.
-
-[broken-timeout]: http://headius.blogspot.de/2008/02/rubys-threadraise-threadkill-timeoutrb.html
-[handle-interrupt]: http://www.ruby-doc.org/core-2.1.3/Thread.html#method-c-handle_interrupt
-
-
-### Time Out Early and Often
-
-Because of the aforementioned issues, it's recommended you set library-specific timeouts and leave Rack::Timeout as a last resort measure. Library timeouts will generally take care of IO issues and abort the operation safely. See [The Ultimate Guide to Ruby Timeouts][ruby-timeouts].
-
-You'll want to set all relevant timeouts to something lower than Rack::Timeout's `service_timeout`. Generally you want them to be at least 1s lower, so as to account for time spent elsewhere during the request's lifetime while still giving libraries a chance to time out before Rack::Timeout.
-
-[ruby-timeouts]: https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts
-
-
-Request Lifetime
-----------------
-
-Throughout a request's lifetime, Rack::Timeout keeps details about the request in `env[Rack::Timeout::ENV_INFO_KEY]`, or, more explicitly, `env["rack-timeout.info"]`.
-
-The value of that entry is an instance of `Rack::Timeout::RequestDetails`, which is a `Struct` consisting of the following fields:
-
-*   `id`: a unique ID per request. Either the value of the `X-Request-ID` header or a random ID
-    generated internally.
-
-*   `wait`: time in seconds since `X-Request-Start` at the time the request was initially seen by Rack::Timeout. Only set if `X-Request-Start` is present.
-
-*   `timeout`: the final timeout value that was used or to be used, in seconds. For `expired` requests, that would be the `wait_timeout`, possibly with `wait_overtime` applied. In all other cases it's the `service_timeout`, potentially reduced to make up for time lost waiting. (See discussion regarding `service_past_wait` above, under the Wait Timeout section.)
-
-*   `service`: set after a request completes (or times out). The time in seconds it took being processed. This is also updated while a request is still active, around every second, with the time taken so far.
-
-*   `state`: the possible states, and their log level, are:
-
-    *   `expired` (`ERROR`): the request is considered too old and is skipped entirely. This happens when `X-Request-Start` is present and older than `wait_timeout`. When in this state, `Rack::Timeout::RequestExpiryError` is raised. See earlier discussion about the `wait_overtime` setting, too.
-
-    *   `ready` (`INFO`): this is the state a request is in right before it's passed down the middleware chain. Once it's being processed, it'll move on to `active`, and then on to `timed_out` and/or `completed`.
-
-    *   `active` (`DEBUG`): 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` (`ERROR`): the request ran for longer than the determined timeout and was aborted. `Rack::Timeout::RequestTimeoutException` is raised in the application when this occurs. This state is not the final one, `completed` will be set after the framework is done with it. (If the exception does bubble up, it's caught by rack-timeout and re-raised as `Rack::Timeout::RequestTimeoutError`, which descends from RuntimeError.)
-
-    *   `completed` (`INFO`): the request completed 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 will still end up with a `completed` state.
-
-
-Errors
-------
-
-Rack::Timeout can raise three types of exceptions. They are:
-
-Two descend from `Rack::Timeout::Error`, which itself descends from `RuntimeError` and is generally caught by an unqualified `rescue`. The third, `RequestTimeoutException`, is more complicated and the most important.
-
-*   `Rack::Timeout::RequestTimeoutException`: this is raised when a request has run for longer than the specified timeout. This descends from `Exception`, not from `Rack::Timeout::Error` (it has to be rescued from explicitly). It's 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 could be caught explicitly within the application, but in doing so you're working past the timeout. This is ok for quick cleanup work but shouldn't be abused as Rack::Timeout will not kick in twice for the same request.
-
-    Rails will generally intercept `Exception`s, but in plain Rack apps, this exception will be caught by rack-timeout and re-raised as a `Rack::Timeout::RequestTimeoutError`. This is to prevent an `Exception` from bubbling up beyond rack-timeout and to the server.
-
-*   `Rack::Timeout::RequestTimeoutError` descends from `Rack::Timeout::Error`, but it's only really seen in the case described above. It'll not be seen in a standard Rails app, and will only be seen in Sinatra if rescuing from exceptions is disabled.
-
-*   `Rack::Timeout::RequestExpiryError`: this is raised when a request is skipped for being too old (see Wait Timeout section). This error cannot generally be rescued from inside a Rails controller action as it happens before the request has a chance to enter Rails.
-
-    This shouldn't be different for other frameworks, unless you have something above Rack::Timeout in the middleware stack, which you generally shouldn't.
-
-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::RequestTimeoutException` 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
-
-
-### Rollbar
-
-Because rack-timeout may raise at any point in the codepath of a timed-out request, the stack traces for similar requests may differ, causing rollbar to create separate entries for each timeout.
-
-The recommended practice is to configure [Custom Fingerprints][rollbar-customfingerprint] on Rollbar.
-
-[rollbar-customfingerprint]: https://docs.rollbar.com/docs/custom-grouping/
-
-Example:
-
-```json
-[
-  {
-    "condition": {
-      "eq": "Rack::Timeout::RequestTimeoutException",
-      "path": "body.trace.exception.class"
-    },
-    "fingerprint": "Rack::Timeout::RequestTimeoutException {{context}}",
-    "title": "Rack::Timeout::RequestTimeoutException {{context}}"
-   }
-]
-
-```
-
-This configuration will generate exceptions following the pattern: `Rack::Timeout::RequestTimeoutException controller#action
-`
-
-On previous versions this configuration was made using `Rack::Timeout::Rollbar` which was removed. [More details on the Issue #122][rollbar-removal-issue].
-
-[rollbar-removal-issue]: https://github.com/heroku/rack-timeout/issues/122
-
-Observers
----------
-
-Observers are blocks that are notified about state changes during a request's lifetime. Keep in mind that the `active` state is set every ~1s, so you'll be notified every time.
-
-You can register an observer with:
-
-```ruby
-Rack::Timeout.register_state_change_observer(:a_unique_name) { |env| do_things env }
-```
-
-There's currently no way to subscribe to changes into or out of a particular state. To check the actual state we're moving into, read `env['rack-timeout.info'].state`. Handling going out of a state would require some additional logic in the observer.
-
-You can remove an observer with `unregister_state_change_observer`:
-
-```ruby
-Rack::Timeout.unregister_state_change_observer(:a_unique_name)
-```
-
-rack-timeout's logging is implemented using an observer; see `Rack::Timeout::StateChangeLoggingObserver` in logging-observer.rb for the implementation.
-
-Custom observers might be used to do cleanup, store statistics on request length, timeouts, etc., and potentially do performance tuning on the fly.
-
-
-Logging
--------
-
-Rack::Timeout logs a line every time there's a change in state in a request's lifetime.
-
-Request state changes into `timed_out` and `expired` are logged at the `ERROR` level, most other things are logged as `INFO`. The `active` state is logged as `DEBUG`, every ~1s while the request is still active.
-
-Rack::Timeout will try to use `Rails.logger` if present, otherwise it'll look for a logger in `env['rack.logger']`, and if neither are present, it'll create its own logger, either writing to `env['rack.errors']`, or to `$stderr` if the former is not set.
-
-When creating its own logger, rack-timeout will use a log level of `INFO`. Otherwise whatever log level is already set on the logger being used continues in effect.
-
-A custom logger can be set via `Rack::Timeout::Logger.logger`. This takes priority over the automatic logger detection:
-
-```ruby
-Rack::Timeout::Logger.logger = Logger.new
-```
-
-There are helper setters that replace the logger:
-
-```ruby
-Rack::Timeout::Logger.device = $stderr
-Rack::Timeout::Logger.level  = Logger::INFO
-```
-
-Although each call replaces the logger, these can be use together and the final logger will retain both properties. (If only one is called, the defaults used above apply.)
-
-Logging is enabled by default, but can be removed with:
-
-```ruby
-Rack::Timeout::Logger.disable
-```
-
-Each log line is a set of `key=value` pairs, containing the entries from the `env["rack-timeout.info"]` struct that are not `nil`. See the Request Lifetime section above for a description of each field. Note that while the values for `wait`, `timeout`, and `service` are stored internally as seconds, they are logged as milliseconds for readability.
-
-A sample log excerpt might look like:
-
-```
-source=rack-timeout id=13793c wait=369ms timeout=10000ms state=ready at=info
-source=rack-timeout id=13793c wait=369ms timeout=10000ms service=15ms state=completed at=info
-source=rack-timeout id=ea7bd3 wait=371ms timeout=10000ms state=timed_out at=error
-```
-
-
-Compatibility
--------------
-
-This version of Rack::Timeout is compatible with Ruby 2.1 and up, and, for Rails apps, Rails 3.x and up.
-
-
----
-Copyright © 2010-2016 Caio Chassot, released under the MIT license
-<http://github.com/heroku/rack-timeout>