micro_sessions 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Ben Hughes
+
+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.

data/README.rdoc

@@ -0,0 +1,72 @@
+== Micro Sessions
+
+In terms of passing data amongst HTTP requests there are really two options:
+* Param or form data passing
+* Storing in cookies
+* Storing in server-side session, keyed off an ID stored as a cookie.
+
+For a certain application where you're using number 3, this comes at a cost - the session is "global".  In other words, in a single browser window with multiple tabs, the server side cannot distinguish between individual "sessions" *within* that browser session. This gem introduces a third, more granular method:
+* Storing in server-side session, keyed off an ID stored as a cookie *and* keyed off a request parameter.
+
+This could be useful in instances such as a very complex wizard where transmitting the entire history of data RESTfully via param passing may not be feasible, yet you'd still like to support multiple tabs within the same browser window separately.
+
+== In-Progress
+
+This gem is not useable and is being continually worked on.  Will be released as 0.1.0 once reasonably working and stable.
+
+DO NOT USE!
+
+== Installation
+
+This gem requires ActionPack and ActiveSupport 3.0 or greater.
+
+Include the gem in your Gemfile:
+  
+  gem "micro_sessions"
+
+== Usage
+
+Simply include the middleware in your controller:
+
+  class ApplicationController
+    micro_sessions
+  end
+
+By default the name of the request parameter used to differentiate micro-sessions is "_msid", though this can be configured:
+  
+  class ApplicationController
+    micro_sessions :key => "_msid"
+  end
+
+By default the key generated will be a 10-digit random hash, though this can be configured as well:
+
+  class ApplicationController
+    micro_sessions :type => :integer, :length => 10
+  end
+
+Valid values for +:type+: are:
+* +:random_hash+
+* +:integer+  (simply increments from one)
+* +:random_integer+ (random integer with a maximum of +:length+ digits)
+
+Session data is accessible to the controller and view through the +micro_session+ object, which works identically to the +session+ object but it specific to the micro-session:
+
+  micro_session[:key] = "Value"
+  micro_session[:key] # => "Value"
+
+When transitioning between pages for which you'd like to keep the micro-session alive, the request parameter must be passed along with any link, form, or redirect.  The preferred way is to make use of the new +:micro_session+ option on available on the +url_for+ helper, which will accept either a specific value or just "true" to use the "current" micro-session to this request:
+  
+  link_to user_path(@user, :micro_session => true)
+  redirect_to user_project_path([@user, @project], :micro_session => true)
+
+If you wish to transmit the identifier via a form, be sure to include the hidden field:
+  
+  <% form_for(@user) do |f| %>
+    <%= micro_session_hidden_field %>
+    ...
+  <% end %>
+
+Destroying a micro-session is as easy as:
+  
+  micro_session.destroy
+

data/init.rb

@@ -0,0 +1,3 @@
+require "micro_sessions"
+
+MicroSessions::Railtie.insert

data/lib/micro_sessions/controller.rb

@@ -0,0 +1,30 @@
+module MicroSessions
+  module Controller
+    extend ActiveSupport::Concern
+  
+    module ClassMethods
+      def micro_sessions(options = {})
+        options.stringify_keys!
+        options.assert_valid_keys(:param, :param_type, :key, :length, :counter)
+        
+        options[:param] ||= "_msid"
+        options[:key] ||= "_micro_sessions"
+        options[:param_type] ||= :hash
+        options[:length] ||= 10
+        options[:counter] ||= 1
+        
+        class_inheritable_accessor :micro_session_options
+        self.micro_session_options = options
+        
+        class_eval do
+          def micro_session
+            @micro_session ||= MicroSessions::MicroSession.new(self)
+          end
+          
+          helper_method :micro_session
+          helper_method :micro_session_options
+        end
+      end
+    end
+  end
+end

data/lib/micro_sessions/helpers.rb

@@ -0,0 +1,27 @@
+module MicroSessions
+  module Helpers
+    module UrlHelper
+      extend ActiveSupport::Concern
+    
+      module InstanceMethods
+        def url_for(options = {})
+          if options.is_a?(Hash) && ms_value = options.delete(:micro_sessions) && !micro_session.empty?
+            options[micro_session.options[:param]] = (ms_value == true ? micro_session.id : ms_value)
+          end
+        
+          super
+        end
+      end
+    end
+    
+    module FormTagHelper
+      extend ActiveSupport::Concern
+      
+      module InstanceMethods
+        def micro_session_hidden_field
+          hidden_field_tag controller.class.micro_session_options[:param], micro_session.id
+        end
+      end
+    end
+  end
+end

data/lib/micro_sessions/micro_session.rb

@@ -0,0 +1,40 @@
+module MicroSessions
+  class MicroSession
+    def initialize(controller)
+      @controller = controller
+    end
+    
+    def options
+      @controller.class.micro_session_options
+    end
+    
+    def data
+      @controller.session[options[:key]] ||= {}
+      @controller.session[options[:key]][id] ||= {}
+    end
+    
+    delegate :empty?, :[], :[]=, :to_h, :to_hash, :to => :data
+    
+    def id
+      @id ||= id_from_params || generate_id
+    end
+    
+    
+    protected
+    
+    def id_from_params
+      @controller.params[options[:param]] if @controller.params
+    end
+    
+    def generate_id
+      case options[:param_type]
+      when :hash
+        ActiveSupport::SecureRandom.hex(options[:length] / 2)
+      when :integer
+        self.counter += 1
+      when :random_integer
+        ActiveSupport::SecureRandom.integer
+      end
+    end
+  end
+end

data/lib/micro_sessions/railtie.rb

