trick_serial 0.2.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

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

data/Gemfile

@@ -0,0 +1,17 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rspec", "~> 2.3.0"
+  gem "yard", "~> 0.6.0"
+  gem "bundler", "~> 1.1.0"
+  gem "jeweler", "~> 1.8.0"
+  gem "rcov", ">= 0"
+  gem 'ruby-debug', ">= 0"
+  gem 'rails', "~> 1.2.6"
+  gem 'memcache-client', ">= 1.7.0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Kurt Stephens
+
+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,128 @@
+= trick_serial
+
+Trick Serializers using Proxies
+
+Serialize objects using Proxies to trick serializers (e.g.: Marshal) to 
+not store entire object graphs (e.g.: ActiveRecord object).
+
+trick_serial supports CGI::Session and Rack sessions to allow ActiveRecord::Base objects
+to be stored directly in a session.  If the object has an id, it is stored in the session
+as a proxy object composed of the object's class name and id.  The object is restored from
+the database only if referenced through the session.
+
+trick_serial can be used independently of ActiveRecord and Session.  It can be configured to
+use serialization proxies for any classes.
+
+trick_serial maintains object identity during serialization.
+
+== Features
+
+Support for CGI::Session::FileStore, CGI::Session::PStore and Rails 1.2 CGI::Session::MemCacheStore.
+
+== Usage
+
+=== ActionController session example
+
+  module AuthenticatedController
+    def user
+      # User.find(...) is executed on the demand of session[:user].
+      @user ||= session[:user] 
+    end
+    
+    def user= x
+      # [ x.class.name, x.id ] is serialized in place of User object in session[:user].
+      @user = session[:user] = x 
+    end
+  end
+  
+  class UserController < ActionController::Base
+    include AuthenticatedController
+    
+    def login
+      if u = User.find(:first, :conditions => [ 'name = ? AND password = ?', params[:login], params[:password] ])
+         self.user = u
+         redirect_to :action => :home
+      end
+    end
+    
+    def logout
+       self.user = nil
+       redirect_to :action => :login
+    end
+    
+    def home
+      render :text => "You are #{user ? user.login : "NOT LOGGED IN!"}"
+    end
+
+    def update
+      raise unless user
+      user.attributes = params[:user]
+      user.save!
+    end
+  end
+
+== Configuration
+
+=== Rails 1.2 
+
+Inside your Rails::Initializer block:
+
+  Rails::Initializer.run do |config|
+    ...
+    # Configure trick_serial for Rails 1.2 MemCache Sessions:
+    begin
+      require 'action_controller/session/mem_cache_store'
+      require 'trick_serial/serializer'
+      require 'trick_serial/serializer/cgi_session'
+      
+      # This must be done after all session-related code is loaded:
+      TrickSerial::Serializer::CgiSession.activate!
+      
+      # Create a serializer instance.
+      serializer = TrickSerial::Serializer.new
+      
+      # Enable logging:
+      if false
+        serializer.logger = Log4r::Logger[:mylogger]
+        serializer.logger_level = :debug
+      end
+      
+      # Instruct the serializer to create proxies for instances of any subclasses of:
+      serializer.proxy_class_map = { 
+        ActiveRecord::Base => TrickSerial::Serializer::ActiveRecordProxy,
+      }
+      
+      # Options used in CGI::Session.new(@cgi, options) from ActionController::Base.
+      # See ActionController::SessionManagement for details.
+      ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS.
+        merge!({
+                 'database_manager' => TrickSerial::Serializer::CgiSession::Store,
+                 'TrickSerial.database_manager' => ::CGI::Session::MemCacheStore,
+                 'TrickSerial.serializer' => serializer,
+                 'TrickSerial.logger' => Log4r::Logger[:mylogger],
+                 'TrickSerial.logger_level' => :info,
+               })
+    end
+    config.action_controller.session_store = TrickSerial::Serializer::CgiSession::Store
+    ...
+  end
+
+=== Rails 3
+
+COMING SOON!
+
+== Contributing to trick_serial
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Kurt Stephens. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "trick_serial"
+  gem.homepage = "http://github.com/kstephens/trick_serial"
+  gem.license = "MIT"
+  gem.summary = %Q{A Serialization Framework.}
+  gem.description = %Q{Trick Serializers using Proxies.}
+  gem.email = "ks.github@kurtstephens.com"
+  gem.authors = ["Kurt Stephens"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/cabar.yml

@@ -0,0 +1,17 @@
+cabar:
+  version: '1.0'
+
+  component:
+    version: v0.1
+    description: 'TrickSerial - Trick Serializers with Object Proxies'
+
+  provides:
+    lib/ruby: lib
+    action:
+      test: "rake"
+    tests: spec
+    
+
+  requires:
+    component:
+      ruby: true

data/lib/trick_serial.rb

@@ -0,0 +1,3 @@
+module TrickSerial
+  EMPTY_Hash = { }.freeze
+end

data/lib/trick_serial/serializer.rb

@@ -0,0 +1,427 @@
+require 'trick_serial'
+
+module TrickSerial
+  # Serializes objects using proxies for classes defined in #proxy_class_map.
+  # Instances of the keys in #proxy_class_map are replaced by proxies if
+  # the proxy class returns true for #can_proxy?(instance).
+  #
+  # Container classes are extended with ProxySwizzling to automatically replace
+  # the Proxy objects with their #object when accessed.
+  #
+  # The result of this class does not require explicit decoding.  However,
+  # this particular class only works with serializers that can handle
+  # Hash and Array objects extended with Modules.
+  #
+  # See Serializer::Simple for support for simpler encode/decode behavior
+  # without ProxySwizzling support.
+  class Serializer
+    # Boolean or Proc.
+    attr_accessor :enabled
+
+    attr_accessor :logger, :logger_level
+    attr_accessor :verbose, :debug
+    attr_reader :root
+
+    attr_accessor :class_option_map
+    @@class_option_map = nil
+    def self.class_option_map 
+      @@class_option_map
+    end
+    def self.class_option_map= x
+      @@class_option_map = x
+    end
+
+    @@default = nil
+    def self.default
+      Thread.current[:'TrickSerial::Serializer.default'] ||
+        @@default
+    end
+    def self.default= x
+      @@default = x
+    end
+
+    def initialize
+      @class_option_map ||= @@class_option_map || EMPTY_Hash
+      @enabled = true
+      @debug = 0
+    end
+
+    def enabled?
+      case @enabled
+      when Proc
+        @enabled.call
+      else
+        @enabled
+      end
+    end
+
+    # Same as #encode!, but copies Array and Hash structures
+    # recursively.
+    # Does not copy structure if #enabled? is false.
+    def encode x
+      return x unless enabled?
+      @copy = true
+      encode! x
+    end
+
+    # Encodes using #proxy_class_map in-place.
+    def encode! x
+      _prepare x do
+        _encode! x
+      end
+    end
+
+    # Same as #decode!, but copies Array and Hash structures
+    # recursively.
+    # Does not copy structure if #enabled? is false.
+    # Only implemented by some subclasses.
+    def decode x
+      return x unless enabled?
+      @copy = true
+      decode! x
+    end
+
+    # Decodes using #proxy_class_map in-place.
+    # Only implemented by some subclasses.
+    def decode! x
+      _prepare x do 
+        _decode! x
+      end
+    end
+
+    def _prepare x
+      return x unless enabled?
+      proxyable
+      @root = x
+      @visited = { }
+      @object_to_proxy_map = { }
+      # debugger
+      yield
+    ensure
+      @visited.clear if @visited
+      @object_to_proxy_map.clear if @object_to_proxy_map
+      @copy =
+      @visited =
+        @object_to_proxy_map = 
+        @root = nil
+    end
+
+    # Returns a list of Modules that are proxable based on the configuration.
+    def proxyable
+      unless @proxyable
+        @proxyable = @class_option_map.keys.select{|cls| ! @class_option_map[cls][:do_not_traverse]}
+        @do_not_traverse ||= @class_option_map.keys.select{|cls| @class_option_map[cls][:do_not_traverse]} << ObjectProxy
+        @class_option_cache ||= { }
+        @proxyable.freeze
+      end
+      @proxyable
+    end
+
+
+    ##################################################################
+
+
+    def _encode! x
+      # pp [ :_encode!, x.class, x.object_id, x.to_s ] if @debug >= 1
+
+      case x
+      when *@do_not_traverse
+        # NOTHING
+
+      when ObjectProxy
+        # NOTHING
+
+      when Struct
+        if o = @visited[x.object_id]
+          return o.first
+        end
+        o = x
+        x = _copy_with_extensions(x)
+        @visited[o.object_id] = [ x, o ]
+        x = o
+        x.class.members.each do | m |
+          v = x.send(m)
+          v = _encode! v
+          x.send(:"#{m}=", v)
+        end
+
+      when OpenStruct
+        if o = @visited[x.object_id]
+          return o.first
+        end
+        o = x
+        x = _copy_with_extensions(x)
+        @visited[o.object_id] = [ x, o ]
+        x = o
+        t = x.instance_variable_get("@table")
+        t.each do | k, v |
+          t[k] = _encode! v
+        end
+
+      when Array
+        if o = @visited[x.object_id]
+          return o.first
+        end
+        o = x
+        x = _copy_with_extensions(x)
+        @visited[o.object_id] = [ x, o ]
+        extended = false
+        x.map! do | v |
+          v = _encode! v
+          if ! extended && ObjectProxy === v
+            x.extend ProxySwizzlingArray
+            extended = true
+          end
+          v
+        end
+
+      when Hash
+        if o = @visited[x.object_id]
+          return o.first
+        end
+        o = x
+        x = _copy_with_extensions(x)
+        @visited[o.object_id] = [ x, o ]
+        extended = false
+        x.keys.to_a.each do | k |
+          # pp [ :Hash_key, k ] if @debug >= 1
+          v = x[k] = _encode!(x[k])
+          if ! extended && ObjectProxy === v
+            x.extend ProxySwizzlingHash
+            extended = true
+          end
+        end
+
+      when *@proxyable
+        if proxy = @object_to_proxy_map[x.object_id]
+          # if @debug >= 1
+          #   o = proxy.first
+          #   $stderr.puts "  #{x.class} #{x.object_id} ==>> (#{o.class} #{o.object_id})"
+          # end
+          return proxy.first
+        end
+        # debugger
+
+        o = x
+        proxy_x = proxy_cls = nil
+        if class_option = _class_option(x)
+          proxy_cls = class_option[:proxy_class]
+          # Deeply encode instance vars?
+          if ivs = class_option[:instance_vars]
+            ivs = x.instance_variables if ivs == true
+            x = _copy_with_extensions x
+            proxy_x = _make_proxy o, x, proxy_cls
+            ivs.each do | ivar |
+              v = x.instance_variable_get(ivar)
+              v = _encode!(v)
+              if ObjectProxy === v
+                ivar.freeze
+                v = ProxySwizzlingIvar.new(x, ivar, v)
+              end
+              x.instance_variable_set(ivar, v)
+            end
+          else
+            proxy_x = _make_proxy o, x, proxy_cls
+          end
+        end
+        x = proxy_x if proxy_cls
+      end
+
+      # pp [ :"_encode!=>", x.class, x.object_id, x.to_s ] if @debug >= 1
+
+      x
+    end # def
+    
+    def _class_option x
+      (@class_option_cache[x.class] ||=
+       [
+        x.class.ancestors.
+        map { |c| @class_option_map[c] }.
+        find { |c| c }
+       ]).first
+    end
+
+    # Create a proxy for x for original object o.
+    # x may be a dup of o.
+    def _make_proxy o, x, proxy_cls
+      # Can the object x be proxied for the original object o?
+      # i.e. does it have an id?
+      if proxy_cls && proxy_cls.can_proxy?(x)
+        x = proxy_cls.new(x, self)
+        _log { "created proxy #{x} for #{o.class} #{o.id}" }
+      end
+      @object_to_proxy_map[o.object_id] = [ x, o ]
+      x
+    end
+
+    def _copy_with_extensions x
+      if @copy 
+        o = x.dup
+        (_extended_by(x) - _extended_by(o)).reverse_each do | m |
+          o.extend(m)
+        end rescue nil # :symbol.extend(m) => TypeError: can't define singleton
+        x = o
+      end
+      x
+    end
+
+    # This is similar to Rails Object#extended_by.
+    def _extended_by x
+      # Note: if Symbol === x this happens:
+      # #<TypeError: no virtual class for Symbol>
+      (class << x; ancestors; end) rescue [ ]
+    end
+
+    def _log msg = nil
+      if @logger
+        msg ||= yield if block_given?
+        @logger.send(@logger_level, msg) if msg
+      end
+    end
+
+
+    module ObjectProxy
+      class Error < ::Exception
+        class DisappearingObject < self; end
+      end
+
+      attr_reader :cls, :id
+
+      def self.included target
+        super
+      end
+
+      def initialize obj, serializer
+        self.object = obj
+      end
+
+      def resolve_class
+        @resolve_class ||=
+          eval("::#{@cls.to_s}")
+      end
+
+      def object= x
+        # @object = x
+        @cls = x && x.class.name.to_sym
+        @id = x && x.id
+      end
+    end # module
+
+    class ActiveRecordProxy
+      include ObjectProxy
+
+      def self.can_proxy?(obj)
+        obj.id
+      end
+
+      def object
+        # STDERR.puts "#{self}#object find #{@cls.inspect} #{@id.inspect}" unless @object
+        @object ||= 
+          resolve_class.find(@id) || 
+          (raise Error::DisappearingObject, "#{@cls.inspect} #{@id.inspect}")
+      end
+    end # class
+ 
+    ##################################################################
+
+    # Base module for all ProxySwizzling.
+    # http://en.wikipedia.org/wiki/Pointer_swizzling
+    module ProxySwizzling
+    end
+
+    class ProxySwizzlingIvar
+      include ProxySwizzling
+      alias :_proxy_class :class
+      def class
+        method_missing :class
+      end
+      
+      alias :_proxy_object_id :object_id
+      def object_id
+        method_missing :object_id
+      end
+
+      alias :_proxy_id :id
+      def id
+        method_missing :id
+      end
+
+      def initialize owner, name, value
+        @owner, @name, @value = owner, name, value
+      end
+      private :initialize
+
+      def method_missing sel, *args, &blk
+        if @owner
+          if ObjectProxy === @value
+            @value = @value.object
+          end
+          @owner.instance_variable_set(@name, @value)
+          @owner = @name = nil
+        end
+        @value.__send__(sel, *args, &blk)
+      end
+    end # class
+
+    module ProxySwizzlingArray
+      include ProxySwizzling
+      def [](i)
+        p = super
+        if ! @does_not_have_proxies && ObjectProxy === p
+          p = self[i] = p.object
+        end
+        p
+      end
+
+      def each
+        unless @does_not_have_proxies
+          size.times do | i |
+            self[i]
+          end
+          @does_not_have_proxies = false
+        end
+        super
+      end
+
+      def map!
+        each { | e | e }
+        super
+      end
+      
+      def select
+        each { | e | }
+        super
+      end
+    end # module
+
+    module ProxySwizzlingHash
+      include ProxySwizzling
+      def [](i)
+        if ObjectProxy === (p = super)
+          p = self[i] = p.object
+        end
+        p
+      end
+
+      def each
+        values
+        super
+      end
+
+      def each_pair 
+        values
+        super
+      end
+
+      def values
+        keys.to_a.each do | k |
+          self[k]
+        end
+        super
+      end
+    end # module
+
+  end # class
+end # module
+
+