has_global_session 0.9.5 → 1.0

data/README.rdoc

@@ -176,10 +176,4 @@ class name of the directory under the 'common' section, like so:
     integrated: true
     directory: MyCoolDirectory
 
-= To-Do
-
-* Option to auto-renew session
-
-* Implement single sign-out via redirect
-
 Copyright (c) 2010 Tony Spataro <code@tracker.xeger.net>, released under the MIT license

data/has_global_session.gemspec

@@ -7,8 +7,8 @@ spec = Gem::Specification.new do |s|
   s.required_ruby_version = Gem::Requirement.new(">= 1.8.7")
 
   s.name    = 'has_global_session'
-  s.version = '0.9.5'
-  s.date    = '2010-07-20'
+  s.version = '1.0'
+  s.date    = '2010-07-27'
 
   s.authors = ['Tony Spataro']
   s.email   = 'code@tracker.xeger.net'

data/lib/has_global_session/configuration.rb

@@ -1,16 +1,98 @@
 module HasGlobalSession
+  # Central point of access for HasGlobalSession configuration information. This is
+  # mostly a very thin wrapper around the serialized hash written to the YAML config
+  # file.
+  #
+  # The configuration is stored as a set of nested hashes and accessed by the code
+  # using hash lookup; for example, we might ask for +Configuration['cookie']['domain']+
+  # if we wanted to know which domain the cookie should be set for.
+  #
+  # The following settings are supported:
+  # * attributes
+  #    * signed
+  #    * insecure
+  # * integrated
+  # * ephemeral
+  # * timeout
+  # * renew
+  # * authority
+  # * trust
+  # * directory
+  # * cookie
+  #     * name
+  #     * domain
+  #
+  # === Environment-Specific Settings
+  # The top level of keys in the configuration hash are special; they provide different
+  # sections of settings that apply in different environments. For instance, a Rails
+  # application might have one set of settings that apply in the development environment;
+  # these would appear under +Configuration['development']+. Another set of settings would
+  # apply in the production environment and would appear under +Configuration['production']+.
+  #
+  # === Common Settings
+  # In addition to having one section for each operating environment, the configuration
+  # file can specify a 'common' section for settings that apply
+  #
+  # === Lookup Mechanism  
+  # When the code asks for +Configuration['foo']+, we first check whether the current
+  # environment's config section has a value for foo. If one is found, we return that.
+  #
+  # If no environment-specific setting is found, we check the 'common' section and return
+  # the value found there.
+  #
+  # === Config File Location
+  # The name and location of the config file depend on the Web framework with which
+  # you are integrating; see HasGlobalSession::Rails for more information.
+  #
   module Configuration
+    # Reader for the environment module-attribute.
+    #
+    # === Return
+    # env(String):: The current configuration environment
     def self.environment; @environment; end
+
+    # Writer for the environment module-attribute.
+    #
+    # === Parameters
+    # value(String):: Configuration environment from which settings should be read
+    #
+    # === Return
+    # env(String):: The new configuration environment
     def self.environment=(value); @environment = value; end
 
+    # Reader for the config_file module-attribute.
+    #
+    # === Return
+    # file(String):: Absolute path to configuration file
     def self.config_file; @config_file; end
+
+    # Writer for the config_file module-attribute.
+    #
+    # === Parameters
+    # value(String):: Absolute path to configuration file
+    #
+    # === Return
+    # env(String):: The new path to the configuration file
     def self.config_file=(value); @config_file= value; end
 
+    # Reader for configuration elements. The reader first checks
+    # the current environment's settings section for the named
+    # value; if not found, it checks the common settings section.
+    #
+    # === Parameters
+    # name(Type):: Description
+    #
+    # === Return
+    # name(Type):: Description
+    #
+    # === Raise
+    # MissingConfiguration:: if config file location is unset, environment is unset, or config file is missing
+    # TypeError:: if config file does not contain a YAML-serialized Hash
     def self.[](key)
       get(key, true)
     end
 
-    def self.validate
+    def self.validate # :nodoc
       ['attributes/signed', 'integrated', 'cookie/name', 'timeout'].each do |path|
         elements = path.split '/'
         object = get(elements.shift, false)
@@ -25,7 +107,8 @@ module HasGlobalSession
     end
 
     private
