global_session 0.9.0 → 1.0.0

data/README.rdoc

@@ -1,12 +1,15 @@
 = Introduction
 
-HasGlobalSession enables multiple heterogeneous Web applications to share
+GlobalSession enables multiple heterogeneous Web applications to share
 session state in a cryptographically secure way, facilitating single sign-on
-and enabling easier development of large-scale distributed applications that
+and enabling easier development of distributed applications that
 make use of architectural strategies such as sharding or separation of concerns.
 
-In other words: it lets semi-related Web apps share selected bits of session
-state.
+In other words: it glues your semi-related Web apps together so they share the
+same bits of session state. This is done by putting the session itself into
+cookies.
+
+== What Is It Not?
 
 This plugin does not provide a complete solution for identity management. In
 particular, it does not provide any of the following:
@@ -73,7 +76,7 @@ whenever attributes change. As an optimization, the signature is only
 recomputed when the metadata or signed attributes have changed; insecure
 attributes can change "for free."
 
-Because the security properties of attributes can vary, HasGlobalSession
+Because the security properties of attributes can vary, GlobalSession
 requires all _possible_ attributes to be declared up-front in the config
 file. The 'attributes' section of the config file defines the _schema_
 for the global session: which attributes can be used, which can be trusted
@@ -97,13 +100,13 @@ or they may be running different codebases that represent different parts of
 a distributed application. (They may also be using app frameworks other than
 Rails.)
 
-The only constraint imposed by HasGlobalSession is that all nodes within the
+The only constraint imposed by GlobalSession is that all nodes within the
 domain must have end-user-facing URLs within the same second-level DNS domain.
 This is due to limitations imposed by the HTTP cookie mechanism: for privacy
 reasons, cookies will only be sent to nodes within the same domain as the
 node that first created them.
 
-For example, in my HasGlobalSession configuration file I might specify that my
+For example, in my GlobalSession configuration file I might specify that my
 cookie's domain is "example.com". My app nodes at app1.example.com and
 app2.example.com would be part of the global session domain, but my business
 partner's application at app3.partner.com could not participate.
@@ -138,7 +141,7 @@ authorities:
 
 == The Directory
 
-The Directory is a Ruby object instantiated by HasGlobalSession in order to
+The Directory is a Ruby object instantiated by GlobalSession in order to
 perform lookups of public and private keys. Given an authority name (as found
 in a session cookie), the Directory can find the corresponding public key.
 
@@ -146,7 +149,7 @@ If the local system is an authority itself, #local_authority_name will
 return non-nil and #private_key will return a private key suitable for
 signing session attributes.
 
-The Directory implementation included with HasGlobalSession uses the filesystem
+The Directory implementation included with GlobalSession uses the filesystem
 as the backing store for its key pairs. Its #initialize method accepts a
 filesystem path that will be searched for files containing PEM-encoded public
 and private keys (the same format used by OpenSSH). This simple Directory
@@ -157,7 +160,7 @@ implementation relies on the following conventions:
 * The local node's authority name is inferred from the name of the private key
   file.
 
-When used with a Rails app, HasGlobalSession expects to find its keystore in
+When used with a Rails app, GlobalSession expects to find its keystore in
 config/authorities. You can use the global_session generator to create new key
 pairs. Remember never to check a *.key file into a public repository!! (*.pub
 files can be checked into source control and distributed freely.) 
@@ -169,7 +172,7 @@ its public key from config/authorities and re-deploy your app.
 
 To replace or enhance the built-in Directory, simply create a new class that
 extends Directory and put the class somewhere in your app (the lib directory
-is a good choice). In the HasGlobalSession configuration file, specify the
+is a good choice). In the GlobalSession configuration file, specify the
 class name of the directory under the 'common' section, like so:
 
   common:

