rack-timeout 0.1.0beta → 0.1.0beta2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZmIyM2ZmYTI0MGY2MWM2YjViZDYwNDZjZjEyNGEwODM5OGY5MGUzYw==
+    ZGY0YjFmYWYzMTAzY2E4NWUzMWQyM2ZlN2YwY2E2Yzk0ZGVkZGRlNA==
   data.tar.gz: !binary |-
-    YmE0ZjYyZGNjOWE1NTljN2VhYjBjM2E5ZmI3NWIzMjIyY2YzZGJiYQ==
+    MjE3NDM5ZTdlMWU4NTQ0OGEzNGYyYzU2MTc4MjczNTNhZDhhYWE0Mw==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NjQxODhjN2JlNjNjM2E2NzI1NDA4NzRhNDFjMmUxYmVmMTFlOGI1NWU3ZWNk
-    NDNkMDYwZjc5YjRiZTE3NGViYTY1YjQyYWJiMjcyZWJhNGMzMjQ0ZTk3M2E1
-    NGI2YTk3YzZjZmRlMmUyNGFkYmQ3OWM2MjdkYTZhZGY1ZWMwZDA=
+    YTVlYTViYjc0ZDdlYzBiYjNhYzJiOTc4ZTQ4OTVlYjNkOWM5MTFmMmRmNzIw
+    MTM0OWI3ZWVmODRiY2M3ZDAwMGY3OGViNmJkMTZiYzlkYzI0ZTJhYThhYTEy
+    MWJlNTUzZTZjYzc2Y2ViMThlMjJlMDdiMTM5Mzg0MzNjMzM0ZTc=
   data.tar.gz: !binary |-
-    ODg1ODEzZjRhY2FiYmY1NjBmYzkzZDZlZTAxZjRmZWU5MDk3NGY5OWMyN2Q4
-    ZDcyN2QwMzM2NjM5N2RjYzIwYWU3MDE3OWI0NGMyNGRhOTNhYTQxNzMxNTcz
-    YzAwMzE1OTZmMTA5ZmU2OTdmMWNjN2JlYTI3MmVjMjIzMTVjNmM=
+    ZTc3Yzk3MmE4YWE0NjQwNjliNjNmZmY1Zjc0ZTdjODYwYThhYmJjNjI0NTRh
+    ZTk5ZGU0YjE1YmQ3ZWY0YTg4N2I1MWUwOGExYTk4M2Q1ZGI0NWRmM2YxMjAw
+    MjFiMzJlOTQ0NjVkYWZmMWRhYzMzN2UwOGRmYjkwZDc0MTc0MjA=

data/README.markdown

@@ -7,7 +7,8 @@ Abort requests that are taking too long; a `Rack::Timeout::Error` will be raised
 Usage
 -----
 
-Setup for current versions of Rails, Rack, Ruby, and Bundler. See next section for legacy versions.
+Setup for current versions of Rails, Rack, Ruby, and Bundler. See the Compatibility section at the
+end for legacy versions.
 
 ### Rails apps
 
@@ -23,11 +24,171 @@ create an initializer file:
 ### Sinatra and other Rack apps
 
     # config.ru
-    require "rack/timeout"
+    require "rack-timeout"
     use Rack::Timeout           # Call as early as possible so rack-timeout runs before other middleware.
     Rack::Timeout.timeout = 10  # This line is optional. If omitted, timeout defaults to 15 seconds.
 
 
