merb-core 0.9.8 → 0.9.9

data/lib/merb-core/dispatch/session/container.rb

@@ -1,41 +1,49 @@
 module Merb
   class SessionContainer < Mash
-  
+    
     class_inheritable_accessor :session_store_type
     cattr_accessor :subclasses 
     self.subclasses = []
-  
+    
     attr_reader :session_id
     attr_accessor :needs_new_cookie
-  
+    
     class << self
-  
+      
       # Register the subclass as an available session store type.
       def inherited(klass)
         self.subclasses << klass.to_s
         super
       end
-
+      
       # Generates a new session ID and creates a new session.
       #
       # ==== Returns
       # SessionContainer:: The new session.
+      # 
+      # @api private
       def generate
       end
-    
+      
       # ==== Parameters
       # request<Merb::Request>:: The Merb::Request that came in from Rack.
       #
+      # ==== Notes
+      # If no sessions were found, a new SessionContainer will be generated.
+      # 
       # ==== Returns
-      # SessionContainer:: a SessionContainer. If no sessions were found, 
-      # a new SessionContainer will be generated.
+      # SessionContainer:: a SessionContainer.
+      # 
+      # @api private
       def setup(request)
-      end    
-    
+      end
+      
     end
-  
+    
     # ==== Parameters
     # session_id<String>:: A unique identifier for this session.
+    # 
+    # @api private
     def initialize(session_id)
       @_destroy = false
       self.session_id = session_id
@@ -45,11 +53,13 @@ module Merb
     #
     # Recreates the cookie with the default expiration time. Useful during log
     # in for pushing back the expiration date.
+    # 
+    # @api private
     def session_id=(sid)
       self.needs_new_cookie = (@session_id && @session_id != sid)
       @session_id = sid
     end
-  
+    
     # Teardown and/or persist the current session.
     #
     # If @_destroy is true, clear out the session completely, including
@@ -57,18 +67,24 @@ module Merb
     #
     # ==== Parameters
     # request<Merb::Request>:: The Merb::Request that came in from Rack.
+    # 
+    # @api private
     def finalize(request)
     end
-  
+    
     # Destroy the current session - clears data and removes session cookie.
+    # 
+    # @api private
     def clear!
       @_destroy = true
       self.clear
     end
-  
+    
     # Regenerate the session_id.
+    # 
+    # @api private
     def regenerate
     end
-
+    
   end
 end

data/lib/merb-core/dispatch/session/cookie.rb

@@ -1,7 +1,7 @@
 require 'base64'        # to convert Marshal.dump to ASCII
 require 'openssl'       # to generate the HMAC message digest
 module Merb
-
+  
   # If you have more than 4K of session data or don't want your data to be
   # visible to the user, pick another session store.
   #
@@ -19,31 +19,33 @@ module Merb
     # TODO (maybe):
     # include request ip address
     # AES encrypt marshaled data
-
+    
     # Raised when storing more than 4K of session data.
     class CookieOverflow < StandardError; end
-
+    
     # Raised when the cookie fails its integrity check.
     class TamperedWithCookie < StandardError; end
-
+    
     # Cookies can typically store 4096 bytes.
     MAX = 4096
     DIGEST = OpenSSL::Digest::Digest.new('SHA1') # or MD5, RIPEMD160, SHA256?
-
+    
     attr_accessor :_original_session_data
-
+    
     # The session store type
     self.session_store_type = :cookie
-
+    
     class << self
       # Generates a new session ID and creates a new session.
       #
       # ==== Returns
       # SessionContainer:: The new session.
+      # 
+      # @api private
       def generate
         self.new(Merb::SessionMixin.rand_uuid, "", Merb::Request._session_secret_key)
       end
-
+      
       # Set up a new session on request: make it available on request instance.
       #
       # ==== Parameters
@@ -52,22 +54,26 @@ module Merb
       # ==== Returns
       # SessionContainer:: a SessionContainer. If no sessions were found,
       # a new SessionContainer will be generated.
