global_session 3.0.5 → 3.1.0

data/lib/global_session/configuration.rb

@@ -19,6 +19,8 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
+require 'yaml'
+
 module GlobalSession
   # Central point of access for GlobalSession configuration information. This is
   # mostly a very thin wrapper around the serialized hash written to the YAML config
@@ -35,8 +37,8 @@ module GlobalSession
   # * ephemeral
   # * timeout
   # * renew
-  # * authority
-  # * trust
+  # * authority (optional - inferred from presence of private key file)
+  # * trust (optional - inferred from presence/name of public key files)
   # * directory
   # * cookie
   #     * version
@@ -94,7 +96,7 @@ module GlobalSession
     def initialize(config, environment)
       if config.is_a?(Hash)
         @config = config
-      elsif File.readable?(config)
+      elsif File.file?(config)
         data = YAML.load(File.read(config))
         unless data.is_a?(Hash)
           raise TypeError, "Configuration file #{File.basename(config)} must contain a hash as its top-level element"
@@ -121,9 +123,32 @@ module GlobalSession
       get(key, true)
     end
 
+    # Writer for configuration elements. Writes to an environment-specific stanza if one is present,
+    # else writes to the common stanza. DOES NOT OVERWRITE the key's value if it already has one!
+    #
+    # @param [String] key
+    # @param optional [Object] the value to write, or empty-hash as a default
+    def []=(key, value={})
+      if @config.has_key?(@environment)
+        @config[@environment][key] ||= value
+      else
+        @config['common'][key] ||= value
+      end
+    rescue NoMethodError
+      raise MissingConfiguration, "Configuration key '#{key}' not found"
+    end
+
+    # Determine whether a given configuration key was specified.
+    #
+    # @return [Boolean] true if the key is present in the common or per-environment stanzas
+    def has_key?(k)
+      @config[@environment].has_key?(k) || @config['common'].has_key?(k)
+    end
+
+    alias key? has_key?
+
     def validate # :nodoc
-      ['attributes/signed', 'cookie/name',
-       'timeout'].each {|k| validate_presence_of k}
+      ['attributes/signed', 'cookie/name', 'timeout'].each {|k| validate_presence_of k}
     end
 
     protected
@@ -137,7 +162,12 @@ module GlobalSession
     # true always
     def validate_presence_of(key)
       elements = key.split '/'
-      object = get(elements.shift, false)
+      top_key = elements.shift
+      object = get(top_key, true) # pretend we're validated in order to get inheritance
+      if object.nil?
+        msg = "Configuration does not specify required element '#{top_key}'"
+        raise MissingConfiguration, msg
+      end
       elements.each do |element|
         object = object[element] if object
         if object.nil?
@@ -150,15 +180,32 @@ module GlobalSession
 
     private
 
+    # Get a configuration key.
+    #
+    # @return [Object] the value of the desired key
+    # @raise [MissingConfiguration] if the key is not found
+    # @param [String] key
+    # @param [Boolean] if true, check both the common and per-environment stanzas for the key
     def get(key, validated) # :nodoc
-      if @config.has_key?(@environment) &&
-         @config[@environment].has_key?(key)
-        return @config[@environment][key]
+      if validated
+        # Fancy inheritance logic
+        if ('common' == key) && @config.key?(key)
+          # The common stanza itself
+          @config[key]
+        elsif (@environment == key) && @config.key?(key)
+          # The environment-specific stanza itself
+          @config[key]
+        elsif @config.key?(@environment) && @config[@environment].key?(key)
+          # Some key in the environment-specific stanza
+          return @config[@environment][key]
+        elsif @config.key?('common') && @config['common'].key?(key)
+          # By process of elimination, some key in the common stanza
+          @config['common'][key]
+        end
       else
-        @config['common'][key]
+        # Fail sauce
+        raise MissingConfiguration, "Configuration key '#{key}' not found"
       end
-    rescue NoMethodError
-      raise MissingConfiguration, "Configuration key '#{key}' not found"
     end
   end
 end

data/lib/global_session/directory.rb

@@ -22,7 +22,7 @@
 require 'set'
 
 module GlobalSession
-  # The global session directory, which provides some lookup and decision services
+  # The global session directory, which provides lookup and decision services
   # to instances of Session.
   #
   # The default implementation is simplistic, but should be suitable for most applications.
@@ -31,28 +31,23 @@ module GlobalSession
   # setting to specify the class name of your implementation:  
   #
   #     common:
