perry 0.4.0 → 0.5.0

data/Rakefile

@@ -24,6 +24,7 @@ spec = Gem::Specification.new do |s|
 
   s.add_dependency("activesupport", [">= 2.3.0"])
   s.add_dependency("bertrpc", [">= 1.3.0"])
+  s.add_dependency("json", [">=1.4.6"])
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|
@@ -52,7 +53,7 @@ begin
     t.libs       = ['test']
     t.test_files = FileList["test/**/*_test.rb"]
     t.verbose    = true
-    t.rcov_opts  = ['--text-report', "-x #{Gem.path}", '-x /Library/Ruby', '-x /usr/lib/ruby']
+    t.rcov_opts  = ['--text-report', "-x #{Gem.path.join(',')}", '-x /Library/Ruby', '-x /usr/lib/ruby']
   end
 
   task :default => :coverage

data/lib/perry/adapters/abstract_adapter.rb

@@ -1,92 +1,217 @@
 require 'perry/logger'
 
-module Perry::Adapters
-  class AbstractAdapter
-    include Perry::Logger
+##
+# = Perry::Adapters::AbstractAdapter
+#
+# This is the base class from which all adapters should inherit from.  Subclasses should overwrite
+# one or all of read, write, and/or delete.  They should also register themselves with a
+# unique name using the register_as class method.
+#
+# Adapters contain a stack of code that is executed on each request.  Here is a diagram of the basic
+# anatomy of the adaper stack:
+#
+#   +----------------+
+#   |   Perry::Base  |
+#   +----------------+
+#           |
+#   +----------------+
+#   |   Processors   |
+#   +----------------+
+#           |
+#   +----------------+
+#   |   ModelBridge  |
+#   +----------------+
+#           |
+#   +----------------+
+#   |   Middlewares  |
+#   +----------------+
+#           |
+#   +----------------+
+#   |     Adapter    |
+#   +----------------+
+#
+# Each request is routed through registred processors, the ModelBridge, and registered middlewares
+# before reaching the adapter.  After the adapter does its operation the return value passes through
+# each item in the stack allowing stack items to do both custom pre and post processing to every
+# request.
+#
+# == Configuration
+#
+# You can configure your adapters using the configure method on Perry::Base
+#
+#   configure(:read) do |config|
+#     config.adapter_var_1 = :custom_value
+#     config.adapter_var_2 = [:some, :values]
+#   end
+#
+# This block creates a new configuration context.  Each context is merged onto the previous context
+# allowing subclasses to override configuration set by their parent class.
+#
+# == Middlewares
+#
+# Middlewares allow you to add custom logic between the model and the adapter.  A good example is
+# caching.  A caching middleware could be implemented that intercepted a request to the adapter and
+# returned the cached value for that request.  If the request is a cache miss it could pass the
+# request on to the adapter, and then cache the result for subsequent calls of the same request.
+#
+# This is an example mof a no-op middleware:
+#
+#   class NoOpMiddleware
+#
+#     def initialize(adapter, config={})
+#       @adapter = adapter
+#       @config = config
+#     end
+#
+#     def call(options)
+#       @adapter.call(options)
+#     end
+#
+#   end
+#
+# Though this doesn't do anything it serves to demonstrate the basic structure of a middleware.
+# Logic could be added to perform caching, custom querying, or custom result processing.
+#
+# Middlewares can also be chained to perform several independent actions.  Middlewares are configured
+# through a custom configuration method:
+#
+#   configure(:read) do |config|
+#     config.add_middleware(MyMiddleware, :config => 'var', :foo => 'bar')
+#   end
+#
+# == ModelBridge
+#
+# The ModelBridge is simply a middleware that is always installed.  It instantiates the records from
+# the data returned by the adapter.  It "bridges" the raw data to the mapped object.
+#
+# == Processors
+#
+# Much like middlewares, processors allow you to insert logic into the request stack.  The
+# differentiation is that processors are able to manipulate the instantiated objects rather than
+# just the raw data.  Processors have access to the objects immediately before passing the data back
+# to the model space.
+#
+# The interface for a processor is identical to that of a middleware.  The return value of the call
+# to adapter; however, is an array of Perry::Base objects rather than Hashes of attributes.
+#
+# Configuration is also very similar to middlewares:
+#
+#   configure(:read) do |config|
+#     config.add_processor(MyProcessor, :config => 'var', :foo => 'bar')
+#   end
+#
+#
+class Perry::Adapters::AbstractAdapter
+  include Perry::Logger
+
+  attr_accessor :config
+  attr_reader :type
+  @@registered_adapters ||= {}
+
+  # Accepts type as :read, :write, or :delete and a base configuration context for this adapter.
+  def initialize(type, config)
+    @type = type.to_sym
+    @configuration_contexts = config.is_a?(Array) ? config : [config]
+  end
 
