cookies_manager 0.1.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.yardoc
+doc

data/.rspec

@@ -0,0 +1 @@
+--color

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.8.7@cookies_manager --create

data/CHANGELOG.rdoc

@@ -0,0 +1,4 @@
+0.1.0 (Nov 07, 2011)
+
+* Initial release
+

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in cookies_manager.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Christophe Levand
+
+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,66 @@
+= CookiesManager
+
+CookiesManager is a simple tool that provides a convenient way to manage any kind of data in the cookies (strings, arrays, hashes, etc.):
+- The data you store in the cookies is automatically marshalled, zipped, and base64-encoded.
+- The data you ask to retrieve from the cookies is read from a cache, which spares the need for reverse transformation as long as the cache is in sync with the cookies. When the cache is out of sync, CookiesManager automatically resynchronizes the cache by reading the data from the cookies and processing reverse transformation (base64-decoding, unzipping, unmarshalling).
+- The cache is defined somehow at the controller instance level. Thus, each HTTP request has its own cache for its whole lifetime.
+
+== Installation
+
+In <b>Rails 2</b>, add this to your environment.rb file.
+
+  config.gem "cookies_manager"
+
+== Getting started
+
+=== Basic usage
+
+To activate the feature, simply call +load_cookies_manager+ on your controller class:
+
+ class YourController < ActionController::Base
+   load_cookies_manager # This instantiates a new CookiesManager accessible through the cookies_manager helper method
+
+<i>Hint: You can call +load_cookies_manager+ on your ApplicationController class to enable the feature for all your controllers.</i>
+
+Next, you can refer the CookiesManager instance by calling the +cookies_manager+ helper method from your controllers and views:
+
+ len_bytes = cookies_manager.write('a_key', ['an', 'array']) # store the array as is in the cache, and as a base-64 string in the cookies
+ my_array = cookies_manager.read('a_key') # retrieves the array from the cache (or from the cookies if the cache is not in sync)
+ my_deleted_array = cookies_manager.delete('a_key') # removes the array from both the cookies and the cache
+
+=== Supported options
+
+All supported options are fully described along with some examples in the {file:../CookiesManager/Base.html CookiesManager::Base documentation}. 
+
+== When to use it?
+
+=== CookiesManager vs native cookies
+
+Whenever you need to store in the cookies some data somewhat more complex than just simple US-ASCII strings (ex: hashes, arrays, etc.), the CookiesManager may be
+more convenient to use than the native cookies hash. 
+
+Note that you can use both CookiesManager and the cookies hash. If needed, the CookiesManager cache is automatically resynchronized from the cookies.
+
+=== CookiesManager vs session
+
+Whenever a cookies storage management is more suited to your needs than a session storage management, the CookiesManager may be a good option if the data you want to
+store is more complex than just simple US-ASCII strings. For example, there may be times when you need to persist in the cookies some non-sensitive data much longer
+than the session length, such as user display preferences.
+
+== Important notes
+
+- If your application is multi-threaded, using CookiesManager is threadsafe as long as your threads refer the same CookiesManager instance.
+- Unless you know what you are really doing, do not store large data in your cookies, since these are included in HTTP request headers.
+- Do not store model objects in cookies (nor in session). For more explanation, check {http://railscasts.com/episodes/13-dangers-of-model-in-session Ryan Bates's screencast about dangers of model in session}.
+
+== Running the tests
+
+RSpec 2 is used for testing. To get the specs running, check {file:spec/README spec/README}.
+
+== Coming up next
+- Adapt the gem to support Ruby 1.9.x and Rails 3.
+
+== Changes
+
+{include:file:CHANGELOG}
+

data/Rakefile

@@ -0,0 +1,14 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+desc "Run RSpec"
+RSpec::Core::RakeTask.new do |t|
+  t.verbose = false
+end
+
+desc "Run all specs except slow tests"
+task :skip_slow do
+  system "rake spec SKIP_SLOW=true"
+end
+
+task :default => :spec

data/cookies_manager.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "cookies_manager/version"
+
+Gem::Specification.new do |s|
+  s.name        = "cookies_manager"
+  s.version     = CookiesManager::VERSION
+  s.authors     = ["Christophe Levand"]
+  s.email       = ["levandch@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Simple cookies management tool for Rails}
+  s.description = %q{Simple cookies management tool for Rails that provides a convenient way to manage any kind of data in the cookies (strings, arrays, hashes, etc.)}
+
+  s.rubyforge_project = "cookies_manager"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rspec', '~> 2.7.0'
+  s.add_development_dependency 'actionpack', '~> 2.3.14'
+  s.add_development_dependency 'rr', '~> 1.0.4'
+  s.add_development_dependency 'aquarium', '~> 0.4.4'
+end

data/init.rb

@@ -0,0 +1 @@
+require 'cookies_manager'

data/lib/cookies_manager/base.rb

@@ -0,0 +1,178 @@
+require 'aquarium'
+
+module CookiesManager
+  # The base class of CookiesManager 
+  class Base
+    include Aquarium::DSL # AOP Filters are defined at the end of the class
+    
+    attr_accessor :cookies # The cookies hash to be based on
+    
+    # Constructs a new CookiesManager instance based on a cookies hash
+    #
+    # The CookiesManager instance is created automatically when you call the +load_cookies_manager+ class method
+    # on your controller, so you don't need to instantiate it directly.
+    #
+    # === Example:
+    # Inside your controller, call the +load_cookies_manager+ method:
+    #
+    #   class YourController < ActionController::Base
+    #     load_cookies_manager
+    #
+    def initialize(input_cookies)
+      self.cookies = input_cookies
+    end
+
+    # Reads the data object corresponding to the key.
+    #
+    # Reads from the cache instance variable, or from the cookies if the cache is not in sync with the cookies.
+    # Cache desynchronization can occur when the cookies hash is modified directly.
+    # The cache is automatically re-synchronized if out of sync.
+    #
+    # If option +:unpack+ is set to true, data will be successively base64-decoded, unzipped, and unmarshalled. This option is used only when the data
+    # is retrieved from the cookies hash (i.e. the cache is not in sync with the cookies).
+    #
+    # === Example: 
+    #    data = cookies_manager.read('my_key') # reads the data associated with the key 'my_key'
+    #
+    # @param [String or Symbol] key a unique key corresponding to the data to read
+    # @option opts [Boolean] :unpack if true, successively base64-decode, unzip, and unmarshall the data. Default is false.
+    # @return [Object] the data associated with the key 
+    #
+    def read(key, opts = {})
+      result = nil
+      getMutex(key).synchronize do
+        result = read_from_cache_or_cookies(key, opts)  
+      end      
+      return result
+    end
+    
+    # Writes the data object and associates it with the key.
+    #
+    # Data is stored in both the cookies and the cache.
+    # 
+    # By default, before being stored in the cookies, data is marshalled, zipped, and base64-encoded. Although this feature is recommended, you can disable it by passing the option +:skip_pack+ if you consider your data can be stored as is in the cookies (ex: US-ASCII string).
+    #
+    # === Examples:
+    #    
+    #    array_data = {:some_item => "an item", :some_array => ['This', 'is', 'an', 'array']}
+    #    #store the data in the cookies as a base64-encoded string, for one hour:
+    #    len_bytes1 = cookies_manager.write('key_for_my_array', data, :expires => 1.hour.from_now)
+    #
+    #    simple_data = "a simple string"
+    #    # store the data as in in the cookies, and keep it as long as the browser remains open:
+    #    len_bytes2 = cookies_manager.write('key_for_my_simple_data', simple_data, :skip_pack => true)
+    #
+    # @param [String or Symbol] key a unique key to associate the data with
+    # @param [Hash] opts a customizable set of options, built on top of the native set of options supported when {http://api.rubyonrails.org/v2.3.8/classes/ActionController/Cookies.html setting cookies}
+    # @option opts [Boolean] :skip_pack if true, DO NOT marshall, zip, nor base64-encode the data. Default is false.     
+    # @option opts [String] :path the path for which this cookie applies. Defaults to the root of the application.
+    # @option opts [String] :domain the domain for which this cookie applies.
+    # @option opts [String] :expires the time at which this cookie expires, as a Time object.
+    # @option opts [String] :secure whether this cookie is a only transmitted to HTTPS servers. Default is +false+.
+    # @option opts [String] :httponly whether this cookie is accessible via scripting or only HTTP. Defaults to +false+.
+    # @return [Integer] the number of bytes written in the cookies
+    #
+    def write(key, data, opts = {})
+      unpacked_data = data
+      data = pack(data) unless opts[:skip_pack]
+      result = nil
+      getMutex(key).synchronize do
+        cache[key] ||= {}
+        result = cookies[key] = {:value => data}.merge(opts) # store the packed data in the cookies hash
+        cache[key][:unpacked_data] = unpacked_data # store the unpacked data in the cache for fast read in the read method
+        cache[key][:packed_data] = data # store the packed data in the cache for fast change diff in the read method
+      end
+      return result[:value].try(:bytesize) || 0
+    end
+        
+    # Deletes the data corresponding to the key.
+    #
+    # Removes the data from both the cookies and the cache, and return it.
+    # The returned value is read from the cache if this is in sync with the cookies. Otherwise, the data is read from the cookies, in which case it is successively
+    # base64-decoded, unzipped, and unmarshalled if option +:unpack+ is set to true.
+    #
+    # === Example:
+    #     data = cookies_manager.delete('my_key')  # deletes the data associated with the key 'my_key'
+    #
+    # @param [String or Symbol] key a unique key corresponding to the data to delete   
+    # @option opts (see #read)
+    # @return (see #read) 
+    #
+    def delete(key, opts = {})
+      result = nil
+      getMutex(key).synchronize do
+        result = read_from_cache_or_cookies(key, opts)
+        cookies.delete(key)
+        cache.delete(key)
+      end
+      return result
+    end
+    
+    #=====#
+    private
+    #=====#
+    
+    def cache
+      @cache ||= {} # The cookies cache
+    end
+    
+    def mutexes
+      @mutexes ||= {} # A hash composed of {key;mutex} pairs where each mutex is used to synchronize operations on the data associated with the key
+    end
+    
+    def global_mutex
+      @global_mutex ||= Mutex.new # A global mutex to synchronize accesses to the mutexes hash
+    end
+    
+    # reads from the cache if in sync. Otherwise, reads from the cookies and resynchronizes the cache for the given key
+    def read_from_cache_or_cookies(key, opts)
+      result = nil
+      data_from_cookies = cookies[key]
+      cache[key] ||= {}
+      if cache[key][:packed_data] == data_from_cookies # checks whether cache is in sync with cookies
+        result = cache[key][:unpacked_data] # reads from cache
+      else # cache not in sync
+        result = opts[:unpack] ? unpack(data_from_cookies) : data_from_cookies # read from cookies
+        # updates the cache
+        cache[key][:packed_data] = data_from_cookies
+        cache[key][:unpacked] = result
+      end
+      return result
+    end
+    
+    def getMutex(key)
+      global_mutex.synchronize do # synchronize accesses to the mutexes hash
+        mutexes[key] ||= Mutex.new
+      end      
+    end
+    
+    def pack(data)
+      Base64.encode64(ActiveSupport::Gzip.compress(Marshal.dump(data)))
+    end
+
+    def unpack(data)
+      Marshal.load(ActiveSupport::Gzip.decompress(Base64.decode64(data)))
+    end    
+    
+    #=================#
+    #== AOP Filters ==#
+    #=================#
+    
+    # Since Aquarium sets the arities of observered methods to -1, we need to save the methods arities in a hash declared as a class variable
+    self.instance_methods(false).each { |method| (@method_arities ||= {})[method.to_sym] = instance_method(method).arity }
+    
+    around :methods => [:read, :write, :delete] do |join_point, object, *args|
+      key = (args[0] = args[0].to_s) # we should stick with string keys since the cookies hash does not support indifferent access (i.e. :foo and "foo" are different keys), although this has changed in rails 3.1
+      opts = args[last_arg_index(join_point.method_name)] # retrieve the options arg (last argument)
+      opts.symbolize_keys! if opts.is_a?(Hash)
+      join_point.proceed(*args)
+    end
+
+    # Returns the index of the last arg in the method signature
+    def self.last_arg_index(method_name)
+      instance_eval { @method_arities[method_name] }.abs - 1
+    end
+    
+  end
+    
+end

data/lib/cookies_manager/controller_additions.rb

@@ -0,0 +1,29 @@
+module CookiesManager
+
+  # This module provides a CookiesManager facility for your controllers.
+  # It is automatically extended by all controllers.
+  module ControllerAdditions
+    
+    # Sets up a before filter that creates a new CookiesManager into an instance variable,   
+    # which is made available to all views through the +cookies_manager+ helper method.
+    #
+    # You can call this method on your controller class as follows:
+    #
+    #   class YourController < ApplicationController
+    #     load_cookies_manager
+    #   
+    def load_cookies_manager
+      self.before_filter do |controller|
+        # defines a CookiesManager instance variable, based on the cookies hash
+        controller.instance_variable_set(:@_cookies_manager, CookiesManager::Base.new(controller.cookies))
+        # wraps the instance variable in a the +cookies_manager+ method
+        define_method :cookies_manager, proc { controller.instance_variable_get(:@_cookies_manager) }
+        # makes the +cookies_manager+ method available to all views as a helper method
+        helper_method :cookies_manager
+      end
+    end
+  end
+end
+
+# Automatically add all ControllerAdditions methods to controller classes as class methods 
+ActionController::Base.extend CookiesManager::ControllerAdditions

data/lib/cookies_manager/version.rb

@@ -0,0 +1,3 @@
+module CookiesManager
+  VERSION = "0.1.1"
+end

data/lib/cookies_manager.rb

@@ -0,0 +1,4 @@
+require 'cookies_manager/version'
+require 'cookies_manager/base'
+require 'cookies_manager/controller_additions'
+

data/spec/README.rdoc

@@ -0,0 +1,21 @@
+= CookiesManager Specs
+
+== Running the specs
+
+1. Run the +bundle+ command to install the necessary gems
+2. Run the +rake+ command to run all the specs
+
+  bundle
+  rake
+
+Some of the specs, covering race conditions in multithreaded contexts, pause in purpose some threads for a few seconds through AOP to test critical sections. Those "slow" tests can be easily skipped by passing +skip_slow+ as an argument to the +rake+ command:
+
+  rake skip_slow
+
+However, I recommend running all the specs whenever you change the code.
+
+== Ruby versions
+
+Currently, the specs require Ruby 1.8.7.
+
+Ruby 1.9.x support is coming up next.  

data/spec/cookies_manager/base_spec.rb

@@ -0,0 +1,319 @@
+require 'spec_helper'
+
+# Useful macros for testing
+module MacrosForCookiesManager
+  def pack(data)
+    Base64.encode64(ActiveSupport::Gzip.compress(Marshal.dump(data)))
+  end
+  
+  def unpack(data)
+    Marshal.load(ActiveSupport::Gzip.decompress(Base64.decode64(data)))
+  end
+end
+
+include MacrosForCookiesManager
+include Aquarium::Aspects
+
+describe CookiesManager::Base do
+  before(:all) do
+    @complex_data = {:some_array => [1,2,3], :some_hash => {:a => 1, :b => 2}}
+    @simple_data = "this is a simple string"
+  end
+  
+  let(:cookies) { TestController.new.cookies }
+  subject { CookiesManager::Base.new(cookies) }  
+  
+  describe "#write" do
+    describe "#write + pack data" do
+      context "when write complex data" do
+        before { @bytesize = subject.write('my_key', @complex_data) }
+        specify { @bytesize.should == pack(@complex_data).bytesize }
+        specify { unpack(cookies['my_key']).should eql @complex_data }      
+      end    
+      context "when write nil value" do
+        before { @bytesize = subject.write('my_key', nil) }
+        specify { @bytesize.should == pack(nil).bytesize }
+        specify { unpack(cookies['my_key']).should be_nil}
+      end
+    end
+    describe "write without packing data" do
+      context "when write simple data" do
+        before { @bytesize = subject.write('my_key', @simple_data, :skip_pack => true) }
+        specify { @bytesize.should == @simple_data.bytesize }
+        specify { cookies['my_key'].should eql @simple_data }
+      end
+      context "when write nil value" do
+        before { @bytesize = subject.write('my_key', nil, :skip_pack => true) }
+        specify { @bytesize.should == 0 }
+        specify { cookies['my_key'].should be_nil}
+      end
+    end
+    describe "#write + set expiration date" do
+      before { subject.write(@key = 'my_key', @complex_data, :expires => (@expiration_date = 2.hours.from_now)) }
+      specify { Time.parse(cookies.controller.response["Set-Cookie"].select { |cookie_str|  cookie_str =~ /\A#{@key}=/ }.last[/expires=(.*?)(;|\Z)/, 1]).to_i.should == @expiration_date.to_i } #parse the expiration date from the cookies string in the response header using some simple non-greedy regex and convert it to epochs to test the time equality. This conversion technique works only for timestamps between 1901-12-13 and 2038-01-19, but is acceptable for our tests.        
+    end
+    describe "#write with nil key" do
+      before { subject.write(nil, @complex_data) }
+      specify { unpack(cookies[nil]).should eql @complex_data }
+      specify { unpack(cookies['']).should eql @complex_data }
+    end
+    describe "#write with empty string key" do
+      before { subject.write('', @complex_data) }
+      specify { unpack(cookies[nil]).should eql @complex_data }
+      specify { unpack(cookies['']).should eql @complex_data }
+    end
+  end
+  
+  describe "#read" do
+    describe "#read with unknown key" do
+      specify { subject.read('unknown_key').should be_nil }
+    end
+    describe "#read some data previously stored through CookiesManager" do
+      context "when reading non-nil data" do
+        before { subject.write('my_key', @complex_data) }
+        specify { subject.read('my_key').should eql @complex_data }
+      end    
+      context "when reading a nil value" do
+        before { subject.write('my_key', nil) }
+        specify { subject.read('my_key').should be_nil }
+      end
+      context "when reading some data stored with a nil key" do
+        before { subject.write(nil, @complex_data) }
+        specify { subject.read(nil).should eql @complex_data }
+        specify { subject.read('').should eql @complex_data }
+      end
+    end
+    describe "#read some data previously stored directly into the cookies hash" do
+      context "when reading non-nil data" do
+        before { cookies['my_key'] = {:value => @complex_data} }
+        specify { subject.read('my_key').should eql @complex_data }
+      end
+      context "when reading a nil value" do
+        before { cookies['my_key'] = {:value => nil } }
+        specify { subject.read('my_key').should be_nil }
+      end
+      context "when reading some data stored with a nil key" do
+        before { cookies[nil] = {:value => @complex_data} }
+        specify { subject.read(nil).should eql @complex_data }
+        specify { subject.read('').should eql @complex_data }
+      end
+      context "when reading some data stored with an empty string key" do
+        before { cookies[''] = {:value => @complex_data} }
+        specify { subject.read(nil).should eql @complex_data }
+        specify { subject.read('').should eql @complex_data }
+      end
+    end
+    describe "#read some data previously stored through CookiesManager but later modified directly inside the cookies hash" do
+      context "when read some simple data" do
+        before do
+          subject.write('my_key', @simple_data)
+          cookies['my_key'] = {:value => (@new_simple_data = "some new data")}
+        end
+        specify { subject.read('my_key').should eql @new_simple_data }
+      end
+      context "when reading some complex data" do
+        before do
+          subject.write('my_key', @complex_data)
+          @new_complex_data = @complex_data.merge(:some_new_item => 'it modifies the data')
+          cookies['my_key'] = {:value => pack(@new_complex_data)}
+        end
+        specify { subject.read('my_key', :unpack => true).should eql @new_complex_data }
+        specify { unpack(subject.read('my_key')).should eql @new_complex_data } #if :unpack option is omitted, needs to unpack manually
+      end
+    end
+    describe "read with key symbol/string indifferent access (ex: :foo, 'foo')" do
+      shared_examples_for "reading with indifferent access key" do
+        specify { subject.read(:my_key).should eql @complex_data }  
+        specify { subject.read('my_key').should eql @complex_data }
+        specify { unpack(cookies['my_key']).should eql @complex_data }
+      end
+      context "when data has been written with a key of type symbol" do
+        before { subject.write(:my_key, @complex_data) }
+        it_should_behave_like "reading with indifferent access key"
+      end
+      context "when data has been written with a key of type string" do
+        before { subject.write('my_key', @complex_data) }
+        it_should_behave_like "reading with indifferent access key"
+      end
+    end
+  end
+  
+  describe "#delete" do
+    describe "#delete existing data" do
+      shared_examples_for "when deleting existing data" do
+        before { @result = subject.delete('my_key') }
+        specify { @result.should eql @complex_data }
+        specify { subject.read('my_key').should be_nil }
+      end
+      context "when data has been previously stored through CookiesManager" do
+        before { subject.write('my_key', @complex_data) }
+        it_should_behave_like "when deleting existing data"
+      end
+      context "when data has been previously stored directly into the cookies hash" do
+        before { cookies['my_key'] = {:value => @complex_data} }
+        it_should_behave_like "when deleting existing data"
+      end
+    end
+    describe "#delete non-existent data" do
+      specify { subject.delete('unknown_key').should be_nil }
+    end
+    describe "#delete with key symbol/string indifferent access (ex: :foo, 'foo')" do
+      shared_examples_for "when deleting with key of type symbol or string" do
+        specify { @result.should eql @complex_data }
+        specify { subject.read(:my_key).should be_nil }
+        specify { subject.read('my_key').should be_nil }
+      end
+      shared_examples_for "when data has been written with a key of type symbol or string" do
+        context "when deleting with key of type symbol" do
+          before { @result = subject.delete(:my_key) }
+          it_should_behave_like "when deleting with key of type symbol or string"
+        end
+        context "when deleting with key of type string" do
+          before { @result = subject.delete('my_key') }
+          it_should_behave_like "when deleting with key of type symbol or string"
+        end
+      end
+      context "when data has been written with a key of type symbol" do        
+        before { subject.write(:my_key, @complex_data) }
+        it_should_behave_like "when data has been written with a key of type symbol or string"
+      end      
+      context "when data has been written with a key of type string" do
+        before { subject.write('my_key',@complex_data) }
+        it_should_behave_like "when data has been written with a key of type symbol or string"
+      end
+    end
+  end
+  
+  describe "#symbol/string indifferent keys in options hash" do
+    describe "#read" do
+      before { cookies['my_key'] = pack(@complex_data) }
+      specify { subject.read('my_key', :unpack => true).should eql @complex_data }
+      specify { subject.read('my_key', 'unpack' => true).should eql @complex_data }
+    end
+    describe "#write" do
+      before do
+        subject.write('key1', @simple_data, :skip_pack => true)
+        subject.write('key2', @simple_data, 'skip_pack' => true)
+      end
+      specify { cookies['key1'].should eql @simple_data }
+      specify { cookies['key2'].should eql @simple_data }
+    end
+    describe "#delete" do
+      before { cookies['my_key'] = pack(@complex_data) }
+      specify { subject.delete('my_key', :unpack => true).should eql @complex_data }
+      specify { subject.delete('my_key', 'unpack' => true).should eql @complex_data }
+    end
+  end
+  
+  describe "#multi-threading", :slow do
+    def print_inside_critical_section(method_name)
+      p "Inside the critical section, when calling cookies#{method_name}, the #{thread_name} thread pauses for #{sleep(2)} seconds, to make the other thread wait at the entrance of the critical section..."
+    end  
+    
+    def print_wait_before_action(action)
+      p "Before calling ##{action}, wait for #{sleep(1)} seconds to let the #{thread_name} thread lock the critical section..."
+    end
+    
+    def run_thread
+      Thread.new do
+        Thread.current["name"] = thread_name
+        yield
+      end      
+    end
+    
+    def build_aspect(method_name)
+      Aspect.new :around, :calls_to => method_name, :on_objects => subject.cookies do |join_point, object, *args|          
+        print_inside_critical_section(join_point.method_name) if Thread.current["name"] == thread_name
+        join_point.proceed
+      end      
+    end
+  
+    before { subject.write('my_key', @original_data = 'original data') }
+    after { @aspect.unadvise }
+    
+    describe "#a thread is reading with a key" do
+      let(:thread_name) { :reader }
+      before do
+        @aspect = build_aspect('[]')
+        @reader = run_thread { @result = subject.read('my_key') }
+      end
+      shared_examples_for 'when another thread wants to access the data with the same key while reading' do
+        it "should wait until the reader finishes reading" do
+          @reader.join
+          @result.should eql @original_data
+        end
+      end
+      context "when another thread wants to write some new data with the same key" do
+        before do
+          print_wait_before_action(:write)
+          subject.write('my_key', @complex_data)
+        end
+        it_should_behave_like 'when another thread wants to access the data with the same key while reading'
+      end
+      context "when another thread wants to delete with the same key" do
+        before do
+          print_wait_before_action(:delete)
+          subject.delete('my_key')
+        end
+        it_should_behave_like 'when another thread wants to access the data with the same key while reading'
+      end      
+    end
+    describe "#a thread is writing with a key" do
+      let(:thread_name) { :writer }
+      before do
+        @aspect = build_aspect('[]=')
+        @writer = run_thread { subject.write('my_key', @complex_data) }
+      end
+      shared_examples_for 'when another thread wants to access the data with the same key while writing' do
+        it 'should wait until the writer finishes writing' do
+          @writer.join
+          @result.should eql @complex_data
+        end
+      end
+      context "when another thread wants to read with same key" do
+        before do
+          print_wait_before_action(:read)
+          @result = subject.read('my_key')
+        end
+        it_should_behave_like 'when another thread wants to access the data with the same key while writing'
+      end
+      context "when another thread wants to delete with the same key" do
+        before do
+          print_wait_before_action(:delete)
+          @result = subject.delete('my_key')
+        end
+        it_should_behave_like 'when another thread wants to access the data with the same key while writing'
+      end      
+    end
+    describe "#a thread is deleting with a key" do
+      let(:thread_name) { :deletor }
+      before do
+        @aspect = build_aspect(:delete)
+        @deletor = run_thread { @delete_result = subject.delete('my_key') }
+      end
+      shared_examples_for 'when another thread wants to access the data with the same key while deleting' do
+        it 'should wait until the deletor finishes deleting' do
+          @deletor.join
+          @delete_result.should eql @original_data
+        end        
+      end
+      context "when another thread wants to read with the same key" do
+        before do
+          print_wait_before_action(:read)
+          @read_result = subject.read('my_key')
+        end
+        it_should_behave_like 'when another thread wants to access the data with the same key while deleting'
+        specify { @read_result.should be_nil }
+      end
+      context "when another thread wants to write with the same key" do
+        before do
+          print_wait_before_action(:write)
+          subject.write('my_key', @complex_data)
+        end
+        it_should_behave_like 'when another thread wants to access the data with the same key while deleting'
+      end      
+    end
+  end
+  
+end
+

data/spec/cookies_manager/controller_additions_spec.rb

@@ -0,0 +1,24 @@
+require 'spec_helper'
+
+describe CookiesManager::ControllerAdditions do
+  let(:controller) { TestController.new }
+  context "when calling the class method :load_cookies_manager on the controller class" do
+    before do
+      mock(TestController).helper_method(:cookies_manager) # makes sure the :cookies_manager method is declared as a helper (to make it available to the views, for example)
+      mock(TestController).before_filter { |block| block.call(controller) } # makes sure a before_filter is set AND runs the filter block with our controller as an argument
+      TestController.load_cookies_manager # the class method we want to test
+    end
+    it "should create a :cookies_manager instance method" do
+      controller.method(:cookies_manager).should_not be_nil
+    end
+    it "the :cookies_manager method should return a CookiesManager object" do
+      controller.cookies_manager.is_a? CookiesManager
+    end
+    it "consecutives calls to the :cookies_manager method should return the SAME CookiesManager object" do
+      controller.cookies_manager.should equal controller.cookies_manager #strict equality required 
+    end
+    it "the CookiesManager object should be based on the native controller's cookies hash" do
+      controller.cookies_manager.cookies.should equal controller.cookies #strict equality required
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'action_controller'
+Bundler.require(:default)
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.filter_run :focus => true
+  config.filter_run_excluding :slow => ENV["SKIP_SLOW"].present?
+  config.run_all_when_everything_filtered = true
+  config.mock_with :rr
+end
+
+ # A test controller with a cookies hash (this works in rails 2.3.14 but needs to be adapted for versions of rails >= 3.x.x)
+class TestController < ActionController::Base
+  attr_accessor :cookies
+  
+  def request 
+    @request ||= ActionController::Request.new('test')
+  end
+  
+  def response
+    @response ||= ActionController::Response.new
+  end  
+  
+  def initialize
+    self.cookies = ActionController::CookieJar.new(self)
+  end     
+end

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification 
+name: cookies_manager
+version: !ruby/object:Gem::Version 
+  hash: 25
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- Christophe Levand
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-11-07 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 2
+        - 7
+        - 0
+        version: 2.7.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: actionpack
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 2
+        - 3
+        - 14
+        version: 2.3.14
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rr
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 1
+        - 0
+        - 4
+        version: 1.0.4
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: aquarium
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 0
+        - 4
+        - 4
+        version: 0.4.4
+  type: :development
+  version_requirements: *id004
+description: Simple cookies management tool for Rails that provides a convenient way to manage any kind of data in the cookies (strings, arrays, hashes, etc.)
+email: 
+- levandch@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- .rvmrc
+- CHANGELOG.rdoc
+- Gemfile
+- LICENSE
+- README.rdoc
+- Rakefile
+- cookies_manager.gemspec
+- init.rb
+- lib/cookies_manager.rb
+- lib/cookies_manager/base.rb
+- lib/cookies_manager/controller_additions.rb
+- lib/cookies_manager/version.rb
+- spec/README.rdoc
+- spec/cookies_manager/base_spec.rb
+- spec/cookies_manager/controller_additions_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: ""
+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: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: cookies_manager
+rubygems_version: 1.6.0
+signing_key: 
+specification_version: 3
+summary: Simple cookies management tool for Rails
+test_files: []
+