-    def self.get(key, validated)
+
+    def self.get(key, validated) # :nodoc
       unless @config
         raise MissingConfiguration, "config_file is nil; cannot read configuration" unless config_file
         raise MissingConfiguration, "environment is nil; must be specified" unless environment

data/lib/has_global_session/directory.rb

@@ -1,7 +1,43 @@
 module HasGlobalSession
+  # The global session directory, which provides some lookup and decision services
+  # to instances of GlobalSession.
+  #
+  # The default implementation is simplistic, but should be suitable for most applications.
+  # Directory is designed to be specialized via subclassing. To override the behavior to
+  # suit your needs, simply create a subclass of Directory and add a configuration file
+  # setting to specify the class name of your implementation:  
+  #
+  #     common:
+  #       directory: MyCoolDirectory
+  #
+  #
+  # === 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.
+  #
+  # === 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.
+  #
   class Directory
     attr_reader :authorities, :private_key, :local_authority_name
 
+    # 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(keystore_directory)
       certs = Dir[File.join(keystore_directory, '*.pub')]
       keys  = Dir[File.join(keystore_directory, '*.key')]
@@ -24,14 +60,41 @@ module HasGlobalSession
       end
     end
 
+    # Determine whether this system trusts a particular authority based on
+    # the trust settings specified in Configuration.
+    #
+    # === Parameters
+    # authority(String):: The name of the authority
+    #
+    # === Return
+    # trusted(true|false):: whether the local system trusts sessions signed by the specified authority
     def trusted_authority?(authority)
       Configuration['trust'].include?(authority)
     end
 
+    # Determine whether the given session UUID is valid. The default implementation only considers
+    # a session to be invalid if its expired_at timestamp is in the past. Custom implementations
+    # might want to consider other factors, such as whether the user has signed out of this node
+    # or another node (perhaps using some sort of centralized lookup or single sign-out mechanism).
+    #
+    # === Parameters
+    # uuid(String):: Global session UUID
+    # expired_at(Time):: When the session expired (or will expire)
+    #
+    # === Return
+    # valid(true|false):: whether the specified session is valid
     def valid_session?(uuid, expired_at)
       expired_at > Time.now
     end
 
+    # Callback used by GlobalSession objects to report when the application code calls
+    # #invalidate! on them. The default implementation of this method does nothing.
+    #
+    # uuid(String):: Global session UUID
+    # expired_at(Time):: When the session expired
+    #
+    # === Return
+    # true:: Always returns true
     def report_invalid_session(uuid, expired_at)
       true
     end

data/lib/has_global_session/encoding.rb

@@ -1,10 +1,29 @@
 module HasGlobalSession
+  # Various encoding (not encryption!) techniques used by the global session plugin.
+  #
   module Encoding
+    # JSON serializer, used to serialize Hash objects in a form suitable
+    # for stuffing into a cookie.
+    #
     class JSON
+      # Unserialize JSON to Hash.
+      #
+      # === Parameters
+      # json(String):: A well-formed JSON document
+      #
+      # === Return
+      # value(Hash):: An unserialized Ruby Hash
       def self.load(json)
         ::JSON.load(json)
       end
 
+      # Serialize Hash to JSON document.
+      #
+      # === Parameters
+      # value(Hash):: The hash to be serialized
+      #
+      # === Return
+      # json(String):: A JSON-serialized representation of +value+
       def self.dump(object)
         return object.to_json
       end
@@ -21,11 +40,25 @@ module HasGlobalSession
     # this scheme preserves the '=' padding characters due to limitations of
     # Ruby's built-in base64 encoding routines.
     class Base64Cookie
+      # Decode a B64cookie-encoded string.
+      #
+      # === Parameters
+      # encoded(String):: The encoded string
+      #
+      # === Return
+      # decoded(String):: The decoded result, which may contain nonprintable bytes
       def self.load(string)
         tr = string.tr('-_', '+/')
         return tr.unpack('m')[0]
       end
       
+      # Encode a Ruby (ASCII or binary) string.
+      #
+      # === Parameters
+      # decoded(String):: The raw string to be encoded
+      #
+      # === Return
+      # encoded(String):: The B64cookie-encoded result.
       def self.dump(object)
         raw = [object].pack('m')
         raw.tr!('+/', '-_')

data/lib/has_global_session/global_session.rb

@@ -6,15 +6,34 @@ require 'zlib'
 require 'uuidtools'
 
 module HasGlobalSession 