data/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    = 'global_session'
-  s.version = '0.9.0'
-  s.date    = '2010-12-07'
+  s.version = '1.0.0'
+  s.date    = '2011-01-01'
 
   s.authors = ['Tony Spataro']
   s.email   = 'code@tracker.xeger.net'

data/lib/global_session/integrated_session.rb

@@ -12,7 +12,7 @@ module GlobalSession
   # 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
+  class GlobalSession::IntegratedSession
     # Return the local-session objects, whose type may vary depending on the Web framework.
     attr_reader :local
 
@@ -78,6 +78,8 @@ module GlobalSession
       @global.has_key?(key) || @local.has_key?(key)
     end
 
+    alias :key? :has_key?
+    
     # Return the keys that are currently present in either the global or local session.
     #
     # === Return

data/lib/global_session/rack.rb

@@ -52,7 +52,7 @@ module GlobalSession
       # === Parameters
       # env(Hash): Rack environment.
       def read_cookie(env)
-        if env['rack.cookies'].key?(@cookie_name)
+        if env['rack.cookies'].has_key?(@cookie_name)
           env['global_session'] = Session.new(@directory,
                                               env['rack.cookies'][@cookie_name])
         elsif @cookie_retrieval && cookie = @cookie_retrieval.call(env)
@@ -69,9 +69,10 @@ module GlobalSession
       # === Parameters
       # env(Hash): Rack environment
       def renew_cookie(env)
+        return unless env['global_session'].directory.local_authority_name
+        return if env['global_session.req.renew'] == false
+        
         if (renew = @configuration['renew']) && env['global_session'] &&
-            env['global_session.req.renew'] != false &&
-            env['global_session'].directory.local_authority_name &&
             env['global_session'].expired_at < Time.at(Time.now.utc + 60 * renew.to_i)
           env['global_session'].renew!
         end
@@ -82,6 +83,7 @@ module GlobalSession
       # === Parameters
       # env(Hash): Rack environment
       def update_cookie(env)
+        return unless env['global_session'].directory.local_authority_name
         return if env['global_session.req.update'] == false
 
         begin
@@ -89,7 +91,7 @@ module GlobalSession
           if env['global_session'] && env['global_session'].valid?
             value = env['global_session'].to_s
             expires = @configuration['ephemeral'] ? nil : env['global_session'].expired_at
-            unless env['rack.cookies'].key?(@cookie_name) &&
+            unless env['rack.cookies'].has_key?(@cookie_name) &&
                 env['rack.cookies'][@cookie_name] == value
               env['rack.cookies'][@cookie_name] = {:value => value, :domain => domain, :expires => expires}
             end
@@ -103,7 +105,7 @@ module GlobalSession
         end
       end
 
-      # Delete the ticket from the cookie jar.
+      # Delete the global session cookie from the cookie jar.
       #
       # === Parameters
       # env(Hash): Rack environment
@@ -112,7 +114,9 @@ module GlobalSession
         env['rack.cookies'][@cookie_name] = {:value => nil, :domain => domain, :expires => Time.at(0)}
       end
 
-      # Handle exceptions that occur during app invocation.
+      # 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
@@ -121,11 +125,10 @@ module GlobalSession
       def handle_error(activity, env, e)
         if e.is_a? ClientError
           env['global_session.error'] = e
-          return @app.call(env)
+          wipe_cookie(env)
         elsif e.is_a? ConfigurationError
           env['rack.logger'].error("#{e.class} while #{activity}: #{e} #{e.backtrace}") if env['rack.logger']
           env['global_session.error'] = e
-          return @app.call(env)
         else
           raise e
         end
@@ -140,17 +143,20 @@ module GlobalSession
           read_cookie(env)
         rescue Exception => e
           env['global_session'] = Session.new(@directory)
-          return handle_error('reading session cookie', env, e)
+          handle_error('reading session cookie', env, e)
         end
 
+        tuple = nil
+        
         begin
           tuple = @app.call(env)
