cardiac 0.2.0.pre2

data/lib/cardiac/resource/adapter.rb

@@ -0,0 +1,178 @@
+require 'active_support/core_ext/hash/reverse_merge'
+require 'active_support/callbacks'
+require 'active_support/configurable'
+require 'active_support/rescuable'
+
+module Cardiac
+  
+  # An adapter for performing operations on a resource.
+  class ResourceAdapter
+    include ::ActiveSupport::Callbacks
+    include ::Cardiac::Representation::LookupMethods
+    
+    define_callbacks :resolve, :prepare, :encode, :execute, :decode
+    
+    attr_accessor :klass, :resource, :payload, :result
+    
+    delegate :request_has_body?, :response_has_body?, to: :resource
+    delegate :encoder_reflection, :decoder_reflections, to: '@reflection'
+    delegate :transmitted?, :aborted?, :completed?, :response, to: :result, allow_nil: true
+
+    # Use instrumentation to perform logging.
+    # @see ActiveSupport::Notifications
+    delegate :instrumenter, to: '::ActiveSupport::Notifications'
+    delegate :logger, to: '::Cardiac::Model::Base'
+    
+    def initialize(klass,base,payload=nil)
+      @klass = klass
+      @reflection = base.to_reflection if base.respond_to?(:to_reflection)
+      run_callbacks :resolve do
+        @resource = base.to_resource if base.respond_to?(:to_resource)
+      end
+      @reflection ||= @resource.to_reflection if resolved?
+    end
+    
+    def __client_options__
+      if resolved?
+        @__client_options__ ||= resource.send(:build_client_options).tap do |h|
+          h = (h[:headers] ||= {})
+            
+          # Content-Type
+          if content_type = h.delete(:content_type).presence
+            content_type = mimes_for(content_type).first
+          else
+            content_type = encoder_reflection.base_reflection.default_type
+          end
+          h['content_type'] = content_type.try(:content_type) || 'application/x-www-form-urlencoded'
+              
+          # Accept
+          if accept = h.delete(:accepts).presence and Array===accept
+            accept = accept.map{|ext| mimes_for(ext.to_s.strip).first }
+          else
+            accept = decoder_reflections.map{|dr| dr.base_reflection.default_type }.compact
+          end
+          h['accept'] = accept.empty? ? '*/*; q=0.5, application/json' : accept.join('; ')
+        end
+      end
+    end
+    
+    # Convenience method to return the current HTTP verb
+    def http_verb
+      if defined? @__client_options__
+        @__client_options__[:method].to_s.upcase
+      end
+    end
+    
+    # Performs a remote call by performing the remaining phases in the lifecycle of this adapter.
+    def call! *arguments, &block
+      self.result = nil
+      
+      resolved? or raise UnresolvableResourceError
+      prepared? or prepare! or raise InvalidOperationError
+      encode! *arguments
+      execute!
+    ensure
+      decode! if completed?
+    end
+    
+    def resolved?
+      resource.present?
+    end
+    
+    def prepared?
+      __client_options__.present?
+    end
+    
+  protected
+  
+    def prepare! verb=nil
+      run_callbacks :prepare do
+        self.resource = resource.http_method(verb) if verb
+      end
+      __client_options__.symbolize_keys!
+      prepared?
+    end
+
+    def encode! *arguments
+      
+      # Allow the payload to be overridden by a single argument.
+      if arguments.length == 1
+        self.payload = arguments.first
+      elsif arguments.length > 1
+        raise ArgumentError, "wrong number of arguments (#{arguments.length} for 0..1)"
+      end
+      
+      # Build the remaining portion of the operation using the given payload.
+      if request_has_body?
+        raise InvalidOperationError, "#{http_verb} requires a payload" if payload.nil?
+        run_callbacks :encode do
+          self.payload = encoder_reflection.base_reflection.coder.encode(payload)
+        end
+      elsif payload.present?
+        raise InvalidOperationError, "#{http_verb} does not support a payload"
+      end
+    end
+    
+    def execute!
+      event = event_attributes 
+      instrumenter.instrument "operation.cardiac", event do
+        run_callbacks :execute do
+          handler = __handler__.new(__client_options__, payload, &__client_handler__)
+          self.result = handler.transmit!
+          event[:response_headers] = result.response.headers if result && result.response
+          completed?
+        end
+      end
+    rescue => e
+      message = "#{e.class.name}: #{e.message}: #{resource.to_url}"
+      logger.error message if logger
+      raise e
+    end
+    
+    def decode! response=self.response
+      return unless response_has_body?
+      
+      unless content_type = response.content_type.presence
+        raise ProtocolError, 'missing Content-type in response'
+      end
+     
+      unless decoder = decoder_reflections.find{|dr| dr.base_reflection.matches?(content_type) }
+        raise ResourceError, "no decoder for #{content_type.inspect} response"
+      end
+      
+      run_callbacks :decode do
+        result.payload = decoder.base_reflection.coder.decode(response.body.to_s)
+      end
+    end
+
+  private
+  
+    def model_name
+      __klass_get(:model_name).try(:to_s)
+    end
+    
+    def event_attributes
+      h = { name: model_name, verb: http_verb, url: resource.to_url, payload: payload }
+      ctx = __klass_get :operation_context
+      ctx = { context: ctx } unless ctx.present? && Hash===ctx
+      h.reverse_merge! ctx if ctx
+      h.keep_if{|key,value| key==:verb || key==:url || value.present? }
+    end
+    
+    def __codecs__
+      @__codecs__ ||= ::Cardiac::Representation::Codecs
+    end
+  
+    def __handler__
+      @__handler__ ||= ::Cardiac::OperationHandler
+    end
+    
+    def __client_handler__
+    end
+    
+    def __klass_get method_name
+      @klass.public_send(method_name) if @klass && @klass.respond_to?(method_name, false)
+    end
+  end
+
+end

