cookies_manager 0.1.8 → 0.2.0

data/CHANGELOG.rdoc

@@ -1,4 +1,8 @@
 0.1.x (Nov 07, 2011)
 
-* Initial release
+* Initial release + documentation compatibility fixes 
 
+0.2.0 (Nov 08, 2011)
+
+* Simplified usage: in reads operations, unpacks the data by default
+* Added cache management rspecs

data/README.rdoc

@@ -29,7 +29,9 @@ To activate the feature, simply call +load_cookies_manager+ on your controller c
 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

data/lib/cookies_manager/base.rb

@@ -23,19 +23,16 @@ module CookiesManager
     end
 
     # Reads the data object corresponding to the key.
+    # - Reads from the cache, or from the cookies if the cache is not in sync.
+    # - Cache desynchronization can occur when the cookies hash has been modified directly, in which case the cache is automatically re-synchronized. 
+    # - When the data needs to be retrieved from the cookies, it is successively base64-decoded, unzipped, and unmarshalled by default. If you consider your data does not need to be transformed, you can disable this feature by passing the +:skip_unpack+ option.
     #
-    # 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: 
+    # === Examples: 
     #    data = cookies_manager.read('my_key') # reads the data associated with the key 'my_key'
+    #    raw_data = cookies_manager.read('my_key', :skip_unpack => true) # reads without unpacking
     #
     # @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.
+    # @option opts [Boolean] :skip_unpack if true, DO NOT base64-decode, unzip, nor unmarshall the data. Default is false. This option is used only when the cache is out of sync.
     # @return [Object] the data associated with the key 
     #
     def read(key, opts = {})
@@ -47,10 +44,8 @@ module CookiesManager
     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).
+    # - 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:
     #    
@@ -85,14 +80,13 @@ module CookiesManager
       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.
+    # Deletes the data corresponding to the key, and return it.
+    # - Removes the data from both the cookies and the cache.
+    # - 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 by default. If you consider your data does not need to be transformed, you can disable this feature by passing the +:skip_unpack+ option.
     #
     # === Example:
-    #     data = cookies_manager.delete('my_key')  # deletes the data associated with the key 'my_key'
+    #     data = cookies_manager.delete('my_key')  # deletes and returns the data associated with the key 'my_key'
+    #     raw_data = cookies_manager.delete('my_key', :skip_unpack => true)  # same as above except that the returned data is not unpacked
     #
     # @param [String or Symbol] key a unique key corresponding to the data to delete   
     # @option opts (see #read)
@@ -132,7 +126,7 @@ module CookiesManager
       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
+        result = opts[:skip_unpack] ? data_from_cookies : unpack(data_from_cookies) # read from cookies
         # updates the cache
         cache[key][:packed_data] = data_from_cookies
         cache[key][:unpacked_data] = result

data/lib/cookies_manager/version.rb

@@ -1,3 +1,3 @@
 module CookiesManager
-  VERSION = "0.1.8"
+  VERSION = "0.2.0"
 end

data/spec/cookies_manager/base_spec.rb

@@ -86,7 +86,7 @@ describe CookiesManager::Base do
     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 }
+        specify { subject.read('my_key', :skip_unpack => true).should eql @complex_data }
       end
       context "when reading a nil value" do
         before { cookies['my_key'] = {:value => nil } }
@@ -94,13 +94,13 @@ describe CookiesManager::Base do
       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 }
+        specify { subject.read(nil, :skip_unpack => true).should eql @complex_data }
+        specify { subject.read('', :skip_unpack => true).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 }
+        specify { subject.read(nil, :skip_unpack => true).should eql @complex_data }
+        specify { subject.read('', :skip_unpack => true).should eql @complex_data }
       end
     end
     describe "#read some data previously stored through CookiesManager but later modified directly inside the cookies hash" do
@@ -109,7 +109,7 @@ describe CookiesManager::Base 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 }
+        specify { subject.read('my_key', :skip_unpack => true).should eql @new_simple_data }
       end
       context "when reading some complex data" do
         before do
@@ -117,8 +117,8 @@ describe CookiesManager::Base do
           @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
+        specify { subject.read('my_key').should eql @new_complex_data }
+        specify { unpack(subject.read('my_key', :skip_unpack => true)).should eql @new_complex_data } #if :skip_unpack option is set, we need to unpack the data manually
       end
     end
     describe "read with key symbol/string indifferent access (ex: :foo, 'foo')" do
@@ -141,7 +141,7 @@ describe CookiesManager::Base do
   describe "#delete" do
     describe "#delete existing data" do
       shared_examples_for "when deleting existing data" do
-        before { @result = subject.delete('my_key') }
+        before { @result = subject.delete('my_key', :skip_unpack => true) }
         specify { @result.should eql @complex_data }
         specify { subject.read('my_key').should be_nil }
       end
@@ -205,6 +205,49 @@ describe CookiesManager::Base do
     end
   end
   
+  describe "#cache management" do
+    shared_examples_for 'when accessing the data' do
+      context 'when reading' do
+        specify { subject.read('my_key').should eql @complex_data }
+      end
+      context 'when deleting' do
+        specify { subject.delete('my_key').should eql @complex_data }
+      end
+    end  
+    describe "#cache in sync with the cookies" do
+      describe "#accessing some data that has been read at least once by the CookiesManager" do
+        before do
+          cookies['my_key'] = pack(@complex_data)
+          subject.read('my_key').should eql @complex_data # this should store the data in the cache, thus sparing the need for future unmarshalling
+          dont_allow(Marshal).load # this makes sure unmarshalling is never done (i.e. the cache is used)
+        end
+        it_should_behave_like 'when accessing the data'
+      end 
+      describe "#accessing some data that has been written through the CookiesManager" do
+        before do
+          subject.write('my_key', @complex_data) # this should store the data in the cache, thus sparing the need for future unmarshalling
+          dont_allow(Marshal).load # this makes sure unmarshalling is never done (i.e. the cache is used)
+        end 
+        it_should_behave_like 'when accessing the data'
+      end
+    end
+    describe "#cache out of sync" do
+      before do
+        subject.write('my_key', @original_data = ['my', 'original', 'array'])
+        cookies['my_key'] = pack(@complex_data) # this causes the cache to be out of sync, thus causing future reads to unmarshall the data from the cookies 
+        mock.proxy(Marshal).load.with_any_args # this makes sure unmarshalling is invoked
+      end
+      it_should_behave_like 'when accessing the data'      
+      describe "#automatic cache resynchronization on read" do
+        before do 
+          subject.read('my_key').should eql @complex_data # this causes unmarshalling, and cache resynchronization
+          dont_allow(Marshal).load # this makes sure we don't unmarshall anymore at this point (i.e. the cache is now in sync and can be used)
+        end 
+        specify { subject.read('my_key').should eql @complex_data}
+      end
+    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..."

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cookies_manager
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
-  - 8
-  version: 0.1.8
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Christophe Levand