right_support 2.10.1 → 2.11.2

data/lib/right_support/rack/request_logger.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2012 RightScale Inc
+# Copyright (c) 2012-2016 RightScale Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -35,20 +35,60 @@ module RightSupport::Rack
   # with Rack::Logger or another middleware that provides logging services.
   class RequestLogger
 
-    # Initialize an instance of the middleware, optionally providing a whitelist (:only) or
-    # a blacklist (:except) of path regexps to which request logging will apply.
-    #
-    # @param [Object] app inner application or middleware layer; must respond to #call
+    # limit exception backtrace length; usually only the first few lines are
+    # significant. the same error dumped repeatedly can make grepping difficult.
+    BACKTRACE_LIMIT = 10
+
+    # for debug-mode only logging. debug-mode can also be enabled by the
+    # "X-Debug=<anything>" header.
+    DEBUG_MODE_ENV_KEY     = 'rack.debug-mode'.freeze
+    DEBUG_MODE             = ::ENV['DEBUG_MODE'] == 'true'
+    DEBUG_MODE_HTTP_HEADER = 'HTTP_X_DEBUG'
+
+    # defaults to STDERR by Rack but usually overridden to use syslog, etc.
+    RACK_LOGGER = 'rack.logger'.freeze
+
+    # indicates whether current request is enabled for logging by filter, etc.
+    RACK_LOGGING_ENABLED = 'rack.logging.enabled'.freeze
+
+    # list of status codes that are 'normalized' when :normalize_40x=true
+    # normalization means stripping any developer-provided details to avoid
+    # leaking information about the service. overridden by DEBUG_MODE=true but
+    # specifically *not* affected by the 'X-Debug' header.
+    NORMALIZE_40X = [401, 403, 404]
+
+    # Initialize an instance of the middleware, optionally providing a whitelist
+    #  (:only) or a blacklist (:except) of path regexps to which request logging
+    #  will apply.
     #
-    # @option options [Array] :only log for these path Regexps unless in debug mode
-    # @option options [Array] :except log except for these path Regexps unless in debug mode; this option is ignored if :only is provided
-    # @option options [Array] :include_query_string log the contents of the query string
+    # @param [Object] app inner application or middleware layer; must respond to
+    #  #call.
+    # @param [Hash] options
+    # @option options [Array] :only log for these path Regexps unless in debug
+    #  mode.
+    # @option options [Array] :except log except for these path Regexps unless
+    #  in debug mode; this option is ignored if :only is provided.
+    # @option options [Array] :include_query_string log the contents of the
+    #  query string.
+    # @option options [Logger] :logger to override any previously set logger or
+    #  nil. Rack sets a STDERR logger by default or it may be set by other
+    #  framework middleware so this is only for when those are not used.
+    # @option options [TrueClass|FalseClass] :normalize_40x to remove detail
+    #  from some 40x responses for security reasons. default=false.
+    # @option options [TrueClass|FalseClass] :normalize_40x_set_cookie to
+    #  override the usual global session behavior of always responding with a
+    #  'Set-Cookie' header regardless of status code. defaults to having the
+    #  same value as the :normalize_40x option.
     def initialize(app, options = {})
       @app = app
       @only = options[:only] || []
       @except = options[:except] || []
       # by default we don't log the query string contents because it may have sensitive data.
       @include_query_string = options[:include_query_string] || false
+      @logger = options[:logger]
+      @normalize_40x = !!options[:normalize_40x]
+      @normalize_40x_set_cookie = options[:normalize_40x_set_cookie]
+      @normalize_40x_set_cookie = @normalize_40x if @normalize_40x_set_cookie.nil?
     end
 
     # Add a logger to the Rack environment and call the next middleware.
@@ -67,25 +107,154 @@ module RightSupport::Rack
     # @return [Object] always returns whatever value is returned by the next
     #  layer of middleware
     def call(env)