+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.
+
+    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.
+
+    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 30s maximum age is set in 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.
+
+    `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
+    it allows one to correlate Rack::Timeout events with the Heroku router's events. There are no
+    downsides to enabling http-request-id.
+
+[X-Request-Start]: https://devcenter.heroku.com/articles/http-routing#heroku-headers
+[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
+determine if the app is actually running on Heroku.
+
+
+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`
+containing the following fields:
+
+*   `id`: a unique ID per request. Either `Heroku-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.
+
+*   `duration`: set after a request completes (or times out). The time in seconds it took.
+
+*   `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.
+
+    *   `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`.
+
+    *   `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.
+
+    *   `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.
+
+
+Errors
+------
+
+Rack::Timeout can raise two types of exceptions. Both descend from `Rack::Timeout::Error`, which
+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.
+
+*   `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.
+
+    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
+change notifications with observers.
+
+
+Observers
+---------
+
+Observers are objects or blocks that are notified about state changes during a request lifetime.
+
+You can register an observer easily with a block:
+
+    Rack::Timeout.register_state_change_observer(:a_unique_name) { |env| do_things env }
+
+or by passing an object that responds to `rack_timeout_request_did_change_state_in(env)`:
+
+    class MyObserver
+      def rack_timeout_request_did_change_state_in(env)
+        # ... do stuff ...
+      end
+    end
+
+    Rack::Timeout.register_state_change_observer(:another_name, MyObserver.new)
+
+This is how logging is implemented, too. See `Rack::Timeout::StateChangeLogger`.
+
+You can remove an observer with `unregister_state_change_observer`:
+
+    Rack::Timeout.unregister_state_change_observer(:a_unique_name)
+
+Custom observers might be used to 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.
+
+Changes into `timed_out` and `expired` are logged at the `ERROR` level, everything else is `INFO`.
+
+The default log level for Rack::Timeout is `INFO`, but can be affected via:
+
+*   Unix environment variables. First `RACK_TIMEOUT_LOG_LEVEL` is checked, then `LOG_LEVEL`. Their
+    value must be name of a predefined constant in ruby's `Logger` class, e.g. `INFO` or `DEBUG`.
+    Case is not significant.
+
+*   By setting `Rack::Timeout.logger.level` directly, e.g.:
+
+        Rack::Timeout.logger.level = ::Logger::DEBUG
+
+Logging is enabled by default if Rack::Timeout is loaded via the `rack-timeout` file (recommended),
+but can be removed by unregistering its observer:
+
+    Rack::Timeout.unregister_state_change_observer(:logger)
+
+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 `age`, `timeout`, and `duration` are
+stored internally as seconds, they are logged as milliseconds for readability.
+
+A sample log excerpt might look like:
+
+    source=rack-timeout id=13793c age=369ms timeout=10000ms state=ready at=info
+    source=rack-timeout id=13793c age=369ms timeout=10000ms duration=15ms state=completed at=info
+    source=rack-timeout id=ea7bd3 age=371ms timeout=10000ms state=timed_out at=error
+
+(IDs shortened for readability.)
+
+
 Compatibility
 -------------
 
@@ -39,7 +200,7 @@ 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
+Here Be Dragons
 ---------------
 
 *   Ruby's Timeout rely on threads. If your app or any of the libraries it depends on is not

data/lib/rack-timeout.rb

@@ -1,9 +1,12 @@
 # encoding: utf-8
-require_relative 'rack/timeout'
+require 'rack/timeout'
+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.timeout-trap') { |app| app.config.middleware.use Rack::Timeout::AbortionReporter }
+    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
+
+Rack::Timeout::StateChangeLogger.register!

data/lib/rack/timeout.rb

@@ -5,13 +5,14 @@ require 'securerandom'
 module Rack
   class Timeout
     class Error < RuntimeError;        end
-    class RequestTooOldError  < Error; end
-    class RequestAbortedError < Error; end
+    class RequestExpiryError  < Error; end
+    class RequestTimeoutError < Error; end
 
-    RequestData          = Struct.new(:id, :age, :timeout, :duration, :state)
+    RequestDetails       = Struct.new(:id, :age, :timeout, :duration, :state)
     ENV_INFO_KEY         = 'rack-timeout.info'
-    FRAMEWORK_ERROR_KEYS = %w(sinatra.error rack.exception)
-    FINAL_STATES         = [:dropped, :aborted, :completed]
+    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
@@ -24,7 +25,7 @@ module Rack
     end
 
     def call(env)
-      info          = env[ENV_INFO_KEY] ||= RequestData.new
+      info          = env[ENV_INFO_KEY] ||= RequestDetails.new
       info.id     ||= env['HTTP_HEROKU_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
@@ -33,57 +34,88 @@ module Rack
       info.timeout  = [self.class.timeout, time_left].compact.select { |n| n >= 0 }.min
 
       if time_left && time_left <= 0
-        Rack::Timeout.set_state_and_log! info, :dropped
-        raise RequestTooOldError
+        Rack::Timeout._set_state! env, :expired
+        raise RequestExpiryError
       end
 
-      Rack::Timeout.set_state_and_log! info, :ready
-      ::Timeout.timeout(info.timeout, RequestAbortedError) do
+      Rack::Timeout._set_state! env, :ready
+      ::Timeout.timeout(info.timeout, RequestTimeoutError) do
         ready_time    = Time.now
-        response      = Rack::Timeout.perform_reporting_abortion_state_in_env(env) { @app.call(env) }
+        response      = Rack::Timeout._perform_block_tracking_timeout_to_env(env) { @app.call(env) }
         info.duration = Time.now - ready_time
-        Rack::Timeout.set_state_and_log! info, :completed
+        Rack::Timeout._set_state! env, :completed
         response
       end
     end
 
-    def self.perform_reporting_abortion_state_in_env(env)
+    # used in #call and TimeoutTracker
+    def self._perform_block_tracking_timeout_to_env(env)
       yield
-    rescue RequestAbortedError
-      set_aborted! env
+    rescue RequestTimeoutError
+      timed_out = true
       raise
     ensure
-      set_aborted! env if env.values_at(*FRAMEWORK_ERROR_KEYS).any? { |e| e.is_a? RequestAbortedError }
+      # 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
     end
 
-    def self.set_aborted!(env)
-      set_state_and_log!(env[ENV_INFO_KEY], :aborted)
-    end
-
-    def self.set_state_and_log!(info, state)
+    # used internally
+    def self._set_state!(env, state)
+      raise "Invalid state: #{state.inspect}" unless ACCEPTABLE_STATES.include? state
+      info = env[ENV_INFO_KEY]
       return if FINAL_STATES.include? info.state
       info.state = state
-      ms         = ->(s) { '%.fms' % (s * 1000) }
-      s          = 'source=rack-timeout'
-      s << ' id='       << info.id           if info.id
-      s << ' age='      << ms[info.age]      if info.age
-      s << ' timeout='  << ms[info.timeout]  if info.timeout
-      s << ' duration=' << ms[info.duration] if info.duration
-      s << ' state='    << info.state.to_s   if info.state
-      s << "\n"
-
-      $stderr << s
+      notify_state_change_observers(env)
     end
 
-    class AbortionReporter
+    # 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_reporting_abortion_state_in_env(env) { @app.call(env) }
+        Rack::Timeout._perform_block_tracking_timeout_to_env(env) { @app.call(env) }
       end
     end
 
+
+    ### state change notification-related methods
+
+    OBSERVER_CALLBACK_METHOD_NAME = :rack_timeout_request_did_change_state_in
+    @state_change_observers       = {}
+
+    # Registers an object or a block to be called back when a request changes state in rack-timeout.
+    #
+    # `id` is anything that uniquely identifies this particular callback, mostly so it may be removed via `unregister_state_change_observer`.
+    #
+    # The second parameter can be either an object that responds to `rack_timeout_request_did_change_state_in(env)` or a block. The object and the block cannot be both specified at the same time.
+    #
+    # Example calls:
+    #     Rack::Timeout.register_state_change_observer(:foo_reporter, FooStateReporter.new)
+    #     Rack::Timeout.register_state_change_observer(:bar) { |env| do_bar_things(env) }
+    def self.register_state_change_observer(id, object = nil, &callback)
+      raise RuntimeError,  "An observer with the id #{id.inspect} is already set." if @state_change_observers.key? id
+      raise ArgumentError, "Pass either a callback object or a block; never both." unless [object, callback].compact.length == 1
+      raise RuntimeError,  "Object must respond to rack_timeout_request_did_change_state_in" if object && !object.respond_to?(OBSERVER_CALLBACK_METHOD_NAME)
+      callback.singleton_class.send :alias_method, OBSERVER_CALLBACK_METHOD_NAME, :call if callback
+      @state_change_observers[id] = object || callback
+    end
+
+    # Removes the observer with the given id
+    def self.unregister_state_change_observer(id)
+      @state_change_observers.delete id
+    end
+
+
+    private
+
+    # Sends out the notifications. Called internally at the end of `set_state!`
+    def self.notify_state_change_observers(env)
+      @state_change_observers.values.each { |observer| observer.send(OBSERVER_CALLBACK_METHOD_NAME, env) }
+    end
+
   end
 end

data/lib/rack/timeout/logger.rb

@@ -0,0 +1,72 @@
+require 'logger'
+
+module Rack
+  class Timeout
+
+    # convenience method so the current logger can be accessed via Rack::Timeout.logger
+    def self.logger
+      @state_change_observers[:logger]
+    end
+
+    class StateChangeLogger < ::Logger
+      SIMPLE_FORMATTER = ->(severity, timestamp, progname, msg) { "#{msg} at=#{severity.downcase}\n" }
+      DEFAULT_LEVEL    = INFO
+      STATE_LOG_LEVEL  = { ready:     INFO,
+                           completed: INFO,
+                           expired:   ERROR,
+                           timed_out: ERROR,
+                         }
+
+
+      # creates a logger and registers for state change notifications in Rack::Timeout
+      def self.register!(*a)
+        new(*a).register!
+      end
+
+      # registers for state change notifications in Rack::Timeout
+      def register!(target = ::Rack::Timeout)
+        target.register_state_change_observer(:logger, self)
+      end
+
+      def initialize(device = $stderr, *a)
+        super(device, *a)
+        self.formatter = SIMPLE_FORMATTER
+        self.level     = self.class.determine_level
+      end
+
+      # callback method from Rack::Timeout state change notifications
+      def rack_timeout_request_did_change_state_in(env)
+        log_state_change(env[ENV_INFO_KEY])
+      end
+
+
+      private
+
+      # log level is, by precedence, one of: $RACK_TIMEOUT_LOG_LEVEL > $LOG_LEVEL > INFO
+      def self.determine_level
+        env_log_level = ENV.values_at("RACK_TIMEOUT_LOG_LEVEL", "LOG_LEVEL").compact.map(&:upcase).first
+        env_log_level = const_get(env_log_level) if env_log_level && const_defined?(env_log_level)
+        env_log_level || DEFAULT_LEVEL
+      end
+
+      # helper method used for formatting in #log_state_change
+      def ms(s)
+        '%.fms' % (s * 1000)
+      end
+
+      # generates the actual log string
+      def log_state_change(info)
+        add(STATE_LOG_LEVEL[info.state]) do
+          s  = 'source=rack-timeout'
+          s << ' id='       << info.id           if info.id
+          s << ' age='      << ms(info.age)      if info.age
+          s << ' timeout='  << ms(info.timeout)  if info.timeout
+          s << ' duration=' << ms(info.duration) if info.duration
+          s << ' state='    << info.state.to_s   if info.state
+          s
+        end
+      end
+
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-timeout
 version: !ruby/object:Gem::Version
-  version: 0.1.0beta
+  version: 0.1.0beta2
 platform: ruby
 authors:
 - Caio Chassot
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-26 00:00:00.000000000 Z
+date: 2013-05-08 00:00:00.000000000 Z
 dependencies: []
 description: Rack middleware which aborts requests that have been running for longer
   than a specified timeout.
@@ -19,6 +19,7 @@ extra_rdoc_files: []
 files:
 - MIT-LICENSE
 - README.markdown
+- lib/rack/timeout/logger.rb
 - lib/rack/timeout.rb
 - lib/rack-timeout.rb
 homepage: http://github.com/kch/rack-timeout