+  # Ladies and gentlemen: the one and only, star of the show, GLOBAL SESSION!
+  #
+  # GlobalSession is designed to act as much like a Hash as possible. You can use
+  # most of the methods you would use with Hash: [], has_key?, each, etc. It has a
+  # few additional methods that are specific to itself, mostly involving whether
+  # it's expired, valid, supports a certain key, etc.
+  #
   class GlobalSession
     attr_reader :id, :authority, :created_at, :expired_at, :directory
 
+    # Create a new global session object.
+    #
+    # === Parameters
+    # directory(Directory):: directory implementation that the session should use for various operations
+    # cookie(String):: Optional, serialized global session cookie. If none is supplied, a new session is created.
+    # valid_signature_digest(String):: Optional, already-trusted signature. If supplied, the expensive RSA-verify operation will be skipped if the cookie's signature matches the value supplied.
+    #
+    # ===Raise
+    # InvalidSession:: if the session contained in the cookie has been invalidated
+    # ExpiredSession:: if the session contained in the cookie has expired
+    # MalformedCookie:: if the cookie was corrupt or malformed
+    # SecurityError:: if signature is invalid or cookie is not signed by a trusted authority
     def initialize(directory, cookie=nil, valid_signature_digest=nil)
       @schema_signed   = Set.new((Configuration['attributes']['signed']))
       @schema_insecure = Set.new((Configuration['attributes']['insecure']))
       @directory       = directory
 
-      if cookie
+      if cookie && !cookie.empty?
         load_from_cookie(cookie, valid_signature_digest)
       elsif @directory.local_authority_name
         create_from_scratch
@@ -23,10 +42,21 @@ module HasGlobalSession
       end
     end
 
+    # Determine whether the session is valid. This method simply delegates to the
+    # directory associated with this session.
+    #
+    # === Return
+    # valid(true|false):: True if the session is valid, false otherwise
     def valid?
       @directory.valid_session?(@id, @expired_at)
     end
 
+    # Serialize the session to a form suitable for use with HTTP cookies. If any
+    # secure attributes have changed since the session was instantiated, compute
+    # a fresh RSA signature.
+    #
+    # === Return
+    # cookie(String):: The B64cookie-encoded Zlib-compressed JSON-serialized global session hash
     def to_s
       if @cookie && !@dirty_insecure && !@dirty_secure
         #use cached cookie if nothing has changed
@@ -57,35 +87,84 @@ module HasGlobalSession
       return Encoding::Base64Cookie.dump(zbin)
     end
 
+    # Determine whether the global session schema allows a given key to be placed
+    # in the global session.
+    #
+    # === Parameters
+    # key(String):: The name of the key
+    #
+    # === Return
+    # supported(true|false):: Whether the specified key is supported
     def supports_key?(key)
       @schema_signed.include?(key) || @schema_insecure.include?(key)
     end
 
+    # Determine whether this session contains a value with the specified key.
+    #
+    # === Parameters
+    # key(String):: The name of the key
+    #
+    # === Return
+    # contained(true|false):: Whether the session currently has a value for the specified key.
     def has_key?(key)
       @signed.has_key(key) || @insecure.has_key?(key)
     end
 
-    def signature_digest
-      @signature ? digest(@signature) : nil
-    end
-
+    # Return the keys that are currently present in the global session.
+    #
+    # === Return
+    # keys(Array):: List of keys contained in the global session
     def keys
       @signed.keys + @insecure.keys
     end
 
+    # Return the values that are currently present in the global session.
+    #
+    # === Return
+    # values(Array):: List of values contained in the global session
     def values
       @signed.values + @insecure.values
     end
 
-    def each_pair(&block)
+    # Iterate over each key/value pair
+    #
+    # === Block
+    # An iterator which will be called with each key/value pair
+    #
+    # === Return
+    # Returns the value of the last expression evaluated by the block
+    def each_pair(&block) # :yields: |key, value|
       @signed.each_pair(&block)
       @insecure.each_pair(&block)
     end
 
+    # Lookup a value by its key.
+    #
+    # === Parameters
+    # key(String):: the key
+    #
+    # === Return
+    # value(Object):: The value associated with +key+, or nil if +key+ is not present
     def [](key)
       @signed[key] || @insecure[key]
     end
 