+        rescue Exception => e
+          handle_error('processing request', env, e)
+          return tuple
+        else
           renew_cookie(env)
           update_cookie(env)
           return tuple
-        rescue Exception => e
-          wipe_cookie(env)
-          return handle_error('processing request', env, e)
         end
       end
     end
@@ -158,5 +164,5 @@ module GlobalSession
 end
 
 module Rack
-  GlobalSession = GlobalSession::Rack::Middleware unless defined?(GlobalSession)
+  GlobalSession = ::GlobalSession::Rack::Middleware unless defined?(::Rack::GlobalSession)
 end

data/lib/global_session/rails/action_controller_class_methods.rb

@@ -1,7 +1,8 @@
 module GlobalSession
   module Rails
     # Module that is mixed into ActionController's eigenclass; provides access to shared
-    # app-wide data such as the configuration object.
+    # app-wide data such as the configuration object, and implements the DSL used to
+    # configure controllers' use of the global session.
     module ActionControllerClassMethods
       def global_session_config
         unless @global_session_config
@@ -17,40 +18,32 @@ module GlobalSession
       end
 
       def has_global_session(options={})
-        odefault = {:integrated=>false}
+        odefault = {:integrated=>false, :raise=>true}
         obase = self.superclass.global_session_options if self.superclass.respond_to?(:global_session_options)
+        obase ||= {}
         options = odefault.merge(obase).merge(options)
-        
-        self.global_session_options = HashWithIndifferentAccess.new(options)
-        options = self.global_session_options
-
-        include GlobalSession::Rails::ActionControllerInstanceMethods
-
-        fopt = {}
-        inverse_fopt = {}
-        fopt[:only] = options[:only] if options[:only]
-        fopt[:except] = options[:except] if options[:except]
-        inverse_fopt[:only] = options[:except] if options[:except]
-        inverse_fopt[:except] = options[:only] if options[:only]
-
-        if fopt[:only] || fopt[:except]
-          before_filter :global_session_skip_renew, inverse_fopt
-          before_filter :global_session_skip_update, inverse_fopt
-        end
 
-        before_filter :global_session_initialize, fopt
+        #ensure derived-class options don't conflict with mutually exclusive base-class options
+        options.delete(:only) if obase.has_key?(:only) && options.has_key?(:except)
+        options.delete(:except) if obase.has_key?(:except) && options.has_key?(:only)
+
+        #mark the global session as enabled (a hidden option) and store our
+        #calculated, merged options
+        options[:enabled] = true
+        self.global_session_options = options
+
+        before_filter :global_session_initialize
       end
 
       def no_global_session
+        @global_session_options[:enabled] = false if @global_session_options
         skip_before_filter :global_session_initialize
-        before_filter :global_session_skip_renew
-        before_filter :global_session_skip_update
       end
 
-      protected
-
       def global_session_options
-        @global_session_options || {}
+        obase = self.superclass.global_session_options if self.superclass.respond_to?(:global_session_options) 
+        obase ||= {}
+        @global_session_options || obase
       end
 
       def global_session_options=(options)

data/lib/global_session/rails/action_controller_instance_methods.rb

@@ -15,7 +15,10 @@ module GlobalSession
     #
     module ActionControllerInstanceMethods
       def self.included(base) # :nodoc:
-        base.alias_method_chain :session, :global_session
+        #Make sure a superclass hasn't already chained the methods...
+        unless base.instance_methods.include?("session_without_global_session")
+          base.alias_method_chain :session, :global_session
+        end
       end
 
       # Shortcut accessor for global session configuration object.
@@ -27,7 +30,7 @@ module GlobalSession
       end
 
       def global_session_options
-        self.class.instance_variable_get(:@global_session_options)
+        self.class.global_session_options
       end
 
       # Global session reader.
@@ -44,7 +47,7 @@ module GlobalSession
       # === Return
       # session(IntegratedSession):: the integrated session
       def session_with_global_session