data/lib/cardiac/resource/builder.rb

@@ -0,0 +1,107 @@
+module Cardiac
+  class ResourceBuilder < Proxy
+    
+    def initialize base, *extensions, &extension_block
+      raise ArgumentError unless Resource === base
+      @base, @extensions, @extension_block = base, extensions, extension_block
+      @extensions.compact!
+    end
+
+    # Returns a copy of our subresource.
+    def to_resource
+      __subresource__.dup
+    end
+    
+    # Resolves this builder's extension module, and extends the builder with it.
+    def __extension_module__
+      @__extension_module__ ||= build_extensions_for_module!{|mod| __extend__ mod }
+    end
+    
+    # Resolves this builder's extensions.
+    def __extensions__
+      @__extensions__ ||= @extensions.dup.tap do |exts|
+        exts.unshift @base.__extension_module__ if @base.__extension_module__
+        exts.push ::Module.new(&@extension_block) if @extension_block
+      end
+    end
+    
+    # Resolves this builder to a subresource.
+    def __subresource__
+      @__subresource__ ||= Subresource.new(@base.to_resource)
+    end
+    
+    def extending(*extensions,&extension_block)
+      extend! extensions, &extension_block
+    end
+    
+  protected
+  
+    # Includes this builder's extensions into the given module, returning that module.
+    # If no module is supplied, then a new module will be built.
+    def build_extensions_for_module!(mod=nil,&block)
+      if __extensions__.any?
+        mod ||= ::Module.new
+        mod.send :include, *__extensions__
+        block.call mod if block
+      end
+      mod
+    end
+    
+  private
+    
+    def method_missing name, *args, &block
+      name = name.to_sym
+      
+      # Always delegate builder methods.
+      if check_builder_method? name
+        build! name, *args, &block
+
+      # Only delegate extension methods if the extension module has not been built yet.
+      # This allows extensions to be removed by preventing method_missing from calling them.
+      elsif @__extension_module__.nil? && check_extension_method?(name)
+        #__extension_module__.instance_method(name).bind(self).call(*args, &block)
+        __public_send__(name, *args, &block) || self
+        
+      # Otherwise, the method has not been implemented.
+      else
+        raise ::NotImplementedError, "#{name.inspect} is not implemented for this builder"
+      end
+    end
+    
+    # Clones our subresource, calls it with the given args, then returns a new builder for it.
+    def build! name, *args, &block
+      subr = to_resource
+      subr.send name, *args, &block
+      __class__.new subr, *(@extensions+[subr.__extension_module__])
+    end
+  
+    # Clones our subresource, extends it with the given extensions, then creates a new builder with an extension block
+    def extend! extensions, &extension_block
+      subr = to_resource.extending(*extensions)
+      subr = DeclarationBuilder.new(subr).extension_exec(&extension_block) if extension_block
+      __class__.new subr, *(@extensions+[subr.__extension_module__])
+    end
+    
+    # Checks if this builder can respond to a symbol.
+    def respond_to_missing?(name, include_private=false)
+      check_builder_method?(name) || check_extension_method?(name)
+    end
+    
+    # Checks if the given builder method is allowed.
+    def check_builder_method? name
+      name = name.to_sym
+      name!=:subresource && name!=:operation && (@base.allowed_builder_methods.include?(name))
+    end
+    
+    # Checks if the given extension method is allowed.
+    def check_extension_method? name
+      __extension_module__.method_defined? name if __extensions__.any?
+    end
+    
+#    def method_added name, &block
+#      @extensions.send :define_method, name, &block
+#      remove_method name if method_defined? name
+#    end
+  end
+  
+end