-      logger = env["rack.logger"]
-      env["rack.logging.enabled"] = enabled = logging_enabled?(logger, env)
+      # forward-declare in case of exception.
+      enabled = true
 
+      # override logger, if necessary.
+      if @logger
+        logger = env[RACK_LOGGER] = @logger
+      else
+        logger = env[RACK_LOGGER]
+      end
+
+      # determine if debug-mode is enabled.
+      env[DEBUG_MODE_ENV_KEY] = debug_enabled?(env)
+
+      # log request only when enabled.
+      env[RACK_LOGGING_ENABLED] = enabled = logging_enabled?(logger, env)
       began_at = Time.now
       log_request_begin(logger, env) if enabled
-      status, header, body = @app.call(env)
+
+      # next
+      status, headers, body = @app.call(env)
+
+      # log exception, if necessary.
       if env['sinatra.error'] && !env['sinatra.error.handled']
+        if !enabled
+          # after the fact but better than logging exception without its request.
+          log_request_begin(logger, env)
+          enabled = true
+        end
         log_exception(logger, env['sinatra.error'])
+      elsif !enabled && env[RACK_LOGGING_ENABLED]
+        # controller can conditionally enable logging for the current request
+        # even though by default such requests are not logged. an example is a
+        # periodic request for a listing (scheduled tasks, etc.) that is only
+        # logged when not empty.
+        log_request_begin(logger, env)
+        enabled = true
       end
-      log_request_end(logger, env, status, header, body, began_at) if enabled
 
-      return [status, header, body]
+      # respond identically to some 40Xs; do not reveal any internals by
+      # varying the response headers or body (as developers tend to do for
+      # debugging reasons). public APIs will receive such requests frequently
+      # but this is generally not needed for internal APIs.
+      #
+      # note that it is important to *not* accept the "X-Debug" header override
+      # and show more information in response ;)
+      if @normalize_40x && !DEBUG_MODE && NORMALIZE_40X.include?(status)
+        # note that ::Rack::CONTENT_LENGTH was not defined before rack v1.6+ :@
+        headers = { 'Content-Length' => '0' }
+        body = []
+        env[DEBUG_MODE_ENV_KEY] = false  # disable any verbose debugging
+      end
+
+      # defeat global session renew, update and set-cookie for normalized 40x.
+      # has no effect if the app is not using global session middleware.
+      if @normalize_40x_set_cookie && NORMALIZE_40X.include?(status)
+        env['global_session.req.renew'] = false
+        env['global_session.req.update'] = false
+      end
+
+      # log response only when enabled.
+      if enabled
+        log_request_end(logger, env, status, headers, body, began_at)
+      end
+
+      return [status, headers, body]
     rescue Exception => e
+      if !enabled
+        # after the fact but better than logging exception without its request.
+        log_request_begin(logger, env)
+      end
       log_exception(logger, e)
       raise
     end
 
+    # provides a canonical representation of a header key that is acceptable to
+    # Rack, etc.
+    def self.canonicalize_header_key(key)
+      key.downcase.gsub('_', '-')
+    end
+
+    # @return [String] header value by canonical key name, if present.
+    def self.header_value_get(headers, key)
+      return nil unless headers
+      key = canonicalize_header_key(key)
+      value = nil
+      headers.each do |k, v|
+        if canonicalize_header_key(k) == key
+          value = v
+          break
+        end
+      end
+      value
+    end
+
+    # safely sets a header value by first locating any existing key by canonical
+    # search.
+    #
+    # @param [Hash] headers to modify
+    # @param [String] key for header
+    # @param [String] value for header
+    # @return [Hash] updated headers
+    def self.header_value_set(headers, key, value)
+      headers ||= {}
+      key = canonicalize_header_key(key)
+      headers.each do |k, v|
+        if canonicalize_header_key(k) == key
+          key = k
+          break
+        end
+      end
+      headers[key] = value
+      headers
+    end
+
+    # Formats a concise error message with limited backtrace, etc.
+    #
+    # @param [Exception] e to format
+    #
+    # @return [String] formatted error
+    def self.format_exception_message(e)
+      trace = e.backtrace || []
+      if trace.size > BACKTRACE_LIMIT
+        trace = trace[0, BACKTRACE_LIMIT] << '...'
+      end
+      kind = e.class.name
+      if (msg = e.message) && !msg.empty? && msg != kind
+        kind = "#{kind}: #{msg}"
+      end
+      [kind, *trace].join("\n")
+    end
+
+    # @return [String] accepted/generated request UUID or else 'missing' to
+    #  indicate that the RequestTracker middleware is missing.
+    def self.request_uuid_from_env(env)
+      env[RequestTracker::REQUEST_UUID_ENV_NAME] || 'missing'
+    end
+
     private
 