-        if global_session
+        if global_session_options[:integrated] && global_session
           unless @integrated_session &&
                  (@integrated_session.local == session_without_global_session) && 
                  (@integrated_session.global == global_session)
@@ -63,14 +66,26 @@ module GlobalSession
       # === Return
       # true:: Always returns true
       def global_session_initialize
-        options = self.class.instance_variable_get(:@global_session_options) || {}
+        options = global_session_options
+
+        if options[:only] && !options[:only].include?(action_name)
+          should_skip = true
+        elsif options[:except] && options[:except].include?(action_name)
+          should_skip = true
+        elsif !options[:enabled]
+          should_skip = true
+        end
 
-        if (error = request.env['global_session.error'])
-          raise error unless options[:raise] == false
+        if should_skip
+          request.env['global_session.req.renew'] = false
+          request.env['global_session.req.update'] = false
         else
+          error = request.env['global_session.error']
+          raise error unless error.nil? || options[:raise] == false
           @global_session = request.env['global_session']
-          return true
         end
+
+        return true
       end
 
       # Filter to disable auto-renewal of the session.

data/lib/global_session/rails.rb

@@ -1,21 +1,26 @@
 basedir = File.dirname(__FILE__)
 
 require 'rack/contrib/cookies'
-
+require 'action_pack'
+require 'action_controller'
 
 #Require the files necessary for Rails integration
 require 'global_session/rack'
 require 'global_session/rails/action_controller_class_methods'
 require 'global_session/rails/action_controller_instance_methods'
 
+# Enable ActionController integration.
+class <<ActionController::Base
+  include GlobalSession::Rails::ActionControllerClassMethods
+end
+
+ActionController::Base.instance_eval do
+  include GlobalSession::Rails::ActionControllerInstanceMethods
+end
+
 module GlobalSession
   module Rails
     def self.activate(config)
-      # Enable ActionController integration.
-      class <<ActionController::Base
-        include GlobalSession::Rails::ActionControllerClassMethods
-      end
-
       authorities = File.join(::Rails.root, 'config', 'authorities')
       hgs_config  = ActionController::Base.global_session_config
       hgs_dir     = GlobalSession::Directory.new(hgs_config, authorities)
@@ -27,4 +32,4 @@ module GlobalSession
       return true
     end
   end
-end
+end

data/lib/global_session/session.rb

@@ -111,6 +111,8 @@ module GlobalSession
       @signed.has_key?(key) || @insecure.has_key?(key)
     end
 
+    alias :key? :has_key?
+    
     # Return the keys that are currently present in the global session.
     #
     # === Return

data/lib/global_session.rb

@@ -61,3 +61,9 @@ require File.join(basedir, 'global_session', 'directory')
 require File.join(basedir, 'global_session', 'encoding')
 require File.join(basedir, 'global_session', 'session')
 require File.join(basedir, 'global_session', 'integrated_session')
+
+#Preemptively try to activate the Rails plugin, ignoring errors
+begin
+  require File.join(basedir, 'global_session', 'rails')  
+rescue Exception => e
+end

data/rails/init.rb

@@ -1,3 +1,2 @@
-#
-# Empty placeholder file so Rails 2.x will recognize us as a plugin
-#
+require 'global_session'
+require 'global_session/rails'

data/rails_generators/global_session/global_session_generator.rb

@@ -0,0 +1,30 @@
+class GlobalSessionGenerator < Rails::Generator::Base
+  def initialize(runtime_args, runtime_options = {})
+    super
+
+    @app_name   = File.basename(::Rails.root)
+    @app_domain = args.shift
+    raise ArgumentError, "Must specify DNS domain for global session cookie, e.g. 'example.com'" unless @app_domain
+  end
+
+  def manifest
+    record do |m|
+      
+      m.template 'global_session.yml.erb',
+                 'config/global_session.yml',
+                 :assigns=>{:app_name=>@app_name,
+                            :app_domain=>@app_domain}
+
+      puts "*** IMPORTANT - WORK IS REQUIRED ***"
+      puts "In order to make use of the global session, you will need to ensure that it"
+      puts "is installed to the Rack middleware stack. You can do so by adding an extra"
+      puts "line in your environment.rb inside the Rails initializer block, like so:"
+      puts
+      puts "         Rails::Initializer.run do |config|"
+      puts "ADD>>      require 'global_session'"
+      puts "ADD>>      GlobalSession::Rails.activate(config)"
+      puts "         end"
+
+    end
+  end
+end