data/lib/cardiac/resource/codec_methods.rb

@@ -0,0 +1,58 @@
+module Cardiac
+  module CodecMethods
+    DEFAULT_DECODERS = [:url_encoded, :xml, :json].freeze
+    
+    # Representation decoder selection and customization.
+    def decoders(search,*rest,&handler) self.decoders_values += check_decoders(rest.unshift(search),handler) ; self end
+    def reset_decoders(*rest,&handler) decoders_values.replace check_decoders(rest,handler) ; self end
+
+    # Representation encoder selection and customization.
+    def encoder(search, &handler)
+      self.encoder_search_value = search.presence or raise ArgumentError
+      self.encoder_handler_value = handler
+      self
+    end
+
+  protected
+  
+    # Delegates mime type lookups to Representation::Codecs.mimes_for
+    def lookup_type(search,options={})
+      ::Cardiac::Representation::Codecs.mimes_for(search,options)
+    end
+
+		def build_encoder(*previous)
+			previous << encoder_handler_value if encoder_handler_value
+			[encoder_search_value, previous]
+		end
+  
+    # Builds a hash of decoder chains, keyed by symbol.
+    #
+    # In the decoder_values, zero or more symbols will precede each Proc in the chain,
+    # specifying which decoder(s) it applies to.  If no symbols precede the Proc, then it will
+    # be applicable to ALL decoders, even subsequently specified ones.  The order of
+    # Proc objects in the chain are preserved, regardless of which decoders they are applicable to.
+    # 
+    def build_decoders(base_decoders=DEFAULT_DECODERS, base_handler=nil)
+      all_chain, decoders = [], {}
+      decoders_values.each do |value|
+        case value
+        when Proc
+          decoders.each_value{|chain| chain << value }
+          all_chain << value
+        when Symbol
+          decoders[value] = all_chain.dup
+        end
+      end
+      base_decoders.each{|decoder| decoders[decoder] = all_chain.dup } if decoders.empty?
+      decoders
+    end
+  
+  private
+  
+    def check_decoders(decoders,handler=nil)
+      raise ArgumentError unless decoders.all?{|k| Symbol===k }
+      decoders << handler if handler
+      decoders
+    end
+  end
+end

data/lib/cardiac/resource/config_methods.rb

@@ -0,0 +1,39 @@
+require 'active_support/concern'
+require 'active_support/configurable'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'net/http'
+
+module Cardiac
+  module ConfigMethods
+    extend ActiveSupport::Concern
+
+    include ActiveSupport::Configurable
+
+    included do
+      config_accessor :default_options
+      self.default_options = {}.with_indifferent_access
+
+      config_accessor :allowed_http_methods
+      self.allowed_http_methods = Net::HTTP.constants.map{|k| Net::HTTP::const_get(k)::METHOD.downcase.to_sym rescue nil }.compact
+      
+      config_accessor :allowed_builder_methods
+      
+      config_accessor :unwrap_client_exceptions
+      self.unwrap_client_exceptions = Cardiac::OperationHandler.unwrap_client_exceptions
+    end
+    
+    def reconfig
+      config.clear ; config
+    end
+    
+    def reconfigure
+      config.clear ; configure
+    end
+
+  protected
+  
+    def build_config(base_config={})
+      base_config.merge config
+    end
+  end
+end

