rack-timeout 0.1.0beta3 → 0.1.0beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d8cadc6366c07e2e809ab55bbcbc66ea82e387cd
-  data.tar.gz: 600c25828d8e91b1556cd4b458833e109c02788d
+  metadata.gz: 36207506f9394cfa73916a31f64a957c79677931
+  data.tar.gz: 5da1c876b06d0e29cd507aac3d2374d8006e2a36
 SHA512:
-  metadata.gz: a4f2117b12ddac87a0398622924219d12eaf84ec11fbcbb55e31f8fa9163eb579a1cb4c7a61d6ec3c0011de3699cf83a1688c80d40de173d1235294fa4b83184
-  data.tar.gz: b54a7b0085fbefa6ecad6e2438b7ec6c99ba3c907a806ef34b8b6e2238b442dd9050e92a47aa9e738138467c081f0965419f085950570d6316bd8fa3d6aa4959
+  metadata.gz: 9035faeb15e556cc8a908124e81a2f4b76440baee9e77ed68f7685730bedb670928631db0def7c356ef3c2dc61924bc72f7261139f70e37f6f41f3b4b282d197
+  data.tar.gz: c08a2cd396936bad0970a21f251da1fd5c573cf3585b77d954a149f8b75230b03fbe4677f009690052c26d97d2b85d07bd812b818db324c1e255d197052a8fba

data/README.markdown

@@ -1,5 +1,4 @@
-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.
+README is not very out-of-date for this release. Lots of comments in source though. README updates coming before next release.
 
 Rack::Timeout
 =============