+      # 
+      # @api private
       def setup(request)
         session = self.new(Merb::SessionMixin.rand_uuid,
           request.session_cookie_value, request._session_secret_key)
         session._original_session_data = session.to_cookie
         request.session = session
       end
-
+      
     end
-
+    
     # ==== Parameters
     # session_id<String>:: A unique identifier for this session.
     # cookie<String>:: The raw cookie data.
     # secret<String>:: A session secret.
     #
     # ==== Raises
-    # ArgumentError:: Nil or blank secret.
+    # ArgumentError:: blank or insufficiently long secret.
+    # 
+    # @api private
     def initialize(session_id, cookie, secret)
       super session_id
       if secret.blank? || secret.length < 16
@@ -78,7 +84,7 @@ module Merb
       @secret = secret
       self.update(unmarshal(cookie))
     end
-
+    
     # Teardown and/or persist the current session.
     #
     # If @_destroy is true, clear out the session completely, including
@@ -86,6 +92,8 @@ module Merb
     #
     # ==== Parameters
     # request<Merb::Request>:: request object created from Rack environment.
+    # 
+    # @api private
     def finalize(request)
       if @_destroy
         request.destroy_session_cookie
@@ -95,10 +103,12 @@ module Merb
     end
     
     # Regenerate the session_id.
+    # 
+    # @api private
     def regenerate
       self.session_id = Merb::SessionMixin.rand_uuid
     end
-
+    
     # Create the raw cookie string; includes an HMAC keyed message digest.
     #
     # ==== Returns
@@ -111,6 +121,8 @@ module Merb
     # Session data is converted to a Hash first, since a container might
     # choose to marshal it, which would make it persist
     # attributes like 'needs_new_cookie', which it shouldn't.
+    # 
+    # @api private
     def to_cookie
       unless self.empty?
         data = self.serialize
@@ -123,24 +135,31 @@ module Merb
         value
       end
     end
-
+    
     private
-
+    
     # Generate the HMAC keyed message digest. Uses SHA1.
+    # 
+    # ==== Returns
+    # String:: an HMAC digest of the cookie data.
+    # 
+    # @api private
     def generate_digest(data)
       OpenSSL::HMAC.hexdigest(DIGEST, @secret, data)
     end
-
+    
     # Unmarshal cookie data to a hash and verify its integrity.
-    #
+    # 
     # ==== Parameters
     # cookie<~to_s>:: The cookie to unmarshal.
-    #
+    # 
     # ==== Raises
     # TamperedWithCookie:: The digests don't match.
-    #
+    # 
     # ==== Returns
     # Hash:: The stored session data.
+    # 
+    # @api private
     def unmarshal(cookie)
       if cookie.blank?
         {}
@@ -156,16 +175,26 @@ module Merb
         unserialize(data)
       end
     end
-
+    
     protected
-
+    
     # Serialize current session data as a Hash.
     # Uses Base64 encoding for integrity.
+    # 
+    # ==== Returns
+    # String:: Base64 encoded dump of the session hash.
+    # 
+    # @api private
     def serialize
       Base64.encode64(Marshal.dump(self.to_hash)).chop
     end
-
+    
     # Unserialize the raw cookie data to a Hash
+    # 
+    # ==== Returns
+    # Hash:: the session hash Base64 decoded from the data dump.
+    # 
+    # @api private
     def unserialize(data)
       Marshal.load(Base64.decode64(data)) rescue {}
     end

data/lib/merb-core/dispatch/session/memcached.rb

@@ -28,33 +28,37 @@ module Merb
   end
   
   module MemcacheStore
-
+    
     # Make the Memcached gem conform to the SessionStoreContainer interface
-
+    
     # ==== Parameters
     # session_id<String>:: ID of the session to retrieve.
     #
     # ==== Returns
     # ContainerSession:: The session corresponding to the ID.
+    # 
+    # @api private
     def retrieve_session(session_id)
       get("session:#{session_id}")
     end
-
+    
     # ==== Parameters
     # session_id<String>:: ID of the session to set.
     # data<ContainerSession>:: The session to set.
+    # 
+    # @api private
     def store_session(session_id, data)
       set("session:#{session_id}", data)
     end