-    attr_accessor :config
-    attr_reader :type
-    @@registered_adapters ||= {}
+  # Wrapper to the standard init method that will lookup the adapter's class based on its registered
+  # symbol name.
+  def self.create(type, config)
+    klass = @@registered_adapters[type.to_sym]
+    klass.new(type, config)
+  end
 
-    def initialize(type, config)
-      @type = type.to_sym
-      @configuration_contexts = config.is_a?(Array) ? config : [config]
-    end
+  # Return a new adapter of the same type that adds the given configuration context
+  def extend_adapter(config)
+    config = config.is_a?(Array) ? config : [config]
+    self.class.create(self.type, @configuration_contexts + config)
+  end
 
-    def self.create(type, config)
-      klass = @@registered_adapters[type.to_sym]
-      klass.new(type, config)
-    end
+  # return the merged configuration object
+  def config
+    @config ||= build_configuration
+  end
 
-    def extend_adapter(config)
-      config = config.is_a?(Array) ? config : [config]
-      self.class.create(self.type, @configuration_contexts + config)
+  # runs the adapter in the specified type mode -- designed to work with the middleware stack
+  def call(mode, options)
+    @stack ||= self.stack_items.inject(self.method(mode)) do |below, (above_klass, above_config)|
+      above_klass.new(below, above_config)
     end
 
-    def config
-      @config ||= build_configuration
-    end
+    options[:mode] = mode.to_sym
+    @stack.call(options)
+  end
 
-    def call(mode, options)
-      @stack ||= self.middlewares.reverse.inject(self.method(mode)) do |below, (above_klass, above_config)|
-        above_klass.new(below, above_config)
-      end
+  # Return an array of added middlewares
+  def middlewares
+    self.config[:middlewares] || []
+  end
 
-      @stack.call(options)
-    end
+  # Return an array of added processors
+  def processors
+    self.config[:processors] || []
+  end
 
-    def middlewares
-      self.config[:middlewares] || []
-    end
+  # Abstract read method -- overridden by subclasses
+  def read(options)
+    raise(NotImplementedError,
+          "You must not use the abstract adapter.  Implement an adapter that extends the " +
+          "Perry::Adapters::AbstractAdapter class and overrides this method.")
+  end
 
-    def read(options)
-      raise(NotImplementedError,
-            "You must not use the abstract adapter.  Implement an adapter that extends the " +
-            "Perry::Adapters::AbstractAdapter class and overrides this method.")
-    end
+  # Abstract write method -- overridden by subclasses
+  def write(object)
+    raise(NotImplementedError,
+          "You must not use the abstract adapter.  Implement an adapter that extends the " +
+          "Perry::Adapters::AbstractAdapter class and overrides this method.")
+  end
 
-    def write(object)
-      raise(NotImplementedError,
-            "You must not use the abstract adapter.  Implement an adapter that extends the " +
-            "Perry::Adapters::AbstractAdapter class and overrides this method.")
-    end
+  # Abstract delete method -- overridden by subclasses
+  def delete(object)
+    raise(NotImplementedError,
+          "You must not use the abstract adapter.  Implement an adapter that extends the " +
+          "Perry::Adapters::AbstractAdapter class and overrides this method.")
+  end
 
-    def delete(object)
-      raise(NotImplementedError,
-            "You must not use the abstract adapter.  Implement an adapter that extends the " +
-            "Perry::Adapters::AbstractAdapter class and overrides this method.")
-    end
+  # New adapters should register themselves using this method
+  def self.register_as(name)
+    @@registered_adapters[name.to_sym] = self
+  end
 
-    def self.register_as(name)
-      @@registered_adapters[name.to_sym] = self
-    end
+  protected
 
-    private
+  def stack_items
+    (processors + [Perry::Middlewares::ModelBridge] + middlewares).reverse
+  end
 