data/rails_generators/{global_session_config → global_session}/templates/global_session.yml.erb

@@ -8,10 +8,8 @@ common:
     # Untrusted attributes of the global session
     insecure:
     - account
-  # Enable local session integration in order to use the ActionController
-  # method #session to access both local AND global session state, with
-  # global attributes always taking precedence over local attributes.
-  integrated: true
+  #If the session cookie is ephemeral, it goes away when the user closes the browser.
+  #Otherwise it stays around
   ephemeral: false
   
 # Test/spec runs
@@ -19,7 +17,7 @@ test:
   timeout: 15 #minutes
   renew: 5 #minutes before expiration
   cookie:
-    name: _session_gbl
+    name: global_session
   #the name of the local authority (optional)
   authority: test
   #which authorities this app will trust
@@ -31,7 +29,7 @@ development:
   timeout: 60
   renew: 15
   cookie:
-    name: _session_gbl
+    name: global_session
   authority: development
   trust:
   - development
@@ -42,7 +40,7 @@ production:
   timeout: 60
   renew: 15
   cookie:
-    name: _session_gbl
+    name: global_session
     domain: <%= app_domain %>
   authority: production
   trust:

data/rails_generators/global_session_authority/global_session_authority_generator.rb

@@ -4,7 +4,7 @@ class GlobalSessionAuthorityGenerator < Rails::Generator::Base
 
     @app_name  = File.basename(::Rails.root)
     @auth_name = args.shift
-    raise ArgumentError, "Must specify name for global session authority, e.g. 'mycoolapp'" unless @auth_name
+    raise ArgumentError, "Must specify name for global session authority, e.g. 'prod'" unless @auth_name
   end
 
   def manifest

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: global_session
 version: !ruby/object:Gem::Version 
-  hash: 59
+  hash: 23
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 9
   - 0
-  version: 0.9.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Tony Spataro
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-07 00:00:00 -08:00
+date: 2011-01-01 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -169,11 +169,11 @@ files:
 - lib/global_session/rails/action_controller_instance_methods.rb
 - lib/global_session/session.rb
 - rails/init.rb
+- rails_generators/global_session/USAGE
+- rails_generators/global_session/global_session_generator.rb
+- rails_generators/global_session/templates/global_session.yml.erb
 - rails_generators/global_session_authority/USAGE
 - rails_generators/global_session_authority/global_session_authority_generator.rb
-- rails_generators/global_session_config/USAGE
-- rails_generators/global_session_config/global_session_config_generator.rb
-- rails_generators/global_session_config/templates/global_session.yml.erb
 has_rdoc: true
 homepage: http://github.com/xeger/global_session
 licenses: []

data/rails_generators/global_session_config/global_session_config_generator.rb

@@ -1,19 +0,0 @@
-class GlobalSessionConfigGenerator < Rails::Generator::Base
-  def initialize(runtime_args, runtime_options = {})
-    super
-
-    @app_name   = File.basename(::Rails.root)
-    @app_domain = args.shift
-    raise ArgumentError, "Must specify DNS domain for global session cookie, e.g. 'example.com'" unless @app_domain
-  end
-
-  def manifest
-    record do |m|
-      
-      m.template 'global_session.yml.erb',
-                 'config/global_session.yml',
-                 :assigns=>{:app_name=>@app_name,
-                            :app_domain=>@app_domain}
-    end
-  end
-end