@@ -101,13 +100,13 @@ containing the following fields:
 *   `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.
+*   `wait`: 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. This is
+*   `service`: 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.
 
@@ -225,14 +224,14 @@ but can be removed by unregistering its observer:
 
 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
+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 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
+    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
 
 (IDs shortened for readability.)
 

data/lib/rack-timeout.rb

@@ -8,4 +8,4 @@ if defined?(Rails) && [3,4].include?(Rails::VERSION::MAJOR)
   end
 end
 
-Rack::Timeout::StateChangeLogger.register!
+Rack::Timeout::StageChangeLoggingObserver.register!

data/lib/rack/timeout.rb

@@ -3,51 +3,102 @@ require 'securerandom'
 
 module Rack
   class Timeout
-    class Error < RuntimeError;        end
-    class RequestExpiryError  < Error; end
-    class RequestTimeoutError < Error; end
-
-    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 Error < RuntimeError;        end # superclass for the following…
+    class RequestExpiryError  < Error; end # raised when a request is dropped without being given a chance to run (because too old)
+    class RequestTimeoutError < Error; end # raised when a request has run for too long
+
+    RequestDetails = Struct.new(
+      :id,        # a unique identifier for the request. informative-only.
+      :wait,      # seconds the request spent in the web server before being serviced by rack
+      :service,   # time rack spent processing the request (updated ~ every second)
+      :timeout,   # the actual computed timeout to be used for this request
+      :state,     # the request's current state, see below:
+      )
+    VALID_STATES = [
+      :expired,   # The request was too old by the time it reached rack (see wait_timeout, wait_overtime)
+      :ready,     # We're about to start processing this request
+      :active,    # This request is currently being handled
+      :timed_out, # This request has run for too long and we're raising a timeout error in it
+      :completed, # We're done with this request (also set after having timed out a request)
+      ]
+    ENV_INFO_KEY = 'rack-timeout.info' # key under which each request's RequestDetails instance is stored in its env.
+
+    # helper methods to setup getter/setters for timeout properties. Ensure they're always positive numbers or false. When set to false (or 0), their behaviour is disabled.
     class << self
-      attr_accessor :timeout
+      def set_timeout_property(property_name, value)
+        unless value == false || (value.is_a?(Numeric) && value >= 0)
+          raise ArgumentError, "value for #{property_name} should be false, zero, or a positive number."
+        end
+        value = false if value.zero? # zero means we're disabling the feature
+        instance_variable_set("@#{property_name}", value)
+      end
+
+      def timeout_property(property_name, start_value)
+        singleton_class.instance_eval do
+          attr_reader property_name
+          define_method("#{property_name}=") { |v| set_timeout_property(property_name, v) }
+        end
+        set_timeout_property(property_name, start_value)
+      end
+    end
+
+    # all values are in seconds
+    timeout_property :wait_timeout,    30 # How long the request is allowed to have waited before reaching rack. If exceeded, the request is 'expired', i.e. dropped entirely without being passed down to the application.
+    timeout_property :wait_overtime,   60 # Additional time over @wait_timeout for requests with a body, like POST requests. These may take longer to be received by the server before being passed down to the application, but should not be expired.
+    timeout_property :service_timeout, 15 # How long the application can take to complete handling the request once it's passed down to it.
+
+    class << self
+      alias_method :timeout=, :service_timeout= # legacy compatibility setter
+      attr_accessor :service_past_wait    # when false, reduces the request's computed timeout from the service_timeout value if the complete request lifetime (wait + service) would have been longer than wait_timeout (+ wait_overtime when applicable). When true, always uses the service_timeout value.
+      @service_past_wait = false          # we default to false under the assumption that the router would drop a request that's not responded within wait_timeout, thus being there no point in servicing beyond seconds_service_left (see code further down) up until service_timeout.
     end
 
     def initialize(app)
       @app = app
     end
 
+    RT = self # shorthand reference
     def call(env)
-      info          = env[ENV_INFO_KEY] ||= RequestDetails.new
-      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_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, "Request older than #{MAX_REQUEST_AGE} seconds."
+      info      = (env[ENV_INFO_KEY] ||= RequestDetails.new)
+      info.id ||= env['HTTP_X_REQUEST_ID'] || SecureRandom.hex
+
+      time_started_service = Time.now                      # The time the request started being processed by rack
+      time_started_wait    = RT._read_x_request_start(env) # The time the request was initially receibed by the web server (if available)
+      effective_overtime   = (RT.wait_overtime && RT._request_has_body?(env)) ? RT.wait_overtime : 0 # additional wait timeout (if set and applicable)
+      seconds_service_left = nil
+
+      # if X-Request-Start is present and wait_timeout is set, expire requests older than wait_timeout (+wait_overtime when applicable)
+      if time_started_wait && RT.wait_timeout
+        seconds_waited          = time_started_service - time_started_wait # how long it took between the web server first receiving the request and rack being able to handle it
+        seconds_waited          = 0 if seconds_waited < 0                  # make up for potential time drift between the routing server and the application server
+        final_wait_timeout      = RT.wait_timeout + effective_overtime     # how long the request will be allowed to have waited
+        seconds_service_left    = final_wait_timeout - seconds_waited      # first calculation of service timeout (relevant if request doesn't get expired, may be overriden later)
+        info.wait, info.timeout = seconds_waited, final_wait_timeout       # updating the info properties; info.timeout will be the wait timeout at this point
+        if seconds_service_left <= 0 # expire requests that have waited for too long in the queue (as they are assumed to have been dropped by the web server / routing layer at this point)
+          RT._set_state! env, :expired
+          raise RequestExpiryError, "Request older than #{final_wait_timeout} seconds."
+        end
       end
 
-      Rack::Timeout._set_state! env, :ready
-      ready_time = Time.now
+      # pass request through if service_timeout is false (i.e., don't time it out at all.)
+      return @app.call(env) unless RT.service_timeout
+
+      # compute actual timeout to be used for this request; if service_past_wait is true, this is just service_timeout. If false (the default), and wait time was determined, we'll use the shortest value between seconds_service_left and service_timeout. See comment above at service_past_wait for justification.
+      info.timeout = RT.service_timeout # nice and simple, when service_past_wait is true, not so much otherwise:
+      info.timeout = seconds_service_left if !RT.service_past_wait && seconds_service_left && seconds_service_left > 0 && seconds_service_left < RT.service_timeout
 
+      RT._set_state! env, :ready
       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
+            info.service  = Time.now - time_started_service
+            sleep_seconds = [1 - (info.service % 1), info.timeout - info.service].min
             break if sleep_seconds <= 0
-            Rack::Timeout._set_state! env, :active
+            RT._set_state! env, :active
             sleep(sleep_seconds)
           end
-          Rack::Timeout._set_state! env, :timed_out
+          RT._set_state! env, :timed_out
           app_thread.raise(RequestTimeoutError, "Request ran for longer than #{info.timeout} seconds.")
         end
         response = @app.call(env)
@@ -56,53 +107,69 @@ module Rack
         timeout_thread.join
       end
 
-      info.duration = Time.now - ready_time
-      Rack::Timeout._set_state! env, :completed
+      info.service = Time.now - time_started_service
+      RT._set_state! env, :completed
       response
     end
 
-    # used internally
+    ### following methods are used internally (called by instances, so can't be private. _ marker should discourage people from calling them)
+
+    # X-Request-Start contains the time the request was first seen by the server. Format varies wildly amongst servers, yay!
+    #   - nginx gives the time since epoch as seconds.milliseconds[1]. New Relic documentation recommends preceding it with t=[2], so might as well detect it.
+    #   - Heroku gives the time since epoch in milliseconds. [3]
+    #   - Apache uses t=microseconds[4], so we're not even going there.
+    #
+    # The sane way to handle this would be by knowing the server being used, instead let's just hack around with regular expressions and ignore apache entirely.
+    # [1]: http://nginx.org/en/docs/http/ngx_http_log_module.html#var_msec
+    # [2]: https://docs.newrelic.com/docs/apm/other-features/request-queueing/request-queue-server-configuration-examples#nginx
+    # [3]: https://devcenter.heroku.com/articles/http-routing#heroku-headers
+    # [4]: http://httpd.apache.org/docs/current/mod/mod_headers.html#header
+    #
+    # 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+)$/
+    def self._read_x_request_start(env)
+      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
+
+    # This method determines if a body is present. requests with a body (generally POST, PUT) can have a lengthy body which may have taken a while to be received by the web server, inflating their computed wait time. This in turn could lead to unwanted expirations. See wait_overtime property as a way to overcome those.
+    # This is a code extraction for readability, this method is only called from a single point.
+    def self._request_has_body?(env)
+      return true  if env['HTTP_TRANSFER_ENCODING'] == 'chunked'
+      return false if env['CONTENT_LENGTH'].nil?
+      return false if env['CONTENT_LENGTH'].to_i.zero?
+      true
+    end
+
     def self._set_state!(env, state)
       raise "Invalid state: #{state.inspect}" unless VALID_STATES.include? state
-      info = env[ENV_INFO_KEY]
-      info.state = state
+      env[ENV_INFO_KEY].state = state
       notify_state_change_observers(env)
     end
 
-
     ### state change notification-related methods
+    @state_change_observers = {}
 
-    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.
+    # Registers a block to be called back when a request changes state in rack-timeout. The block will receive the request's env.
     #
     # `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