data/lib/cardiac/resource/extension_methods.rb

@@ -0,0 +1,115 @@
+require 'active_support/core_ext/module/remove_method'
+
+module Cardiac
+  
+  module ExtensionMethods
+    
+    # Defines an operation on this resource.    
+    def operation(name, implementation)
+      self.operations_values << check_operation(name, implementation)
+      self
+    end
+    
+    # Defines a subresource on this resource.    
+    def subresource(name, implementation, &extension_block)
+      self.subresources_values << check_subresource(name, implementation, extension_block)
+      self
+    end
+    
+    # Declares an extension module to be included into this resource's extension module.
+    def extending(*modules, &extension_block)
+      self.extensions_values += check_extensions(modules, extension_block)
+      self
+    end
+
+    # Lazily builds the extension module, then redefines this method as an attr_reader.
+    def __extension_module__
+      build_extension_module if extensions_values.any? || operations_values.any? || subresources_values.any?
+    ensure
+      singleton_class.class_eval "attr_reader :__extension_module__"
+    end
+    
+    # Checks if an extension is defined.
+    def __extension_defined__?(name)
+      __extension_module__.method_defined? name
+    end
+    
+  protected
+  
+    def build_extension_module
+      @__extension_module__ = apply_extensions_to_module!
+    end
+    
+    def build_operations_for_module mod
+      operations_values.inject({}.with_indifferent_access){|h,(k,v)| h[k]=v ; h }.
+        each{|name,block| mod.redefine_method(name, &block) }
+    end
+    
+    def build_subresources_for_module mod, subm=Module.new
+			[subm, subresources_values.
+					inject({}.with_indifferent_access){|h,(k,v,e)| h[k]=[v,e] ; h }.
+					each do |name,(block,extension_block)|
+						subm.redefine_method(name, &block)
+						if extension_block
+              stash_object_in_method! subm, :"__#{name}_extensions__", extension_block
+						end
+					end]
+    end
+    
+    def build_extensions_for_module mod
+      extensions_values.each{|ext| mod.send :include, ext }
+    end
+    
+  private
+  
+    def check_operation name, implementation
+      raise ArgumentError unless Proc===implementation
+      raise ArgumentError unless String===name || Symbol===name
+      name = name.to_sym
+      return [name, implementation] unless subresources_values.any?{|v| v.first==name }
+      raise ArgumentError, ":#{name} has already been defined as a subresource"
+    end
+  
+    def check_subresource name, implementation, extension_block
+      raise ArgumentError unless Proc===implementation
+      raise ArgumentError unless String===name || Symbol===name
+      raise ArgumentError unless extension_block.nil? || extension_block.arity==0
+      name = name.to_sym
+      return [name, implementation, extension_block] unless operations_values.any?{|v| v.first==name }
+      raise ArgumentError, ":#{name} has already been defined as an operation"
+    end
+    
+    def check_extensions modules, extension_block
+      raise ArgumentError unless modules.all?{|mod| Module===mod}
+      raise ArgumentError unless extension_block.nil? || extension_block.arity==0
+      modules << Module.new(&extension_block) if extension_block
+      modules
+    end
+    
+    def apply_extensions_to_module! mod=Module.new
+      build_extensions_for_module mod
+
+			subm, subr = build_subresources_for_module mod
+			if subm && subr && subr.any?
+				mod.send :include, subm
+				subr.each do |name,(_,extension_block)|
+						mod.module_eval <<-EOVR
+	def #{name}(*args)
+		super(*args)#{".extending(&__#{name}_extensions__)" if extension_block}
+	end
+	EOVR
+				end
+			end
+
+			build_operations_for_module mod
+			mod
+    end
+    
+    def stash_object_in_method! mod, name, object
+      mod.module_exec object do |_object|
+        define_method(name) { object }
+      end
+    end
+  end
+  
+end

data/lib/cardiac/resource/request_methods.rb

