cardiac 0.2.0.pre2

data/lib/cardiac/model/validations.rb

@@ -0,0 +1,124 @@
+module Cardiac
+  module Model
+    
+    # Cardiac::Model finder methods.
+    # Most of this has been "borrowed" from ActiveRecord.
+    module Validations
+      extend ActiveSupport::Concern
+      include ActiveModel::Validations
+      
+      included do
+        
+        ##
+        # :method: remote_errors_class=
+        # Set this on your class to customize the errors instance to build.
+        # The default value is ::ActiveModel::Errors
+        class_attribute :remote_errors_class
+      end
+    
+      module ClassMethods
+        
+        def create!(attributes = nil, &block)
+          if attributes.is_a?(Array)
+            attributes.collect { |attr| create!(attr, &block) }
+          else
+            object = new(attributes)
+            yield(object) if block_given?
+            object.save!
+            object
+          end
+        end
+      end
+      
+      def save(options={})
+        perform_validations(options) && super && remote_errors.empty?
+      end
+    
+      def save!(options={})
+        raise RecordInvalid.new(self) unless perform_validations(options)
+        super
+      ensure
+        raise RecordInvalid.new(self) unless remote_errors.empty?
+      end
+    
+      # Runs all the validations within the specified context. Returns +true+ if
+      # no errors are found, +false+ otherwise.
+      #
+      # If the argument is +false+ (default is +nil+), the context is set to <tt>:create</tt> if
+      # <tt>new_record?</tt> is +true+, and to <tt>:update</tt> if it is not.
+      #
+      # Validations with no <tt>:on</tt> option will run no matter the context. Validations with
+      # some <tt>:on</tt> option will only run in the specified context.
+      def valid?(context = nil)
+        context ||= (new_record? ? :create : :update)
+        output = super(context)
+        errors.empty? && output
+      end
+        
+      # Stores the errors returned by the remote, after performing any unpacking/decoding.
+      # To customize the options used to add the error:
+      #
+      #   <code>assign_remote_errors(data,options: {foo: :bar})</code>
+      #
+      def assign_remote_errors(data,options={})
+        decode_remote_errors(data,options).each do |key,values|
+          Array.wrap(values).each do |value|
+            remote_errors.add key, value.to_s, *([options[:options]] if Hash===options[:options])
+          end
+        end
+      end
+      
+      alias remote_errors= assign_remote_errors
+        
+      # Like ActiveModel::Validations#errors, but used for remote errors.
+      def remote_errors
+        @remote_errors ||= (self.class.remote_errors_class || ::ActiveModel::Errors).new(self)
+      end
+    
+    protected
+    
+      # Like ActiveModel::Validations#perform_validations, but also checks remote_errors.
+      #
+      # Remote_errors are not cleared before execution, but you could easily do that in a callback:
+      #
+      #   <code>before_validation { remote_errors.clear }</code>
+      #
+      def perform_validations(options={})
+        options[:validate] == false || (valid?(options[:context]) && remote_errors.empty?)
+      end
+    
+      # Overridden to unpack remote errors from the data.
+      def decode_remote_attributes(data,options={})
+        self.remote_errors = data.delete('errors')
+        super
+      end
+      
+      # Decodes errors returned by the remote.
+      #
+      # If the remote did not return a Hash, the data is wrapped in a single key: <code>:base</code>
+      # If no remote errors are present, an empty Hash is returned.
+      def decode_remote_errors(data, options={})
+        data.present? ? (Hash===data ? data : {base: data}) : {}
+      end
+  
+    private
+    
+      # Overridden to set @new_record back to true if there are remote errors.
+      def create_record
+        super
+        @new_record ||= ! remote_errors.empty?
+          
+        # Return success, if we are no longer a new record.
+        ! @new_record
+      end
+    
+      # Overridden to set @destroyed back to false if there are remote errors.
+      def delete_record
+        super
+        @destroyed &&= remote_errors.empty?
+      end
+      
+    end
+
+  end
+end

data/lib/cardiac/model.rb