-
+    
     # ==== Parameters
     # session_id<String>:: ID of the session to delete.
     def delete_session(session_id)
       delete("session:#{session_id}")
     end
-
+    
   end
-
+  
 end
 
 # For the memcached gem.

data/lib/merb-core/dispatch/session/memory.rb

@@ -34,9 +34,11 @@ module Merb
   
   # Used for handling multiple sessions stored in memory.
   class MemorySessionStore
-
+    
     # ==== Parameters
     # ttl<Fixnum>:: Session validity time in seconds. Defaults to 1 hour.
+    # 
+    # @api private
     def initialize(ttl=nil)
       @sessions = Hash.new
       @timestamps = Hash.new
@@ -50,41 +52,51 @@ module Merb
     #
     # ==== Returns
     # ContainerSession:: The session corresponding to the ID.
+    # 
+    # @api private
     def retrieve_session(session_id)
       @mutex.synchronize {
         @timestamps[session_id] = Time.now
         @sessions[session_id]
       }
     end
-
+    
     # ==== Parameters
     # session_id<String>:: ID of the session to set.
     # data<ContainerSession>:: The session to set.
+    # 
+    # @api private
     def store_session(session_id, data)
       @mutex.synchronize {
         @timestamps[session_id] = Time.now
         @sessions[session_id] = data
       }
     end
-
+    
     # ==== Parameters
     # session_id<String>:: ID of the session to delete.
+    # 
+    # @api private
     def delete_session(session_id)
       @mutex.synchronize {
         @timestamps.delete(session_id)
         @sessions.delete(session_id)
       }
     end
-
+    
     # Deletes any sessions that have reached their maximum validity.
+    # 
+    # @api private
     def reap_expired_sessions
       @timestamps.each do |session_id,stamp|
         delete_session(session_id) if (stamp + @session_ttl) < Time.now 
       end
       GC.start
     end
-
+    
     # Starts the timer that will eventually reap outdated sessions.
+    # 
+    # @api private
     def start_timer
       Thread.new do
         loop {

data/lib/merb-core/dispatch/session/store_container.rb

@@ -45,25 +45,31 @@ module Merb
     self.session_store_type = :store
     
     class << self
-
+      
       # Generates a new session ID and creates a new session.
-      #
+      # 
       # ==== Returns
       # SessionStoreContainer:: The new session.
+      # 
+      # @api private
       def generate
         session = new(Merb::SessionMixin.rand_uuid)
         session.needs_new_cookie = true
         session
       end
-
-      # Setup a new session.
-      #
+      
+      # Setup a new session or retreive an existing session.
+      # 
       # ==== Parameters
       # request<Merb::Request>:: The Merb::Request that came in from Rack.
-      #
+      # 
+      # ==== Notes
+      # If no sessions were found, a new SessionContainer will be generated.
+      # 
       # ==== Returns
-      # SessionContainer:: a SessionContainer. If no sessions were found, 
-      # a new SessionContainer will be generated.
+      # SessionContainer:: a SessionContainer.
+      # 
+      # @api private
       def setup(request)
         session = retrieve(request.session_id)
         request.session = session
@@ -84,6 +90,8 @@ module Merb
       # ==== Notes
       # If there are persisted exceptions callbacks to execute, they all get executed
       # when Memcache library raises an exception.
+      # 
+      # @api private
       def retrieve(session_id)
         unless session_id.blank?
           begin
@@ -121,6 +129,8 @@ module Merb
     # The data (self) is converted to a Hash first, since a container might 
     # choose to do a full Marshal on the data, which would make it persist 
     # attributes like 'needs_new_cookie', which it shouldn't.
+    # 
+    # @api private
     def finalize(request)
       if @_destroy
         store.delete_session(self.session_id)
@@ -138,8 +148,10 @@ module Merb
         end
       end
     end
-
+    
     # Regenerate the session ID.
+    # 
+    # @api private
     def regenerate
       store.delete_session(self.session_id)
       self.session_id = Merb::SessionMixin.rand_uuid