@@ -0,0 +1,138 @@
+require 'uri'
+require 'active_support/core_ext/hash/deep_merge'
+require 'active_support/core_ext/hash/indifferent_access'
+
+module Cardiac
+  module RequestMethods
+    
+    # The default accepts header type identifiers.
+    DEFAULT_ACCEPTS = [:json, :xml]
+
+    # HTTP method selection.
+    def http_method(k) self.method_value = check_http_method(k) ; self end
+      
+    # Header selection.
+    def headers(h,*rest) self.headers_values += check_headers(rest.unshift(h)) ; self end
+    def reset_headers(*h) headers_values.replace check_headers(h) ; self end
+    def header(key, value)
+      raise ArgumentError unless String===key or Symbol===key
+      raise ArgumentError if TrueClass===value
+      self.headers_values << (FalseClass===value ? key : {key => value})
+      self
+    end
+    def accepts(search,*rest) self.accepts_values += check_accepts(rest.unshift(search)) ; self end
+    
+    # Request option selection.
+    def options(o,*rest) self.options_values += apply_request_options!(check_options(rest.unshift(o))) ; self end
+    def reset_options(*o) options_values.replace apply_request_options!(check_options(o)) ; self end
+    def option(key, value)
+      raise ArgumentError unless String===key or Symbol===key
+      raise ArgumentError if TrueClass===value
+      self.options_values << (FalseClass===value ? key : {key => value})
+      self
+    end
+
+    # Relative resource selection.
+    def at(rel,options={})
+      super(rel).options(options)
+    end
+    
+    # Checking if the configured HTTP verb has requests that support a body.
+    def request_has_body?
+      net_http_request_klass::REQUEST_HAS_BODY
+    end
+    
+    # Checking if the configured HTTP verb has responses that support a body.
+    def response_has_body?
+      net_http_request_klass::RESPONSE_HAS_BODY
+    end
+    
+  protected
+    
+    def build_options(base_options={})
+      options_values.inject base_options.with_indifferent_access do |o,v|
+        case v
+        when Hash          then o.deep_merge!(v)
+        when String,Symbol then o.delete(v) ; o
+        end
+      end.symbolize_keys
+    end
+    
+    def build_headers(base_headers={})
+      base_headers = base_headers.with_indifferent_access
+      base_headers[:content_type] = encoder_search_value if encoder_search_value.present?
+      base_headers[:accepts] = build_accepts
+
+      headers_values.inject base_headers.with_indifferent_access do |h,v|
+        case v
+        when Hash          then h.deep_merge!(v)
+        when String,Symbol then h.delete(v) ; h
+        end
+      end.symbolize_keys
+    end
+    
+    def build_accepts
+      (accepts_values.presence || DEFAULT_ACCEPTS).dup
+    end
+
+    def build_http_method
+      if method_value.nil?
+        raise InvalidOperationError, 'no HTTP method specified'
+      elsif ! net_http_request_klass
+        raise InvalidOperationError, "unsupported HTTP method: #{method_value.to_s.upcase}"
+      elsif ! allowed_http_methods.include?(method_value)
+        raise InvalidOperationError, "disallowed HTTP method: #{method_value.to_s.upcase}"
+      end
+      method_value
+    end
+
+  private
+  
+    def check_http_method(http_method)
+      if http_method.present?
+        raise ArgumentError unless Symbol===http_method || String===http_method
+        http_method.downcase.to_sym
+      end
+    end
+
+    def check_options(options)
+      raise ArgumentError unless options.all?{|o| Hash===o }
+      options
+    end
+
+    def check_headers(headers)
+      raise ArgumentError unless headers.all?{|h| Hash===h }
+      headers
+    end
+
+    def check_accepts(searches)
+      raise ArgumentError unless searches.all?{|a| Symbol===a || String===a }
+      searches
+    end
+    
+    def apply_request_option! key, value
+      case key
+      when :method, :http_method ; http_method(value)
+      when :headers              ; headers(value)
+      when :accepts              ; accepts(value)
+      when :params               ; query(value)
+      end
+    end
+    
+    def apply_request_options! options
+      options.map{|o| o.reject{|k,v| apply_request_option!(k,v) }.presence }.compact
+    end
+  
+    def net_http_request_klass
+      if method_value.present?
+        verb = method_value.to_s.upcase
+        if @request_klass && @request_klass::METHOD == verb
+          @request_klass
+        else
+          klass = Net::HTTP.const_get(verb.capitalize) rescue nil
+          @request_klass = klass if klass && klass::METHOD == verb
+        end
+      end
+    end
+  end
+end