@@ -0,0 +1,17 @@
+require 'active_support/dependencies/autoload'
+
+module Cardiac
+  module Model
+    extend ActiveSupport::Autoload
+    
+    autoload :Attributes
+    autoload :Base
+    autoload :Callbacks
+    autoload :Declarations
+    autoload :Dirty
+    autoload :Operations
+    autoload :Persistence
+    autoload :Querying
+    autoload :Validations
+  end
+end

data/lib/cardiac/operation_builder.rb

@@ -0,0 +1,75 @@
+module Cardiac
+  class OperationBuilder < ResourceBuilder
+    attr_writer :klass
+
+  protected
+  
+    # Checks if the given HTTP method is allowed.
+    def http_method_allowed?(verb=@base.method_value)
+      @base.allowed_http_methods.include?(verb)
+    end
+
+  private
+  
+    # Overridden to support :call when a verb is implied.
+    def respond_to_missing?(name,include_private=false)
+      unless name == :call then super else 
+        @base.method_value.present? && http_method_allowed?(@base.method_value)
+      end
+    end
+  
+    # Overridden to respond to HTTP verbs.
+    def check_builder_method?(name)
+      super(name) || http_method_allowed?(name)
+    end
+    
+    # Overridden to respond to HTTP verbs.
+    def method_missing name, *args, &block
+      name = @base.send(:build_method) if name == :call
+      if http_method_allowed? name
+        call!(name, *args, &block)
+      else
+        super
+      end
+    end
+    
+    # This builder does not actually perform calls, but does record the HTTP verb.
+    def call!(name, *args, &block)
+      if @base.method_value==name then self else
+        build! :http_method, name
+      end
+    end
+    
+    # Overridden to assign the :klass.
+    def build!(name, *args, &block)
+      b = super
+      b.klass = @klass
+      b
+    end
+    
+    # Overridden to assign the :klass.
+    def extend!(*extensions, &extension_block)
+      b = super
+      b.klass = @klass
+      b
+    end
+  end
+  
+  class OperationProxy < OperationBuilder
+    
+  private
+    
+    # Overridden to actually perform the call and return the payload.
+    def call!(name, *args, &block)
+      built = super
+      resolved = __adapter__.new(@klass, built.to_resource)
+      resolved.call!(*args, &block)
+      resolved.result.payload
+    end
+  
+    def __adapter__
+      @__adapter__ ||= ::Cardiac::ResourceAdapter
+    end
+    
+  end
+end

data/lib/cardiac/operation_handler.rb