+    # determines if debug-mode is enabled for the current request by environment
+    # variable override or by specific X-Debug header in request.
+    #
+    # note that the legacy code accepted any value for the debug header so long
+    # as it was not nil.
+    def debug_enabled?(env)
+      DEBUG_MODE || !env[DEBUG_MODE_HTTP_HEADER].nil?
+    end
+
     # Determine whether logging enabled for given request
     #
     # @param [Object] logger for Rack
@@ -96,7 +265,7 @@ module RightSupport::Rack
       path = env["PATH_INFO"]
 
       # the request can always ask for debugging
-      if env["HTTP_X_DEBUG"]
+      if env[DEBUG_MODE_ENV_KEY]
         true
       # some apps have a blacklist of boring requests (e.g. health checks)
       elsif @except.any? { |e| e.is_a?(Regexp) ? (path =~ e) : (path == e) }
@@ -110,6 +279,12 @@ module RightSupport::Rack
       end
     end
 
+    # @return [String] accepted/generated request UUID or else 'missing' to
+    #  indicate that the RequestTracker middleware is missing.
+    def request_uuid_from_env(env)
+      self.class.request_uuid_from_env(env)
+    end
+
     # Log beginning of request
     #
     # @param [Object] logger for Rack
@@ -137,24 +312,20 @@ module RightSupport::Rack
         cookie = env['global_session']
         info = [ env['global_session'].id,
                  cookie.keys.map{|k| %{"#{k}"=>"#{cookie[k]}"} }.join(', ') ]
-        sess = %Q{Session ID: %s  Session Data: {%s}} % info
+        sess = %Q{Session ID: %s, Session Data: {%s}, } % info
       else
         sess = ""
       end
 