+    def self.register_state_change_observer(id, &callback)
+      raise RuntimeError, "An observer with the id #{id.inspect} is already set." if @state_change_observers.key? id
+      raise ArgumentError, "A callback block is required." unless callback
+      @state_change_observers[id] = callback
     end
 
     # Removes the observer with the given id
     def self.unregister_state_change_observer(id)
-      @state_change_observers.delete id
+      @state_change_observers.delete(id)
     end
 
-
     private
-
-    # Sends out the notifications. Called internally at the end of `set_state!`
+    # 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) }
+      @state_change_observers.values.each { |observer| observer.call(env) }
     end
 
   end

data/lib/rack/timeout/logger.rb

@@ -1,73 +1,63 @@
 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]
+class Rack::Timeout
+  class StageChangeLoggingObserver
+    STATE_LOG_LEVEL = { :expired   => :error,
+                        :ready     => :info,
+                        :active    => :debug,
+                        :timed_out => :error,
+                        :completed => :info,
+                      }
+
+    # creates a logger and registers for state change notifications in Rack::Timeout
+    def self.register!(logger = nil)
+      new.register!(logger)
     end
 
-    class StateChangeLogger < ::Logger
-      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,
-                         }
-
-
-      # 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
+    # registers for state change notifications in Rack::Timeout (or other explicit target (potentially useful for testing))
+    def register!(logger = nil, target = ::Rack::Timeout)
+      @logger = logger
+      target.register_state_change_observer(:logger, &method(:log_state_change))
+    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])
+    SIMPLE_FORMATTER = ->(severity, timestamp, progname, msg) { "#{msg} at=#{severity.downcase}\n" }
+    def self.mk_logger(device, level = ::Logger::INFO)
+      ::Logger.new(device).tap do |logger|
+        logger.level     = level
+        logger.formatter = SIMPLE_FORMATTER
       end
+    end
 
+    class << self
+      attr_accessor :logger
+    end
+    def logger(env = nil)
+      self.class.logger ||
+        (defined?(::Rails) && Rails.logger) ||
+        (env && env['rack.logger'])         ||
+        (env && env['rack.errors'] && self.class.mk_logger(env['rack.errors'])) ||
+        (@fallback_logger ||= self.class.mk_logger($stderr))
+    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
+    # 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
+    # generates the actual log string
+    def log_state_change(env)
+      info = env[ENV_INFO_KEY]
+      level = STATE_LOG_LEVEL[info.state]
+      logger(env).send(level) do
+        s  = 'source=rack-timeout'
+        s << ' id='      << info.id          if info.id
+        s << ' wait='    << ms(info.wait)    if info.wait
+        s << ' timeout=' << ms(info.timeout) if info.timeout
+        s << ' service=' << ms(info.service) if info.service
+        s << ' state='   << info.state.to_s  if info.state
+        s
       end
-
     end
+
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-timeout
 version: !ruby/object:Gem::Version
-  version: 0.1.0beta3
+  version: 0.1.0beta4
 platform: ruby
 authors:
 - Caio Chassot
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-01 00:00:00.000000000 Z
+date: 2014-09-30 00:00:00.000000000 Z
 dependencies: []
 description: Rack middleware which aborts requests that have been running for longer
   than a specified timeout.
@@ -19,9 +19,9 @@ extra_rdoc_files: []
 files:
 - MIT-LICENSE
 - README.markdown
-- lib/rack/timeout/logger.rb
-- lib/rack/timeout.rb
 - lib/rack-timeout.rb
+- lib/rack/timeout.rb
+- lib/rack/timeout/logger.rb
 homepage: http://github.com/kch/rack-timeout
 licenses:
 - MIT
@@ -32,17 +32,17 @@ 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: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Abort requests that are taking too long