@@ -0,0 +1,215 @@
+require 'active_support/configurable'
+require 'active_support/rescuable'
+require 'active_support/callbacks'
+require 'rack'
+require 'rack/client'
+require 'rack/cache'
+require 'stringio'
+
+module Cardiac
+  
+  # This is what is returned by the OperationHandler.
+  class OperationResult
+    attr_accessor :response, :payload
+    
+    def initialize(handled, response, payload=nil)
+      @transmitted = !! handled.transmitted?
+      @completed   = !! handled.completed?
+      @aborted     = !! handled.aborted?
+      @response    = response
+      @payload     = payload
+    end
+    
+    def transmitted?; @transmitted end
+    def completed?; @completed end
+    def aborted?; @aborted end
+  end
+  
+  # A base operation handler.
+  class OperationHandler
+    include ActiveSupport::Configurable
+    include ActiveSupport::Rescuable
+    include ActiveSupport::Callbacks
+    
+    rescue_from Errno::ETIMEDOUT, Errno::ECONNREFUSED, with: :service_unavailable
+    rescue_from RequestFailedError, with: :unwrap_client_exception
+    
+    config_accessor(:unwrap_client_exceptions)          { false }
+    config_accessor(:mock_response_on_connection_error) { true  }
+      
+    define_callbacks :transmission, :abort, :complete
+    
+    DEFAULT_RESPONSE_HANDLER = Proc.new do |response|
+      raise RequestFailedError, response unless response.successful?
+      response
+    end
+    
+    class Client < Rack::Client::Simple
+      class SwitchHeaders
+        def initialize(app,match,switch)
+          @app, @match, @switch = app, match, switch
+        end
+        def call(env)
+          status, headers, body = @app.call(env)
+          [status, Hash[ headers.to_a.map{|k,v| [@match===k ? @switch+$' : k, v] }], body]
+        end
+      end
+
+      use SwitchHeaders, /^X-HideRack-/, 'X-Rack-'
+      use SwitchHeaders, /^X-Rack-/, 'X-Rack-Client-'
+      use Rack::Cache,
+        'rack-cache.ignore_headers' => ['Set-Cookie','X-Content-Digest']
+      use Rack::Head
+      use Rack::ConditionalGet
+      use Rack::ETag
+      use SwitchHeaders, /^X-Rack-/, 'X-HideRack-'
+      
+      def self.new
+        super Rack::Client::Handler::NetHTTP
+      end
+      
+      def self.request(*args)
+        @instance ||= new
+        @instance.request(*args)
+      end
+      
+      def http_user_agent
+        "cardiac #{Cardiac::VERSION} (rack-client #{Rack::Client::VERSION})"
+      end
+    end
+    
+    attr_accessor :verb, :url, :headers, :payload, :options, :response_handler, :result
+    
+    def initialize client_options, payload=nil, &response_handler
+      @verb = client_options[:method] or raise InvalidOperationError, 'no HTTP verb was specified'
+      @url = client_options[:url] or raise InvalidOperationError, 'no URL was specified'
+      @headers = client_options[:headers]
+      @payload = payload
+      @options = client_options.except(:method, :url, :headers)
+      @response_handler = response_handler || DEFAULT_RESPONSE_HANDLER
+    end
+    
+    def transmit!
+      # Reset any old state before actually performing the transmission.
+      self.result = @aborted = @transmitted = nil
+      
+      # Perform the actual request and receive the response.
+      run_callbacks :transmission do
+        self.result = nil
+        begin
+          self.result = @response_handler.call(perform_request)
+          
+          # A response was received, so consider it transmitted.
+          @transmitted = true
+        rescue Exception => exception
+          
+          # An exception was received, so consider it untransmitted.
+          @transmitted = false
+          
+          # The exception may still be handled, to prevent the operation from aborting.
+          abort! exception
+        end
+      end
+      
+      # If we get here, then we must have a result to return.
+      complete!
+      
+    ensure
+      # Always clear out our result instance before returning it.
+      self.result = nil
+    end
+    
+    # Checks if the request was transmitted and a response was received.
+    def transmitted?
+      @transmitted
+    end
+    
+    # Checks if the operation was aborted due to an exception being thrown.
+    # Even though this does not involve the interpretation a response body, an
+    # aborted transmission could instead be considered completed by handling the exception.
+    def aborted?
+      @aborted
+    end
+    
+    # Checks if the operation was completed.
+    # This means that either the operation was transmitted, or an exception was handled successfully.
+    def completed?
+      @aborted.nil? ? @transmitted : !@aborted
+    end
+
+  protected
+  
+    def abort! exception
+      # Start out by assuming we will abort.
+      @aborted = true
+      
+      # Now we can run the abort callbacks.
+      run_callbacks :abort do
+        if rescue_with_handler(exception)
+          @aborted = false
+          raise OperationAbortError
+        elsif Exception===result
+          self.result, exception = nil, self.result
+        end
+      end
+      
+      # Now we can re-raise the unhandled exception.
+      raise exception
+      
+    rescue OperationAbortError => e
+      raise e if exception == e # just in case
+    end
+    
+    # Performs the completion of an operation, returning an OperationResult
+    def complete!(response=self.result)
+      run_callbacks :complete do
+        OperationResult.new(self, response)
+      end
+    end
+  
+    # Customized to only consider an exception handler successful if and only if
+    # it sets a result on this instance that is not itself an Exception.
+    def rescue_with_handler exception
+      if handler = handler_for_rescue(exception)
+        self.result = handler.arity != 0 ? handler.call(exception) : handler.call
+        
+        # Fail if the result is missing or is an Exception.
+        result.present? && ! result.is_a?(Exception)
+      end
+    end
+    
+  private
+  
+    def perform_request
+      Client.request @verb.to_s.upcase, @url.to_s, @headers.try(:stringify_keys) || {}, @payload
+    end
+  
+    # Handles RequestFailedError exceptions, optionally unwrapping them.
+    # This is a special case since we must still show that the operation was "transmitted"
+    # even if we will be aborting this operation.
+    def unwrap_client_exception e
+      # If we receive a "wrapped" exception, then a response was definitely received.
+      # However, the operation will still abort unless we are unwrapping client exceptions since
+      # any user-supplied exception handler would have overridden this one.
+      #
+      # Thus, we will set this flag early so that even an unhandled client exception that
+      # aborts the operation will still correctly show that the response was transmitted.
+      @transmitted = true
+      
+      # The configuration determines if we should use a non-20x response as a result.
+      self.result = e.response if unwrap_client_exceptions && e.respond_to?(:response)
+    end
+
+    # Handles I/O exceptions and other similar cases that do not involve the HTTP protocol.
+    # Optionally, these conditions could also be made to provide a mock response on a connection error.
+    # This would prevent the operation from aborting but still show that the response was not transmitted.
+    def service_unavailable e
+      self.result = build_mock_response e, '503' if mock_response_on_connection_error
+    end
+  
+    # Internal method.
+    def build_mock_response body, code, version='1.0', headers={}
+      Rack::Client::Simple::CollapsedResponse.new code, headers, StringIO.new(body)
+    end
+  end
+end

data/lib/cardiac/railtie.rb

@@ -0,0 +1,20 @@
+require 'active_attr/railtie'
+require "cardiac/model/base"
+require 'cardiac/log_subscriber'
+
+module Cardiac
+  class Railtie < Rails::Railtie
+
+    initializer "cardiac.logger" do
+      ActiveSupport.on_load(:cardiac) { self.logger ||= ::Rails.logger }
+    end
+
+    # Make the console output logging to STDERR (unless AR already did it).
+    console do |app|
+      unless defined? ::ActiveRecord::Base
+        console = ActiveSupport::Logger.new(STDERR)
+        Rails.logger.extend ActiveSupport::Logger.broadcast(console)
+      end
+    end
+  end
+end

data/lib/cardiac/reflections.rb

@@ -0,0 +1,85 @@
+require 'uri'
+require 'net/http'
+require 'active_support/core_ext/module/delegation'
+require 'cardiac'
+require 'cardiac/resource'
+
+module Cardiac
+
+	class BaseReflection
+		attr_reader :macro, :uri, :http_verb, :options
+		alias http_verb?   http_verb
+		alias http_method  http_verb
+		alias http_method? http_verb?
+
+		def initialize(resource_or_uri, http_verb=nil)
+			@macro, @http_verb = self.class.build_macro, http_verb
+
+			resource_or_uri.to_resource if resource_or_uri.respond_to?(:to_resource)
+					
+			case resource_or_uri
+			when Cardiac::Resource
+				@http_verb ||= resource_or_uri.method_value
+				@uri = resource_or_uri.to_uri
+				_options = resource_or_uri.send(:build_client_options, @http_verb)
+			when URI
+				@uri = resource_or_uri.dup
+				_options = {}
+			else
+				@uri = resource_or_uri.to_uri if resource_or_uri.respond_to?(:to_uri)
+				@http_verb ||= resource_or_uri.http_verb if resource_or_uri.respond_to?(:http_verb)
+				@options ||= resource_or_uri.options if resource_or_uri.respond_to?(:options)
+			end
+			@options = _options.dup
+			@options.symbolize_keys!
+			@options[:method] = @http_verb
+		end
+
+		def to_uri
+			@uri.dup
+		end
+
+		def to_url
+			@uri.to_s
+		end
+		
+		def to_reflection
+		  self
+		end
+
+  private
+  		
+		def self.build_macro(name=self.name)
+		  name.to_s.demodulize.sub(/Reflection$/,'').underscore.to_sym unless Symbol===name
+		  name
+		end
+	end
+
+	class ChainReflection
+		attr_reader :macro, :base_reflection, :handler_chain, :block
+
+		def initialize(macro, base, *handler_chain, &block)
+			@macro, @base_reflection, @handler_chain, @block = macro, base, handler_chain, block
+		end
+	end
+	
+	class ResourceReflection < BaseReflection
+		attr_reader :adapter_klass, :encoder_reflection, :decoder_reflections
+
+		def initialize(resource, http_verb=nil)
+			super resource, http_verb
+
+			@decoder_reflections = resource.send(:build_decoders).map do |search,handler_chain|
+				ChainReflection.new :decode, Representation::Reflection.new(search), *handler_chain
+			end
+
+			@encoder_reflection = ChainReflection.new :encode, *(resource.send(:build_encoder).tap do |search_and_chain|
+			    search_and_chain[0] = Representation::Reflection.new(search_and_chain.first || :url_encoded)
+			  end)
+		end
+	end
+	
+	class OperationReflection < ResourceReflection
+		attr_reader :handler_klass
+	end
+end

data/lib/cardiac/representation.rb

@@ -0,0 +1,124 @@
+require 'mime/types'
+require 'uri'
+require 'active_support/core_ext/object/to_param'
+require 'active_support/core_ext/object/to_query'
+require 'rack/utils'
+require 'multi_json'
+
+module Cardiac
+  module Representation
+    
+    # Looking up coders, mimes, etc.
+    module LookupMethods
+      def coder_for(search)
+        search = $1.to_s.classify if search =~ /\.?([a-z][a-z0-9_]*)$/i
+        const_get search.to_s
+      end
+
+      def mime_types(options={})
+        options[:types] || MIME::Types
+      end
+
+      def mimes_for(search, options={})
+        options = {complete: true, platform: false}.merge!(options)
+        case search
+        when /\.?([^\/\.])$/
+          mime_types(options).of(search.to_s, options[:platform])
+        when Symbol
+          mime_types(options)[search.to_s, options]
+        else
+          mime_types(options)[search, options]
+        end
+      end
+    end
+
+    # Basic reflection of a representation type.
+    class Reflection < Struct.new(:extension, :types, :default_type, :coder)
+      def initialize(extension,default_type=nil,*extra_types)
+        types = __codecs__.mimes_for(extension) + extra_types
+        if default_type.nil?
+          default_type = types.first
+        elsif ! types.include? default_type
+          types.unshift default_type
+        end
+        super extension.to_sym, types, default_type, __codecs__.coder_for(extension)
+      end
+      
+      delegate :coder_for, :mimes_for, to: :__codecs__
+      private :coder_for, :mimes_for
+      
+      def matches?(mime_type)
+        types.any?{|type| type.like? mime_type}
+      end
+    
+      def __codecs__
+        @__codecs__ ||= ::Cardiac::Representation::Codecs
+      end
+    end
+
+    module Codecs
+      extend LookupMethods
+      
+      module FormEncoded
+      module_function
+      
+        def encode(value,options={})
+          String===value ? value : URI.encode_www_form(value)
+        end
+
+        def decode(value,options={})
+          Hash===value ? value.stringify_keys : Hash[URI.decode_www_form(value)]
+        end
+      end
+      
+      module UrlEncoded
+        
+        # In Ruby 1.9.3, super is not available from module_function(s).
+        # It is simplest to just define all extensions here, then.
+        module Extensions
+          include ::Cardiac::RackUtils
+          include FormEncoded
+          alias encode_form encode
+          alias decode_form decode
+        end
+        
+        include Extensions
+        extend Extensions
+        
+      module_function
+      
+        def encode(value,options={})
+          Hash===value ? build_nested_query(value) : encode_form(value)
+        end
+
+        def decode(value,options={})
+          decode_form(value).inject({}) do |params,(key,value)|
+            normalize_params params, key, value
+          end
+        end
+      end
+
+      module Json
+        module_function
+        def encode(value,options={})
+          MultiJson.dump(value.as_json(options), options) unless value.kind_of?(String)
+        end
+
+        def decode(value,options={})
+          ::ActiveSupport::JSON.decode(value, options)
+        end
+      end
+
+      module Xml
+        module_function
+        def encode(value,options={})
+          value.to_xml(options)
+        end
+
+        def decode(value,options={})
+          Hash.from_xml(value)
+        end
+      end
+    end
+  end
+end