-      shard_info = 'Shard: ' + (env['HTTP_X_SHARD'] || 'default').to_s + ';'
-
-      params = [
+      logger.info '[%s] Started %s "%s%s" (for %s), %sShard: %s' % [
+        request_uuid_from_env(env),
         env['REQUEST_METHOD'],
         env['PATH_INFO'],
         query_info,
         remote_addr,
         sess,
-        shard_info,
-        env['rack.request_uuid'] || ''
+        env['HTTP_X_SHARD'] || 'default'
       ]
-
-      logger.info 'Processing %s "%s%s" (for %s)  %s %s Request ID: %s' % params
     end
 
     # Log end of request
@@ -167,30 +338,39 @@ module RightSupport::Rack
     # @return [TrueClass] always true
     def log_request_end(logger, env, status, headers, body, began_at)
       duration = (Time.now - began_at) * 1000
-
-      # Downcase keys in the headers Hash for case-insensitive comparisons
-      safe_headers = Hash[*headers.map {|k,v| [k.downcase, v]}.flatten]
-
-      content_length = if safe_headers['content-length']
-        safe_headers['content-length']
-      else
-        if body.is_a?(Array)
-          body.reduce(0) {|accum, e| accum += e.bytesize}
-        elsif body.is_a?(String)
-          body.bytesize
+      unless content_length = self.class.header_value_get(headers, 'Content-Length')
+        case body
+        when Array
+          content_length = body.reduce(0) {|accum, e| accum += e.bytesize}
+        when String
+          content_length = body.bytesize
         else
-          '-'
+          content_length = '-'
         end
       end
 
-      params = [
+      request_uuid = request_uuid_from_env(env)
+      logger.info '[%s] Completed in %dms | %s | %s bytes' % [
+        request_uuid,
         duration,
         "#{status} #{Rack::Utils::HTTP_STATUS_CODES[status]}",
-        content_length.to_s,
-        env['rack.request_uuid'] || ''
+        content_length.to_s
       ]
 
-      logger.info 'Completed in %dms | %s | %s bytes | Request ID: %s' % params
+      # more detail, if appropriate.
+      if env[DEBUG_MODE_ENV_KEY] && logger.debug?
+        unless headers.nil? || headers.empty?
+          logger.debug("[#{request_uuid}] #{headers.inspect}")
+        end
+        unless body.nil? || body.empty?
+          body = Array(body) unless body.respond_to?(:each)
+          body.each do |b|
+            b = b.to_s.strip
+            logger.debug("[#{request_uuid}] #{b}") unless b.empty?
+          end
+        end
+      end
+      true
     end
 
     # Log exception
@@ -199,11 +379,10 @@ module RightSupport::Rack
     # @param [Exception] exception to be logged
     #
     # @return [TrueClass] always true
-    def log_exception(logger, exception)
-      msg = ["#{exception.class} - #{exception.message}", *exception.backtrace].join("\n")
-      logger.error(msg)
+    def log_exception(logger, e)
+      logger.error(self.class.format_exception_message(e))
     rescue
-      #no-op, something is seriously messed up by this point...
+      # no-op; something is seriously messed up by this point...
     end
   end
 end

data/lib/right_support/rack/request_tracker.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2011 RightScale Inc
+# Copyright (c) 2011-2016 RightScale Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,43 +21,130 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module RightSupport::Rack
-  # TODO docs
+
+  # middleware to detect a request ID header or generate a new ID for each
+  # incoming request. the purpose is to track a request lineage throughout a
+  # chain of internal API calls and, in some cases, out to external APIs that
+  # also support the X-Request-ID header as a de-facto standard (google it).
   class RequestTracker
-    REQUEST_LINEAGE_UUID_HEADER = "HTTP_X_REQUEST_LINEAGE_UUID".freeze
-    REQUEST_UUID_HEADER         = "X-Request-Uuid".freeze
-    REQUEST_UUID_ENV_NAME       = "rack.request_uuid".freeze
-    UUID_SEPARATOR              = " ".freeze
+    # shorthand
+    Generator = ::RightSupport::Data::Token
 
-    # Make a new Request tracker.
-    #
-    # Tags the requset with a new request UUID
-    #
-    # === Parameters
-    # app(Rack client): application to run
+    # used by many public services to represent a client-generated request ID
+    # that can be tracked and safely logged throughout the lineage of a request.
+    # this is also supported by goa middleware.
+    REQUEST_ID_HEADER = 'X-Request-Id'.freeze
+
+    # incoming header as found in Rack env hash, if any.
+    HTTP_REQUEST_ID_HEADER = 'HTTP_X_REQUEST_ID'.freeze
+
+    # LEGACY: still supported but new code should use the standard (see above).
+    REQUEST_UUID_HEADER = "X-Request-Uuid".freeze
+
+    # LEGACY: incoming header as found in Rack env hash, if any.
+    HTTP_REQUEST_UUID_HEADER = 'HTTP_X_REQUEST_UUID'.freeze
+
+    # LEGACY: refers to the generated or passed-in request ID. the key has been
+    # hardcoded in some places so is not easy to change and/or there is not much
+    # value to finding and replacing with _id in all cases.
+    REQUEST_UUID_ENV_NAME = 'rack.request_uuid'.freeze
+
+    # @deprecated do not send the lineage header as support may go away.
+    REQUEST_LINEAGE_UUID_HEADER = 'HTTP_X_REQUEST_LINEAGE_UUID'.freeze
+
+    # @deprecated do not send the lineage header as support may go away.
+    UUID_SEPARATOR = ' '.freeze
+
+    # limit request [UU]ID to something reasonable to keep our logs from
+    # overflowing on bad user-provided IDs. we do not want to be too restrictive
+    # in case people are encoding some useful information, etc. the issue is
+    # that the request ID will tend to show up a lot in logs.
+    MAX_REQUEST_UUID_LENGTH = 128
+
+    # @param [Object] app as next middleware or the rack application
     def initialize(app)
       @app = app
     end
 
+    # request tracking.
+    #
+    # @param [Hash] env from preceding middleware
+    #
+    # @return [Array] tuple of [status, headers, body]
     def call(env)
-      if env.has_key? REQUEST_LINEAGE_UUID_HEADER
-        request_uuid = env[REQUEST_LINEAGE_UUID_HEADER] + UUID_SEPARATOR +
-                       generate_request_uuid
-      else
-        request_uuid = generate_request_uuid
-      end
-
+      request_uuid, response_header_name = self.class.detect_request_uuid(env)
       env[REQUEST_UUID_ENV_NAME] = request_uuid
 
       status, headers, body = @app.call(env)
 
-      headers[REQUEST_UUID_HEADER] = request_uuid
-      [status, headers,body]
+      headers[response_header_name] = request_uuid
+      [status, headers, body]
     end
 
+    # detects whether the incoming env hash contains a request ID is some form
+    # and generates a new ID when missing.
+    #
+    # @return [Array] tuple of detected/generated ID and the name of the header
+    #  to use to represent the ID in a response.
+    def self.detect_request_uuid(env)
+      request_uuid = ''
+      response_header_name = nil
+      {
+        HTTP_REQUEST_ID_HEADER => REQUEST_ID_HEADER,
+        HTTP_REQUEST_UUID_HEADER => REQUEST_UUID_HEADER,
+        REQUEST_LINEAGE_UUID_HEADER => REQUEST_UUID_HEADER
+      }.each do |in_key, out_key|
+        if env.has_key?(in_key)
+          request_uuid = env[in_key].to_s.strip
+          response_header_name = out_key
+          break
+        end
+      end
+
+      # for legacy reasons we default to the -UUID header in response for newly-
+      # generated IDs. we will use the -ID standard if that was passed-in. once
+      # all apps are updated you will mostly see -ID in response except for API
+      # calls initiated by browser code. the javascript can gradually be changed
+      # to send -ID with requests as well.
+      if request_uuid.empty?
+        request_uuid = generate_request_uuid
+        response_header_name = REQUEST_UUID_HEADER
+      else
+        # truncate, if necessary.
+        request_uuid = request_uuid[0, MAX_REQUEST_UUID_LENGTH]
+      end
 
-    def generate_request_uuid
-      ::RightSupport::Data::UUID.generate
+      return request_uuid, response_header_name
+    end
+
+    # copies the request [UU]ID from the request environment to the given hash,
+    # if present. does nothing if request [UU]ID is not set (because middleware
+    # was not present, etc.)
+    #
+    # @param [Hash] from_env as source
+    # @param [Hash] to_headers as target
+    #
+    # @return [Hash] updated headers
+    def self.copy_request_uuid(from_env, to_headers)
+      to_headers ||= {}
+      if from_env
+        if request_uuid = from_env[REQUEST_UUID_ENV_NAME]
+          # note we always forward the _ID header as the standard. none of the
+          # RS code ever actually accepted the _UUID header so that is a
+          # non-issue.
+          to_headers[REQUEST_ID_HEADER] = request_uuid
+        end
+      end
+      to_headers
+    end
+
+    # generates a token (nicer than an actual UUID for logging) but we continue
+    # to refer to it as the "request UUID" for legacy reasons.
+    #
+    # @return [String] a new token
+    def self.generate_request_uuid
+      Generator.generate
     end
-  end
 
-end
+  end # RequestTracker
+end # RightSupport::Rack

data/right_support.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: right_support 2.10.1 ruby lib
+# stub: right_support 2.11.2 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "right_support"
-  s.version = "2.10.1"
+  s.version = "2.11.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Tony Spataro", "Sergey Sergyenko", "Ryan Williamson", "Lee Kirchhoff", "Alexey Karpik", "Scott Messier"]
-  s.date = "2016-06-01"
+  s.date = "2016-07-08"
   s.description = "A toolkit of useful, reusable foundation code created by RightScale."
   s.email = "support@rightscale.com"
   s.extra_rdoc_files = [
@@ -58,6 +58,7 @@ Gem::Specification.new do |s|
     "lib/right_support/data/hash_tools.rb",
     "lib/right_support/data/mash.rb",
     "lib/right_support/data/serializer.rb",
+    "lib/right_support/data/token.rb",
     "lib/right_support/data/unknown_type.rb",
     "lib/right_support/data/uuid.rb",
     "lib/right_support/db.rb",
@@ -70,6 +71,7 @@ Gem::Specification.new do |s|
     "lib/right_support/log/mixin.rb",
     "lib/right_support/log/multiplexer.rb",
     "lib/right_support/log/null_logger.rb",
+    "lib/right_support/log/step_level_logger.rb",
     "lib/right_support/log/syslog/remote.rb",
     "lib/right_support/log/system_logger.rb",
     "lib/right_support/net.rb",
@@ -77,6 +79,7 @@ Gem::Specification.new do |s|
     "lib/right_support/net/dns.rb",
     "lib/right_support/net/http_client.rb",
     "lib/right_support/net/lb.rb",
+    "lib/right_support/net/lb/base.rb",
     "lib/right_support/net/lb/health_check.rb",
     "lib/right_support/net/lb/round_robin.rb",
     "lib/right_support/net/lb/sticky.rb",
@@ -107,6 +110,7 @@ Gem::Specification.new do |s|
     "spec/crypto/signed_hash_spec.rb",
     "spec/data/hash_tools_spec.rb",
     "spec/data/mash_spec.rb",
+    "spec/data/token_spec.rb",
     "spec/data/uuid_spec.rb",
     "spec/db/cassandra_model_part1_spec.rb",
     "spec/db/cassandra_model_part2_spec.rb",
@@ -122,13 +126,14 @@ Gem::Specification.new do |s|
     "spec/log/mixin_spec.rb",
     "spec/log/multiplexer_spec.rb",
     "spec/log/null_logger_spec.rb",
+    "spec/log/step_level_logger_spec.rb",
     "spec/log/system_logger_spec.rb",
     "spec/net/address_helper_spec.rb",
-    "spec/net/balancing/health_check_spec.rb",
-    "spec/net/balancing/round_robin_spec.rb",
-    "spec/net/balancing/sticky_policy_spec.rb",
     "spec/net/dns_spec.rb",
     "spec/net/http_client_spec.rb",
+    "spec/net/lb/health_check_spec.rb",
+    "spec/net/lb/round_robin_spec.rb",
+    "spec/net/lb/sticky_spec.rb",
     "spec/net/request_balancer_spec.rb",
     "spec/net/s3_helper_spec.rb",
     "spec/net/ssl_spec.rb",

data/spec/data/token_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe RightSupport::Data::Token do
+
+  context :generate do
+    let(:match) { /^[0-9a-zA-Z]{13}$/ }
+
+    subject { described_class }
+
+    it 'generates UUIDs' do
+      seen = {}
+      100.times do
+        actual = subject.generate
+        actual.should =~ match
+        seen[actual].should be_nil
+        seen[actual] = true
+      end
+    end
+  end
+
+end