-    # TRP: Run each configure block in order of class hierarchy / definition and merge the results.
-    def build_configuration
-      @configuration_contexts.inject({}) do |sum, config|
-        if config.is_a?(Hash)
-          sum.merge(config)
-        else
-          AdapterConfig.new(sum).tap { |ac| config.call(ac) }.marshal_dump
-        end
+  # TRP: Run each configure block in order of class hierarchy / definition and merge the results.
+  def build_configuration
+    @configuration_contexts.inject({}) do |sum, config|
+      if config.is_a?(Hash)
+        sum.merge(config)
+      else
+        AdapterConfig.new(sum).tap { |ac| config.call(ac) }.marshal_dump
       end
     end
+  end
 
-    class AdapterConfig < OpenStruct
+  class AdapterConfig < OpenStruct
 
-      def add_middleware(klass, config={})
-        self.middlewares ||= []
-        self.middlewares << [klass, config]
-      end
+    def add_middleware(klass, config={})
+      self.middlewares ||= []
+      self.middlewares << [klass, config]
+    end
 
-      def to_hash
-        marshal_dump
-      end
+    def add_processor(klass, config={})
+      self.processors ||= []
+      self.processors << [klass, config]
+    end
 
+    def to_hash
+      marshal_dump
     end
 
   end
+
 end
 

data/lib/perry/adapters/bertrpc_adapter.rb

@@ -12,9 +12,10 @@ module Perry::Adapters
     end
 
     def read(options)
-      log(options, "RPC #{config[:service]}") {
+      query = options[:relation].to_hash
+      log(query, "RPC #{config[:service]}") {
         self.service.call.send(self.namespace).send(self.service_name,
-                                                    options.merge(config[:default_options] || {}))
+                                                    query.merge(config[:default_options] || {}))
       }
     end
 

data/lib/perry/adapters/restful_http_adapter.rb

@@ -5,20 +5,22 @@ module Perry::Adapters
   class RestfulHTTPAdapter < Perry::Adapters::AbstractAdapter
     register_as :restful_http
 
-    attr_reader :last_response
-
-    def initialize(*args)
-      super
-      @configuration_contexts << { :primary_key => :id }
+    class KeyError < Perry::PerryError
+      def message
+        '(restful_http_adapter) request not sent because primary key value was nil'
+      end
     end
 
-    def write(object)
+    attr_reader :last_response
+
+    def write(options)
+      object = options[:object]
       params = build_params_from_attributes(object)
       object.new_record? ? post_http(object, params) : put_http(object, params)
     end
 
-    def delete(object)
-      delete_http(object)
+    def delete(options)
+      delete_http(options[:object])
     end
 
     protected
@@ -55,7 +57,19 @@ module Perry::Adapters
       self.log(params, "#{method.to_s.upcase} #{req_uri}") do
         @last_response = Net::HTTP.new(req_uri.host, req_uri.port).start { |http| http.request(request) }
       end
-      parse_response_code(@last_response)
+
+      Perry::Persistence::Response.new.tap do |response|
+        response.status = @last_response.code.to_i if @last_response
+        response.success = parse_response_code(@last_response)
+        response.meta = http_headers(@last_response).to_hash if @last_response
+        response.raw = @last_response.body if @last_response
+        response.raw_format = config[:format] ? config[:format].gsub(/\W/, '').to_sym : nil
+      end
+    rescue KeyError => ex
+      Perry::Persistence::Response.new.tap do |response|
+        response.success = false
+        response.parsed = { :base => ex.message }
+      end
     end
 
     def parse_response_code(response)
@@ -69,7 +83,8 @@ module Perry::Adapters
 
     def build_params_from_attributes(object)
       if self.config[:post_body_wrapper]
-        params = self.config[:default_options] || {}
+        defaults = self.config[:default_options]
+        params = defaults ? defaults.dup : {}
         params.merge!(object.write_options[:default_options]) if object.write_options.is_a?(Hash) && object.write_options[:default_options].is_a?(Hash)
 
         object.attributes.each do |attribute, value|
@@ -84,7 +99,11 @@ module Perry::Adapters
 
     def build_uri(object, method)
       url = [self.config[:host].gsub(%r{/$}, ''), self.config[:service]]
-      url << object.send(self.config[:primary_key]) unless object.new_record?
+      unless object.new_record?
+        primary_key = self.config[:primary_key] || object.primary_key
+        pk_value = object.send(primary_key) or raise KeyError
+        url << pk_value
+      end
       uri = URI.parse "#{url.join('/')}#{self.config[:format]}"
 
       # TRP: method DELETE has no POST body so we have to append any default options onto the query string