+    # Set a value in the global session hash. If the supplied key is denoted as
+    # secure by the global session schema, causes a new signature to be computed
+    # when the session is next serialized.
+    #
+    # === Parameters
+    # key(String):: The key to set
+    # value(Object):: The value to set
+    #
+    # === Return
+    # value(Object):: Always returns the value that was set
+    #
+    # ===Raise
+    # InvalidSession:: if the session has been invalidated (and therefore can't be written to)
+    # ArgumentError:: if the configuration doesn't define the specified key as part of the global session
+    # NoAuthority:: if the specified key is secure and the local node is not an authority
+    # UnserializableType:: if the specified value can't be serialized as JSON
     def []=(key, value)
       raise InvalidSession unless valid?
 
@@ -102,36 +181,58 @@ module HasGlobalSession
       else
         raise ArgumentError, "Attribute '#{key}' is not specified in global session configuration"
       end
+
+      return value
     end
 
+    # Invalidate this session by reporting its UUID to the Directory.
+    #
+    # === Return
+    # unknown(Object):: Returns whatever the Directory returns
     def invalidate!
       @directory.report_invalid_session(@id, @expired_at)
     end
 
+    # Renews this global session, changing its expiry timestamp into the future.
+    # Causes a new signature will be computed when the session is next serialized.
+    #
+    # === Return
+    # true:: Always returns true
     def renew!
       authority_check
       @expired_at = Configuration['timeout'].to_i.minutes.from_now.utc
       @dirty_secure = true
     end
 
+    # Return the SHA1 hash of the most recently-computed RSA signature of this session.
+    # This isn't really intended for the end user; it exists so the Web framework integration
+    # code can optimize request speed by caching the most recently verified signature in the
+    # local session and avoid re-verifying it on every request.
+    #
+    # === Return
+    # digest(String):: SHA1 hex-digest of most-recently-computed signature
+    def signature_digest
+      @signature ? digest(@signature) : nil
+    end
+
     private
 
-    def authority_check
+    def authority_check # :nodoc:
       unless @directory.local_authority_name
         raise NoAuthority, 'Cannot change secure session attributes; we are not an authority'
       end      
     end
 
-    def canonical_digest(input)
+    def canonical_digest(input) # :nodoc:
       canonical = Encoding::JSON.dump(canonicalize(input))
       return digest(canonical)
     end
 
-    def digest(input)
+    def digest(input) # :nodoc:
       return Digest::SHA1.new().update(input).hexdigest
     end
 
-    def canonicalize(input)
+    def canonicalize(input) # :nodoc:
       case input
         when Hash
           output = Array.new
@@ -150,10 +251,16 @@ module HasGlobalSession
       return output
     end
 
-    def load_from_cookie(cookie, valid_signature_digest)
-      zbin = Encoding::Base64Cookie.load(cookie)
-      json = Zlib::Inflate.inflate(zbin)
-      hash = Encoding::JSON.load(json)
+    def load_from_cookie(cookie, valid_signature_digest) # :nodoc:
+      begin
+        zbin = Encoding::Base64Cookie.load(cookie)
+        json = Zlib::Inflate.inflate(zbin)
+        hash = Encoding::JSON.load(json)
+      rescue Exception => e
+        mc = MalformedCookie.new("Caused by #{e.class.name}: #{e.message}")
+        mc.set_backtrace(e.backtrace)
+        raise mc
+      end
 
       id         = hash['id']
       authority  = hash['a']
@@ -200,7 +307,7 @@ module HasGlobalSession
       @cookie     = cookie
     end
 
-    def create_from_scratch
+    def create_from_scratch # :nodoc:
       authority_check
 
       @signed          = {}
@@ -219,7 +326,7 @@ module HasGlobalSession
       renew!
     end
 
-    def create_invalid
+    def create_invalid # :nodoc:
       @id         = nil
       @created_at = Time.now.utc
       @expired_at = created_at

data/lib/has_global_session/integrated_session.rb

@@ -1,12 +1,42 @@
 module HasGlobalSession
+  # Helper class that enables the end user to treat the global and local session as if
+  # they were the same object. This is accomplished by implementing approximately the
+  # same interface as a Hash, and dispatching to one or the other session object depending
+  # on various factors.
+  #
+  # This class isn't intended to be used directly by the end user. Instead, set integrated: true
+  # in the configuration file and the Web framework integration code will manage an integrated
+  # session object for you, as well as overriding the framework's default session accessor to
+  # return an integrated session instead.
+  #
+  # When using an integrated session, you can always get to the underlying objects by
+  # using the #local and #global readers of this class.
+  #
   class IntegratedSession