-  #       directory: MyCoolDirectory
+  #       directory:
+  #         class: MyCoolDirectory
   #
+  # == Key Management
   #
-  # === The Authority Keystore
-  # Directory uses a filesystem directory as a backing store for RSA
-  # public keys of global session authorities. The directory should
-  # contain one or more +*.pub+ files containing OpenSSH-format public
-  # RSA keys. The name of the pub file determines the name of the
-  # authority it represents.
+  # All key-related functionality has been delegated to the Keystore class as of
+  # v3.1. Directory retains its key management hooks for downrev compatibility,
+  # but mostly they are stubs for Keystore functionality.
   #
-  # === The Local Authority
-  # Directory will infer the name of the local authority (if any) by
-  # looking for a private-key file in the keystore. If a +*.key+ file
-  # is found, then its name is taken to be the name of the local
-  # authority and all GlobalSessions created will be signed by that
-  # authority's private key.
-  #
-  # If more than one key file is found, Directory will raise an error
-  # at initialization time.
+  # For more information about key mangement, please refer to the Keystore class.
   #
   class Directory
-    attr_reader :configuration, :authorities, :private_key
+    # @return [Configuration] shared configuration object
+    attr_reader :configuration
+
+    # @return [Keystore] asymmetric crypto keys for signing authorities
+    attr_reader :keystore
 
     # @return a representation of the object suitable for printing to the console
     def inspect
@@ -61,31 +56,36 @@ module GlobalSession
 
     # Create a new Directory.
     #
-    # === Parameters
-    # keystore_directory(String):: Absolute path to authority keystore
-    #
-    # === Raise
-    # ConfigurationError:: if too many or too few keys are found, or if *.key/*.pub files are malformatted
-    def initialize(configuration, keystore_directory)
+    # @param [Configuration] shared configuration
+    # @param optional [String] keystore_directory (DEPRECATED) if present, directory where keys can be found
+    # @raise [ConfigurationError] if too many or too few keys are found, or if *.key/*.pub files are malformatted
+    def initialize(configuration, keystore_directory=nil)
       @configuration = configuration
-      certs = Dir[File.join(keystore_directory, '*.pub')]
-      keys  = Dir[File.join(keystore_directory, '*.key')]
-
       @authorities = {}
-      certs.each do |cert_file|
-        basename = File.basename(cert_file)
-        authority = basename[0...(basename.rindex('.'))] #chop trailing .ext
-        @authorities[authority] = OpenSSL::PKey::RSA.new(File.read(cert_file))
-        raise ConfigurationError, "Expected #{basename} to contain an RSA public key" unless @authorities[authority].public?
-      end
 
-      if local_authority_name
-        key_file = keys.detect { |kf| kf =~ /#{local_authority_name}.key$/ }
-        raise ConfigurationError, "Key file #{local_authority_name}.key not found" unless key_file        
-        @private_key  = OpenSSL::PKey::RSA.new(File.read(key_file))
-        raise ConfigurationError, "Expected #{key_file} to contain an RSA private key" unless @private_key.private?
+      # Propagate a deprecated parameter
+      # @deprecated remove for v4.0
+      if keystore_directory.is_a?(String)
+        all_files = Dir.glob(File.join(keystore_directory, '*'))
+        public_keys = all_files.select { |kf| kf =~ /\.pub$/ }
+        raise ConfigurationError, "No public keys (*.pub) found in #{keystore_directory}" if public_keys.empty?
+
+        @configuration['common'] ||= {}
+        @configuration['common']['keystore'] ||= {}
+        @configuration['common']['keystore']['public'] = [keystore_directory]
+
+        # Propagate a deprecated configuration option
+        # @deprecated remove for v4.0
+        if (private_key = @configuration['authority'])
+          key_file = all_files.detect { |kf| kf =~ /#{private_key}\.key$/ }
+          raise ConfigurationError, "Key file #{private_key}.key not found in #{keystore_directory}" unless key_file
+          @configuration['common'] ||= {}
+          @configuration['common']['keystore'] ||= {}
+          @configuration['common']['keystore']['private'] = key_file
+        end
       end
 
+      @keystore = Keystore.new(configuration)
       @invalid_sessions = Set.new
     end
 
@@ -95,6 +95,7 @@ module GlobalSession
     # DEPRECATED: If a cookie is provided, load an existing session from its
     # serialized form. You should use #load_session for this instead.
     #
+    # @deprecated will be removed in GlobalSession v4; please use #load_session instead
     # @see load_session
     #
     # === Parameters
@@ -146,12 +147,33 @@ module GlobalSession
       Session.new(self, cookie)
     end
 
+    # @return [Hash] map of String authority-names to OpenSSL::PKey public-keys
+    # @deprecated will be removed in GlobalSession v4; please use Keystore instead
+    # @see GlobalSession::Keystore
+    def authorities
+      @keystore.public_keys
+    end
+
+    # Determine the private key associated with this directory, to be used for signing.
+    #
+    # @return [nil,OpenSSL::PKey] local authority key if we are an authority, else nil
+    # @deprecated will be removed in GlobalSession v4; please use Keystore instead
+    # @see GlobalSession::Keystore
+    def private_key
+      @keystore.private_key || @private_key
+    end
+
+    # Determine the authority name associated with this directory's private session-signing key.
+    #
+    # @deprecated will be removed in GlobalSession v4; please use Keystore instead
+    # @see GlobalSession::Keystore
     def local_authority_name
-      @configuration['authority']
+      @keystore.private_key_name || @private_key_name
     end
     
-    # Determine whether this system trusts a particular authority based on
-    # the trust settings specified in Configuration.
+    # Determine whether this system trusts a particular named authority based on
+    # the settings specified in Configuration and/or the presence of public key
+    # files on disk.
     #
     # === Parameters
     # authority(String):: The name of the authority
@@ -159,7 +181,13 @@ module GlobalSession
     # === Return
     # trusted(true|false):: whether the local system trusts sessions signed by the specified authority
     def trusted_authority?(authority)
-      @configuration['trust'].include?(authority)
+      if @configuration.has_key?('trust')
+        # Explicit trust in just the authorities specified in the configuration
+        @configuration['trust'].include?(authority)
+      else
+        # Implicit trust in any public key we found on disk
+        @keystore.public_keys.keys.include?(authority)
+      end
     end
 
     # Determine whether the given session UUID is valid. The default implementation only considers
@@ -190,5 +218,5 @@ module GlobalSession
     def report_invalid_session(uuid, expired_at)
       @invalid_sessions << uuid
     end
-  end  
+  end
 end

data/lib/global_session/keystore.rb

@@ -0,0 +1,139 @@
+# Copyright (c) 2014- RightScale Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'set'
+require 'uri'
+
+module GlobalSession
+  # Keystore uses one or more filesystem directories as a backing store
+  # for RSA keys of global session authorities. The directories should
+  # contain one or more +*.pub+ files containing OpenSSH-format public
+  # RSA keys. The name of the pub file determines the name of the
+  # authority it represents.
+  #
+  # === The Local Authority
+  # Directory will infer the name of the local authority (if any) by
+  # looking for a private-key file in the keystore. If a +*.key+ file
+  # is found, then its name is taken to be the name of the local
+  # authority and all GlobalSessions created will be signed by that
+  # authority's private key.
+  #
+  # If more than one private key file is found, Directory will raise
+  # an error at initialization time.
+  #
+  class Keystore
+    # @return [Configuration] shared configuration object
+    attr_reader :configuration
+
+    # @return [Hash] map of String authority-names to OpenSSL::PKey public-keys
+    attr_reader :public_keys
+
+    # @return [nil, String] name of local authority if we are one, else nil
+    attr_reader :private_key_name
+
+    # @return [nil,OpenSSL::PKey] local authority key if we are an authority, else nil
+    attr_reader :private_key
+
+    # @return a representation of the object suitable for printing to the console
+    def inspect
+      "<#{self.class.name} @configuration=#{@configuration.inspect}>"
+    end
+
+    def initialize(configuration)
+      @configuration = configuration
+      load
+    end
+
+    private
+
+    # Load all public and/or private keys from location(s) specified in the configuration's
+    # "keystore/public" and "keystore/private" directives.
+    #
+    # @raise [ConfigurationError] if some authority's public key has already been loaded
+    def load
+      locations = Array((configuration['keystore'] || {})['public'] || [])
+
+      locations.each do |location|
+        load_public_key(location)
+      end
+
+      location = (configuration['keystore'] || {})['private']
+      location ||= ENV['GLOBAL_SESSION_PRIVATE_KEY']
+      load_private_key(location) if location # then we must be an authority; load our key
+    end
+
+    # Load a single authority's public key, or an entire directory full of public keys. Assume
+    # that the basenames of the key files are the authority names, e.g. "dev.pub" --> "dev".
+    #
+    # @param [String] path to file or directory to load
+    # @raise [Errno::ENOENT] if path is neither a file nor a directory
+    # @raise [ConfigurationError] if some authority's public key has already been loaded
+    def load_public_key(path)
+      @public_keys ||= {}
+
+      if File.directory?(path)
+        Dir.glob(File.join(path, '*')).each do |file|
+          load_public_key(file)
+        end
+      elsif File.file?(path)
+        name = File.basename(path, '.*')
+        key  = OpenSSL::PKey::RSA.new(File.read(path))
+        # ignore private keys (which legacy config allowed to coexist with public keys)
+        unless key.private?
+          if @public_keys.has_key?(name)
+            raise ConfigurationError, "Duplicate public key for authority: #{name}"
+          else
+            @public_keys[name] = key
+          end
+        end
+      else
+        raise Errno::ENOENT.new("Path is neither a file nor a directory: " + path)
+      end
+    end
+
+    # Load a private key. Assume that the basename of the key file is the local authority name,
+    # e.g. "dev.key" --> "dev".
+    #
+    # @param [String] path to private-key file
+    # @raise [Errno::ENOENT] if path is not a file
+    # @raise [ConfigurationError] if some private key has already been loaded
+    def load_private_key(path)
+      if File.directory?(path)
+        # Arbitrarily pick the first key file found in the directory
+        path = Dir.glob(File.join(path, '*.key')).first
+      end
+
+      if File.file?(path)
+        if @private_key.nil?
+          name        = File.basename(path, '.*')
+          private_key = OpenSSL::PKey::RSA.new(File.read(path))
+          raise ConfigurationError, "Expected #{key_file} to contain an RSA private key" unless private_key.private?
+          @private_key      = private_key
+          @private_key_name = name
+        else
+          raise ConfigurationError, "Only one private key is allowed; already loaded #{@private_key_name}, cannot also load #{path}"
+        end
+      else
+        raise Errno::ENOENT.new("Path is not a file: " + path)
+      end
+    end
+  end
+end

data/lib/global_session/rack.rb

@@ -29,61 +29,84 @@ module GlobalSession
     class Middleware
       LOCAL_SESSION_KEY = "rack.session".freeze
 
-      # Make a new global session.
+      # @return [GlobalSession::Configuration]
+      attr_accessor :configuration
+
+      # @return [GlobalSession::Directory]
+      attr_accessor :directory
+
+      # Make a new global session middleware.
       #
       # The optional block here controls an alternate ticket retrieval
       # method.  If no ticket is stored in the cookie jar, this
       # function is called.  If it returns a non-nil value, that value
       # is the ticket.
       #
-      # === Parameters
-      # app(Rack client): application to run
-      # configuration(String or Configuration): global_session configuration.
-      #                                         If a string, is interpreted as a
-      #                                         filename to load the config from.
-      # directory(String or Directory):         Directory object that provides
-      #                                         trust services to the global
-      #                                         session implementation. If a
-      #                                         string, is interpreted as a
-      #                                         filesystem directory containing
-      #                                         the public and private keys of
-      #                                         authorities, from which default
-      #                                         trust services will be initialized.
+      # @param [Configuration] configuration
+      # @param optional [String,Directory] directory the directory class name (DEPRECATED) or an actual instance of Directory
       #
-      # block: optional alternate ticket retrieval function
-      def initialize(app, configuration, directory, &block)
+      # @yield if a block is provided, yields to the block to fetch session data from request state
+      # @yieldparam [Hash] env Rack request environment is passed as a yield parameter
+      def initialize(app, configuration, directory=nil, &block)
         @app = app
 
+        # Initialize shared configuration
+        # @deprecated require Configuration object in v4
         if configuration.instance_of?(String)
           @configuration = Configuration.new(configuration, ENV['RACK_ENV'] || 'development')
         else
           @configuration = configuration
         end
 
+        klass = nil
         begin
-          klass_name = @configuration['directory'] || 'GlobalSession::Directory'
+          # v0.9.0 - v3.0.4: class name is the value of the 'directory' key
+          klass_name = @configuration['directory']
+
+          case klass_name
+          when Hash
+            # v3.0.5 and beyond: class name is in 'class' subkey
+            klass_name = klass_name['class']
+          when NilClass
+            # the eternal default, if the class name is not provided
+            klass_name = 'GlobalSession::Directory'
+          end
 
-          #Constantize the type name that was given as a string
-          parts = klass_name.split('::')
-          namespace = Object
-          namespace = namespace.const_get(parts.shift.to_sym) until parts.empty?
-          directory_klass = namespace
+          if klass_name.is_a?(String)
+            # for apps
+            klass = klass_name.to_const
+          else
+            # for specs that need to directly inject a class/object
+            klass = klass_name
+          end
         rescue Exception => e
-          raise GlobalSession::ConfigurationError, "Invalid/unknown directory class name #{@configuration['directory']}"
+          raise GlobalSession::ConfigurationError,
+                "Invalid/unknown directory class name: #{klass_name.inspect}"
         end
 
-        if directory.instance_of?(String)
-          @directory = directory_klass.new(@configuration, directory)
-        else
+        # Initialize the directory
+        # @deprecated require Directory object in v4
+        if klass.is_a?(Class)
+          @directory = klass.new(@configuration, directory)
+        elsif klass.is_a?(Directory)
           @directory = directory
+        else
+          raise GlobalSession::ConfigurationError,
+                "Unsupported value for 'directory': expected Class or Directory, got #{klass.inspect}"
         end
 
+        # Initialize the keystore
+        @keystore = Keystore.new(@configuration)
+
         @cookie_retrieval = block
-        @cookie_name = @configuration['cookie']['name']
+        @cookie_name      = @configuration['cookie']['name']
       end
 
       # Rack request chain. Sets up the global session ticket from
       # the environment and passes it up the chain.
+      #
+      # @return [Array] valid Rack response tuple e.g. [200, 'hello world']
+      # @param [Hash] env Rack request environment
       def call(env)
         env['rack.cookies'] = {} unless env['rack.cookies']
 
@@ -121,11 +144,8 @@ module GlobalSession
       # header was found, also disable global session cookie update and renewal by setting the
       # corresponding keys of the Rack environment.
       #
-      # === Parameters
-      # env(Hash): Rack environment.
-      #
-      # === Return
-      # result(true,false):: Returns true if the environment was populated, false otherwise
+      # @return [Boolean] true if the environment was populated, false otherwise
+      # @param [Hash] env Rack request environment
       def read_authorization_header(env)
         if env.has_key? 'X-HTTP_AUTHORIZATION'
           # RFC2617 style (preferred by OAuth 2.0 spec)
@@ -138,9 +158,9 @@ module GlobalSession
         end
 
         if header_data && header_data.size == 2 && header_data.first.downcase == 'bearer'
-          env['global_session.req.renew'] = false
+          env['global_session.req.renew']  = false
           env['global_session.req.update'] = false
-          env['global_session'] = @directory.load_session(header_data.last)
+          env['global_session']            = @directory.load_session(header_data.last)
           true
         else
           false
@@ -149,11 +169,8 @@ module GlobalSession
 
       # Read a global session from HTTP cookies, if present.
       #
-      # === Parameters
-      # env(Hash): Rack environment.
-      #
-      # === Return
-      # result(true,false):: Returns true if the environment was populated, false otherwise
+      # @return [Boolean] true if the environment was populated, false otherwise
+      # @param [Hash] env Rack request environment
       def read_cookie(env)
         if @cookie_retrieval && (cookie = @cookie_retrieval.call(env))
           env['global_session'] = @directory.load_session(cookie)
@@ -169,11 +186,8 @@ module GlobalSession
       # Ensure that the Rack environment contains a global session object; create a session
       # if necessary.
       #
-      # === Parameters
-      # env(Hash): Rack environment.
-      #
-      # === Return
-      # true:: always returns true
+      # @return [true] always returns true
+      # @param [Hash] env Rack request environment
       def create_session(env)
         env['global_session'] ||= @directory.create_session
 
@@ -182,49 +196,53 @@ module GlobalSession
 
       # Renew the session ticket.
       #
-      # === Parameters
-      # env(Hash): Rack environment
+      # @return [true] always returns true
+      # @param [Hash] env Rack request environment
       def renew_cookie(env)
-        return unless @directory.local_authority_name
+        return unless @configuration['authority']
         return if env['global_session.req.renew'] == false
 
         if (renew = @configuration['renew']) && env['global_session'] &&
-            env['global_session'].expired_at < Time.at(Time.now.utc + 60 * renew.to_i)
+          env['global_session'].expired_at < Time.at(Time.now.utc + 60 * renew.to_i)
           env['global_session'].renew!
         end
+
+        true
       end
 
       # Update the cookie jar with the revised ticket.
       #
-      # === Parameters
-      # env(Hash): Rack environment
+      # @return [true] always returns true
+      # @param [Hash] env Rack request environment
       def update_cookie(env)
-        return unless @directory.local_authority_name
-        return if env['global_session.req.update'] == false
+        return true unless @configuration['authority']
+        return true if env['global_session.req.update'] == false
 
         session = env['global_session']
 
         if session
           unless session.valid?
             old_session = session
-            session = @directory.create_session
+            session     = @directory.create_session
             perform_invalidation_callbacks(env, old_session, session)
             env['global_session'] = session
           end
 
-          value = session.to_s
+          value   = session.to_s
           expires = @configuration['ephemeral'] ? nil : session.expired_at
           unless env['rack.cookies'][@cookie_name] == value
             env['rack.cookies'][@cookie_name] =
-                {:value => value,
-                 :domain => cookie_domain(env),
-                 :expires => expires,
-                 :httponly=>true}
+              {:value    => value,
+               :domain   => cookie_domain(env),
+               :expires  => expires,
+               :httponly => true}
           end
         else
           # write an empty cookie
           wipe_cookie(env)
         end
+
+        true
       rescue Exception => e
         wipe_cookie(env)
         raise e
@@ -232,25 +250,27 @@ module GlobalSession
 
       # Delete the global session cookie from the cookie jar.
       #
-      # === Parameters
-      # env(Hash): Rack environment
+      # @return [true] always returns true
+      # @param [Hash] env Rack request environment
       def wipe_cookie(env)
-        return unless @directory.local_authority_name
+        return unless @configuration['authority']
         return if env['global_session.req.update'] == false
 
-        env['rack.cookies'][@cookie_name] = {:value => nil,
-                                             :domain => cookie_domain(env),
+        env['rack.cookies'][@cookie_name] = {:value   => nil,
+                                             :domain  => cookie_domain(env),
                                              :expires => Time.at(0)}
+
+        true
       end
 
       # Handle exceptions that occur during app invocation. This will either save the error
       # in the Rack environment or raise it, depending on the type of error. The error may
       # also be logged.
       #
-      # === Parameters
-      # activity(String): name of activity in which error happened
-      # env(Hash): Rack environment
-      # e(Exception): error that happened
+      # @return [true] always returns true
+      # @param [String] activity name of activity during which the error happened
+      # @param [Hash] env Rack request environment
+      # @param [Exception] e error that happened
       def handle_error(activity, env, e)
         if env['rack.logger']
           msg = "#{e.class} while #{activity}: #{e}"
@@ -264,17 +284,20 @@ module GlobalSession
         elsif e.is_a? ConfigurationError
           env['global_session.error'] = e
         else
+          # Don't intercept errors unless they're GlobalSession-related
           raise e
         end
+
+        true
       end
 
       # Perform callbacks to directory and/or local session
       # informing them that this session has been invalidated.
       #
-      # === Parameters
-      # env(Hash):: the rack environment
-      # old_session(GlobalSession):: the now-invalidated session
-      # new_session(GlobalSession):: the new session that will be sent to the client
+      # @return [true] always returns true
+      # @param [Hash] env Rack request environment
+      # @param [GlobalSession::Session] old_session now-invalidated session
+      # @param [GlobalSession::Session] new_session new session that will be sent to the client
       def perform_invalidation_callbacks(env, old_session, new_session)
         if (local_session = env[LOCAL_SESSION_KEY]) && local_session.respond_to?(:rename!)
           local_session.rename!(old_session, new_session)
@@ -287,16 +310,15 @@ module GlobalSession
       # in the configuration if one is found; otherwise, uses the SERVER_NAME from the request
       # but strips off the first component if the domain name contains more than two components.
       #
-      # === Parameters
-      # env(Hash):: the Rack environment hash
+      # @param [Hash] env Rack request environment
       def cookie_domain(env)
-        if @configuration['cookie'].key?('domain')
+        if @configuration['cookie'].has_key?('domain')
           # Use the explicitly provided domain name
           domain = @configuration['cookie']['domain']
         else
           # Use the server name, but strip off the most specific component
-          parts = env['SERVER_NAME'].split('.')
-          parts = parts[1..-1] if parts.length > 2
+          parts  = env['SERVER_NAME'].split('.')
+          parts  = parts[1..-1] if parts.length > 2
           domain = parts.join('.')
         end