@@ -0,0 +1,19 @@
+module MicroSessions
+  if defined?(Rails::Railtie)
+    class Railtie < Rails::Railtie
+      initializer "micro_sessions.insert" do
+        ActiveSupport.on_load(:action_controller) do
+          MicroSessions::Railtie.insert
+        end
+      end
+    end
+  end
+  
+  class Railtie
+    def self.insert
+      ActionController::Base.send(:include, MicroSessions::Controller)
+      ActionView::Helpers::UrlHelper.send(:include, MicroSessions::Helpers::UrlHelper)
+      ActionView::Helpers::FormTagHelper.send(:include, MicroSessions::Helpers::FormTagHelper)
+    end
+  end
+end

data/lib/micro_sessions/version.rb

@@ -0,0 +1,3 @@
+module MicroSessions
+  VERSION = "0.1.0"
+end

data/lib/micro_sessions.rb

@@ -0,0 +1,25 @@
+unless defined?(ActionController)
+  begin
+    require "action_pack"  
+    require "action_controller"
+    require "action_view"
+  rescue LoadError
+    require "rubygems"
+    require_gem "actionpack"
+  end
+end
+
+module MicroSessions
+  extend ActiveSupport::Concern
+  extend ActiveSupport::Autoload
+  
+  autoload :Controller
+  autoload :Helpers
+  autoload :MicroSession
+  
+  included do
+    include MicroSessions::Controller
+  end
+end
+
+require "micro_sessions/railtie"

data/spec/controller_spec.rb

@@ -0,0 +1,80 @@
+require "spec_helper"
+
+describe MicroSessions::Controller do
+  context "with a controller" do
+    before do
+      @controller_class = class SampleController < ActionController::Base
+        micro_sessions
+        self
+      end
+    end
+    
+    it "should default param to _msid" do
+      @controller_class.micro_session_options[:param].should == "_msid"
+    end
+    
+    it "should default key to _micro_sessions" do
+      @controller_class.micro_session_options[:key].should == "_micro_sessions"
+    end
+    
+    it "should default length to 10" do
+      @controller_class.micro_session_options[:length].should == 10
+    end
+    
+    it "should default counter to 1" do
+      @controller_class.micro_session_options[:counter].should == 1
+    end
+    
+    context "an instance of the controller" do
+      before do
+        @controller = @controller_class.new
+        @controller.stub(:params).and_return({})
+      end
+      
+      it "should expose #micro_session as a method" do
+        @controller.micro_session.should be_an_instance_of(MicroSessions::MicroSession)
+      end
+      
+      it "should generate a 10-character hash id" do
+        @controller.micro_session.id.should be_a(String)
+        @controller.micro_session.id.size.should == 10
+      end
+      
+      context "with micro session data and another controller" do
+        before do
+          @micro_session_data = {
+            :integer => 1,
+            :string => "String"
+          }
+          
+          @another_controller = @controller_class.new
+          @another_controller.stub(:params).and_return({})
+          @another_controller.stub(:session).and_return({
+            "_micro_sessions" => {@controller.micro_session.id => @micro_session_data}
+          })
+        end
+        
+        context "without passing id" do
+          subject do
+            @another_controller.micro_session
+          end
+          
+          it "should not have data" do
+            subject.data.should == {}
+          end
+        end
+      
+        context "when passing id" do
+          subject do
+            @another_controller.stub(:params).and_return({"_msid" => @controller.micro_session.id})
+            @another_controller.micro_session
+          end
+          
+          it "should have data" do
+            subject.data.should == @micro_session_data
+          end
+        end
+      end
+    end
+  end
+end

data/spec/helpers_spec.rb

@@ -0,0 +1,24 @@
+require "spec_helper"
+
+describe MicroSessions::Helpers do
+  before do
+    @controller_class = Class.new(ActionController::Base)
+    @controller_class.stub(:micro_session_options).and_return(:param => "_msid")
+    @helpers = ActionView::Base.new
+    @helpers.stub(:controller).and_return(@controller_class.new)
+    @helpers.stub(:micro_session).and_return(mock(:id => "abc123"))
+  end
+  
+  it "should respond to #micro_session_hidden_field" do
+    @helpers.should respond_to(:micro_session_hidden_field)
+  end
+  
+  it "should render correct micro_session_hidden_field" do
+    @helpers.micro_session_hidden_field.should == %{<input id="_msid" name="_msid" type="hidden" value="abc123" />}
+  end
+  
+  # TODO: This is way too complex to test, requires an enormous amount of stubbing... Need a real Rails app.
+  # it "should render correct link_to with :micro_sessions => true" do
+  #   @helpers.url_for
+  # end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require "rubygems"
+require "rspec"
+require "active_support"
+require "action_pack"
+
+require File.dirname(__FILE__) + "/../init"
+
+RSpec.configure do |c|
+  
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification 
+name: micro_sessions
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Ben Hughes
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-23 00:00:00 +03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: actionpack
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id002
+description: Provides 'micro-sessions' within the global sessions object keyed off an identifier.
+email: ben@railsgarden.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/micro_sessions/controller.rb
+- lib/micro_sessions/helpers.rb
+- lib/micro_sessions/micro_session.rb
+- lib/micro_sessions/railtie.rb
+- lib/micro_sessions/version.rb
+- lib/micro_sessions.rb
+- spec/controller_spec.rb
+- spec/helpers_spec.rb
+- spec/spec_helper.rb
+- LICENSE
+- README.rdoc
+- init.rb
+has_rdoc: true
+homepage: http://github.com/rubiety/micro_sessions
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 19
+      segments: 
+      - 1
+      - 3
+      - 4
+      version: 1.3.4
+requirements: []
+
+rubyforge_project: micro_sessions
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Keyed sessions within the global sessions object.
+test_files: []
+