-    attr_reader :local, :global
+    # Return the local-session objects, whose type may vary depending on the Web framework.
+    attr_reader :local
+
+    # Return the global-session object.
+    attr_reader :global
     
+    # Construct a new integrated session.
+    #
+    # === Parameters
+    # local(Object):: Local session that acts like a Hash
+    # global(GlobalSession):: GlobalSession
     def initialize(local, global)
       @local = local
       @global = global
     end
 
+    # Retrieve a value from the global session if the supplied key is supported by
+    # the global session, else retrieve it from the local session.
+    #
+    # === Parameters
+    # key(String):: the key
+    #
+    # === Return
+    # value(Object):: The value associated with +key+, or nil if +key+ is not present
     def [](key)
       key = key.to_s
       if @global.supports_key?(key)
@@ -16,6 +46,15 @@ module HasGlobalSession
       end
     end
 
+    # Set a value in the global session (if the supplied key is supported) or the local
+    # session otherwise.
+    #
+    # === Parameters
+    # key(String):: The key to set
+    # value(Object):: The value to set
+    #
+    # === Return
+    # value(Object):: Always returns the value that was set
     def []=(key, value)
       key = key.to_s
       if @global.supports_key?(key)
@@ -23,34 +62,48 @@ module HasGlobalSession
       else
         @local[key] = value
       end
+
+      return value
     end
 
+    # Determine whether the global or local session contains a value with the specified key.
+    #
+    # === Parameters
+    # key(String):: The name of the key
+    #
+    # === Return
+    # contained(true|false):: Whether the session currently has a value for the specified key.
     def has_key?(key)
       key = key.to_s
-      @global.has_key(key) || @local.has_key?(key)
+      @global.has_key?(key) || @local.has_key?(key)
     end
 
+    # Return the keys that are currently present in either the global or local session.
+    #
+    # === Return
+    # keys(Array):: List of keys contained in the global or local session.
     def keys
       @global.keys + @local.keys
     end
 
+    # Return the values that are currently present in the global or local session.
+    #
+    # === Return
+    # values(Array):: List of values contained in the global or local session.
     def values
       @global.values + @local.values
     end
 
+    # Iterate over each key/value pair in both the global and local session.
+    #
+    # === Block
+    # An iterator which will be called with each key/value pair
+    #
+    # === Return
+    # Returns the value of the last expression evaluated by the block
     def each_pair(&block)
       @global.each_pair(&block)
       @local.each_pair(&block)
     end
-
-    def method_missing(meth, *args)
-      if @global.respond_to?(meth)
-        return @global.send(meth, *args)
-      elsif @local.respond_to?(meth)
-        return @local.send(meth, *args)
-      else
-        super
-      end
-    end
   end
 end

data/lib/has_global_session/rails/action_controller_instance_methods.rb

@@ -1,17 +1,39 @@
 module HasGlobalSession
+  # Rails integration for HasGlobalSession.
+  #
+  # The configuration file for Rails apps is located in +config/global_session.yml+ and a generator
+  # (global_session_config) is available for creating a sensible default.
+  #
+  # There is also a generator (global_session_authority) for creating authority keypairs.
+  #
+  # The main integration touchpoint for Rails is the module ActionControllerInstanceMethods,
+  # which gets mixed into ActionController::Base. This is where all of the magic happens..
+  #
   module Rails
+    # Module that is mixed into ActionController-derived classes when the class method
+    # +has_global_session+ is called.
+    #
     module ActionControllerInstanceMethods
-      def self.included(base)
+      def self.included(base) # :nodoc:
         base.alias_method_chain :session, :global_session
         base.before_filter :global_session_read_cookie
         base.before_filter :global_session_auto_renew
         base.after_filter  :global_session_update_cookie
       end
 
+      # Global session reader.
+      #
+      # === Return
+      # session(GlobalSession):: the global session associated with the current request, nil if none
       def global_session
         @global_session
       end
 
+      # Aliased version of ActionController::Base#session which will return the integrated
+      # global-and-local session object (IntegratedSession).
+      #
+      # === Return
+      # session(IntegratedSession):: the integrated session
       def session_with_global_session
         if Configuration['integrated'] && @global_session
           unless @integrated_session &&
@@ -27,6 +49,11 @@ module HasGlobalSession
         end
       end
 