@@ -95,5 +114,11 @@ module Perry::Adapters
       uri
     end
 
+    def http_headers(response)
+      response.to_hash.inject({}) do |clean_headers, (key, values)|
+        clean_headers.merge(key => values.length > 1 ? values : values.first)
+      end
+    end
+
   end
 end

data/lib/perry/association.rb

@@ -43,8 +43,14 @@ module Perry::Association
       raise NotImplementedError, "You must define collection? in subclasses."
     end
 
-    def primary_key
-      options[:primary_key] || :id
+    def primary_key(object=nil)
+      if options[:primary_key]
+        options[:primary_key]
+      elsif is_a?(BelongsTo)
+        target_klass(object).primary_key
+      elsif is_a?(Has)
+        source_klass.primary_key
+      end
     end
 
     def foreign_key
@@ -52,10 +58,18 @@ module Perry::Association
     end
 
     def target_klass(object=nil)
+      eager_loading = object.is_a?(Array)
       if options[:polymorphic] && object
         poly_type = object.is_a?(Perry::Base) ? object.send("#{id}_type") : object
       end
 
+      # This is an eager loading attempt
+      if eager_loading && !eager_loadable?
+        raise(Perry::AssociationPreloadNotSupported,
+              "This association cannot be eager loaded.  It has config with procs or it is a " +
+              "polymorphic belongs_to association.")
+      end
+
       klass = if poly_type
         type_string = [
           options[:polymorphic_namespace],
@@ -92,9 +106,10 @@ module Perry::Association
     # TRP: Only eager loadable if association query does not depend on instance
     # data
     def eager_loadable?
-      Perry::Relation::FINDER_OPTIONS.inject(true) do |condition, key|
-        condition && !options[key].respond_to?(:call)
+      dynamic_config = Perry::Relation::FINDER_OPTIONS.inject(false) do |condition, key|
+        condition || options[key].respond_to?(:call)
       end
+      !dynamic_config && !(self.polymorphic? && self.is_a?(BelongsTo))
     end
 
     protected
@@ -113,7 +128,8 @@ module Perry::Association
 
     # TRP: Make sure the value looks like a variable syntaxtually
     def sanitize_type_attribute(string)
-      string.gsub(/[^a-zA-Z]\w*/, '')
+      string =~ /^[a-zA-Z]\w*/
+      Regexp.last_match.to_s
     end
 
   end
@@ -154,8 +170,15 @@ module Perry::Association
     #  where(:id => source[:foo_id])
     #
     def scope(object)
-      if object[self.foreign_key]
-        base_scope(object).where(self.primary_key => object[self.foreign_key])
+      if object.is_a? Array
+        keys = object.collect(&self.foreign_key.to_sym)
+        keys = nil if keys.empty?
+      else
+        keys = object[self.foreign_key]
+      end
+      if keys
+        scope = base_scope(object)
+        scope.where(self.primary_key(object) => keys)
       end
     end
 
@@ -192,13 +215,19 @@ module Perry::Association
     #   where(:parent_id => source[:id], :parent_type => source.class)
     #
     def scope(object)
-      return nil unless object[self.primary_key]
-      s = base_scope(object).where(self.foreign_key => object[self.primary_key])
-      if polymorphic?
-        s = s.where(
-          polymorphic_type => Perry::Base.base_class_name(object.class) )
+      if object.is_a? Array
+        keys = object.collect(&self.primary_key.to_sym)
+        keys = nil if keys.empty?
+        klass = object.first.class
+      else
+        keys = object[self.primary_key]
+        klass = object.class
+      end
+      if keys
+        scope = base_scope(object).where(self.foreign_key => keys)
+        scope = scope.where(polymorphic_type => Perry::Base.base_class_name(klass)) if polymorphic?
+        scope
       end
-      s
     end
 
     def polymorphic_type
@@ -288,7 +317,7 @@ module Perry::Association
       else
         relation = relation.where(
           proc do
-            { target_association.primary_key => proxy_ids.call }
+            { target_association.primary_key(options[:source_type]) => proxy_ids.call }
           end
         )
       end

data/lib/perry/base.rb

@@ -2,28 +2,29 @@
 require 'perry/errors'
 require 'perry/associations/contains'
 require 'perry/associations/external'
-require 'perry/association_preload'
-require 'perry/cacheable'
 require 'perry/serialization'
 require 'perry/relation'
 require 'perry/scopes'
 require 'perry/adapters'
-
+require 'perry/middlewares'
+require 'perry/processors'
 
 class Perry::Base
   include Perry::Associations::Contains
   include Perry::Associations::External
-  include Perry::AssociationPreload
   include Perry::Serialization
   include Perry::Scopes
 
-  attr_accessor :attributes, :new_record, :read_options, :write_options
+  DEFAULT_PRIMARY_KEY = :id
+
+  attr_accessor :attributes, :new_record, :saved, :read_options, :write_options
   alias :new_record? :new_record
+  alias :saved? :saved
+  alias :persisted? :saved?
 
-  class_inheritable_accessor :read_adapter, :write_adapter, :cacheable,
+  class_inheritable_accessor :read_adapter, :write_adapter,
     :defined_attributes, :scoped_methods, :defined_associations
 
-  self.cacheable = false
   self.defined_associations = {}
   self.defined_attributes = []
 
@@ -36,6 +37,14 @@ class Perry::Base
     @attributes[attribute.to_s]
   end
 
+  def errors
+    @errors ||= {}
+  end
+
+  def primary_key
+    self.class.primary_key
+  end
+
   protected
 
   # TRP: Common interface for setting attributes to keep things consistent; if
@@ -61,7 +70,22 @@ class Perry::Base
 
     delegate :find, :first, :all, :search, :apply_finder_options, :to => :scoped
     delegate :select, :group, :order, :joins, :where, :having, :limit, :offset,
-      :from, :fresh, :to => :scoped
+      :from, :includes, :to => :scoped
+    delegate :modifiers, :to => :scoped
+
+    def primary_key
+      @primary_key || DEFAULT_PRIMARY_KEY
+    end
+
+    # Allows you to specify an attribute other than :id to use as your models
+    # primary key.
+    #
+    def set_primary_key(attribute)
+      unless defined_attributes.include?(attribute.to_s)
+        raise Perry::PerryError.new("cannot set primary key to non-existent attribute")
+      end
+      @primary_key = attribute.to_sym
+    end
 
     def new_from_data_store(hash)
       if hash.nil?
@@ -96,8 +120,7 @@ class Perry::Base
     protected
 
     def fetch_records(relation)
-      options = relation.to_hash
-      self.read_adapter.read(options).collect { |hash| self.new_from_data_store(hash) }.compact.tap { |result| eager_load_associations(result, relation) }
+      self.read_adapter.call(:read, :relation => relation).compact
     end
 
     def read_with(adapter_type)
@@ -136,13 +159,6 @@ class Perry::Base
       end
     end
 
-    def configure_cacheable(options={})
-      unless cacheable
-        self.send(:include, Perry::Cacheable)
-        self.enable_caching(options)
-      end
-    end
-
     # TRP: Used to declare attributes -- only attributes that are declared will be available
     def attributes(*attributes)
       return self.defined_attributes if attributes.empty?

data/lib/perry/{cacheable → middlewares/cache_records}/entry.rb

@@ -1,18 +1,18 @@
-module Perry::Cacheable
-  
+class Perry::Middlewares::CacheRecords
+
   class Entry
-    
+
     attr_accessor :value, :expire_at
-    
+
     def initialize(value, expire_at)
       self.value = value
       self.expire_at = expire_at
     end
-    
+
     def expired?
       Time.now > self.expire_at rescue true
     end
-    
+
   end
-  
+
 end

data/lib/perry/middlewares/cache_records/scopes.rb

@@ -0,0 +1,18 @@
+module Perry::Middlewares::CacheRecords::Scopes
+  def self.included(model)
+    model.class_eval do
+
+      # Using the :fresh scope will skip the cache and execute query regardless of
+      # whether a cached result is available or not.
+      scope :fresh, (lambda do |*args|
+        val = args.first.nil? ? true : args.first
+        modifiers(:fresh => val)
+      end)
+
+      # Using the :reset_cache scope in a query will delete all entries from the
+      # cache store before running the query. Whenever possible, you should use
+      # the :fresh scope instead of :reset_cache.
+      scope :reset_cache, modifiers(:reset_cache => true)
+    end
+  end
+end

data/lib/perry/{cacheable → middlewares/cache_records}/store.rb

@@ -1,4 +1,4 @@
-module Perry::Cacheable
+class Perry::Middlewares::CacheRecords
 
   class Store