+      # Before-filter to read the global session cookie and construct the GlobalSession object
+      # for this controller instance.
+      #
+      # === Return
+      # true:: Always returns true
       def global_session_read_cookie
         directory   = global_session_create_directory
         cookie_name = Configuration['cookie']['name']
@@ -56,15 +83,27 @@ module HasGlobalSession
         end
       end
 
+      # Before-filter to renew the global session if it will be expiring soon.
+      #
+      # === Return
+      # true:: Always returns true
       def global_session_auto_renew
         #Auto-renew session if needed
         renew = Configuration['renew']
-        if @global_session.directory.local_authority_name && renew &&
+        if @global_session &&
+           renew &&
+           @global_session.directory.local_authority_name &&
            @global_session.expired_at < renew.to_i.minutes.from_now.utc
           @global_session.renew!
-        end        
+        end
+
+        return true
       end
 
+      # After-filter to write any pending changes to the global session cookie.
+      #
+      # === Return
+      # true:: Always returns true
       def global_session_update_cookie
         name   = Configuration['cookie']['name']
         domain = Configuration['cookie']['domain'] || request.env['SERVER_NAME']
@@ -90,6 +129,15 @@ module HasGlobalSession
         end
       end
 
+      # Override for the ActionController method of the same name that logs
+      # information about the request. Our version logs the global session ID
+      # instead of the local session ID.
+      #
+      # === Parameters
+      # name(Type):: Description
+      #
+      # === Return
+      # name(Type):: Description
       def log_processing
         if logger && logger.info?
           log_processing_for_request_id
@@ -97,7 +145,7 @@ module HasGlobalSession
         end
       end
 
-      def log_processing_for_request_id
+      def log_processing_for_request_id # :nodoc:
         if global_session && global_session.id
           session_id = global_session.id + " (#{session[:session_id]})"
         elsif session[:session_id]
@@ -114,7 +162,7 @@ module HasGlobalSession
         logger.info(request_id)
       end
 
-      def log_processing_for_parameters
+      def log_processing_for_parameters # :nodoc:
         parameters = respond_to?(:filter_parameters) ? filter_parameters(params) : params.dup
         parameters = parameters.except!(:controller, :action, :format, :_method)
 
@@ -123,7 +171,7 @@ module HasGlobalSession
 
       private
 
-      def global_session_create_directory
+      def global_session_create_directory # :nodoc:
         if (klass = Configuration['directory'])
           klass = klass.constantize
         else

data/lib/has_global_session.rb

@@ -1,9 +1,46 @@
 module HasGlobalSession
+  # Indicates that the global session configuration file is missing from disk.
+  #
   class MissingConfiguration < Exception; end
+
+  # Indicates that the global session configuration file is missing elements or is
+  # malformatted.
+  #
   class ConfigurationError < Exception; end
+
+  # Indicates that a client submitted a request with a valid session cookie, but the
+  # session ID was reported as invalid by the Directory.
+  #
+  # See Directory#valid_session? for more information.
+  #
   class InvalidSession < Exception; end
+
+  # Indicates that a client submitted a request with a valid session cookie, but the
+  # session has expired.
+  #
   class ExpiredSession < Exception; end
+
+  # Indicates that a client submitted a request with a session cookie that could not
+  # be decoded or decompressed.
+  #
+  class MalformedCookie < Exception; end
+
+  # Indicates that application code tried to put an unserializable object into the glboal
+  # session hash. Because the global session is serialized as JSON and not all Ruby types
+  # can be easily round-tripped to JSON and back without data loss, we constrain the types
+  # that can be serialized.
+  #
+  # See HasGlobalSession::Encoding::JSON for more information on serializable types.
+  #
   class UnserializableType < Exception; end
+
+  # Indicates that the application code tried to write a secure session attribute or
+  # renew the global session. Both of these operations require a local authority
+  # because they require a new signature to be computed on the global session.
+  #
+  # See HasGlobalSession::Configuration and HasGlobalSession::Directory for more
+  # information.
+  #
   class NoAuthority < Exception; end
 end
 

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: has_global_session
 version: !ruby/object:Gem::Version 
-  hash: 49
+  hash: 15
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 9
-  - 5
-  version: 0.9.5
+  version: "1.0"
 platform: ruby
 authors: 
 - Tony Spataro
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-20 00:00:00 -07:00
+date: 2010-07-27 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency