daylight 0.9.0.rc1

data/lib/daylight/collection.rb

@@ -0,0 +1,161 @@
+##
+# Alternate collection methods for +first_or_create+, +first_or_initialize+.
+#
+# Used to split the +original_params+ into known attributes and query params
+# added by ResourceProxy.
+#
+# Parameters not added by ResourceProxy will still be merged into the supplied
+# attributes.  This is the current ActiveResource behavior.
+#
+# Parameters that contain known attributes (ie. +:filter+) will also be merged
+# with the supplied attributes.  The query parameters (ie. +:scopes+) will be
+# set on +prefix_options+
+#
+# For example:
+#
+#    users = User.find(:all, params: {
+#      filters: {last_name: {'Bonzai'}},
+#      scopes: ['planet_ten'],
+#      band: 'Hong Kong Cavaliers'
+#    })
+#
+# Return all Users in the band 'Hong Kong Cavaliers' where their last name
+# is 'Bonzai'.  If a User with first name 'Buckaroo' does not exist:
+#
+#    users.first_or_create(first_name: 'Buckaroo')
+#
+# Or:
+#
+#    users.first_or_initialize(first_name: 'Buckaroo').save
+#
+# Will issue the following request where the band is kept as a query parameter
+# and the contents of the +filter+ paramter are merged with the attributes:
+#
+#    POST: /api/v1/users.json?scopes[]=planet_ten
+#    DATA: {"user":{"first_name":"Buckaroo", "last_name":"Bonzai", "band":"Hong Kong Cavaliers"}}
+#
+# See:
+# ActiveResource::Collection
+module Daylight::Collection
+  extend ActiveSupport::Concern
+
+  included do
+    attr_reader :metadata
+
+    ##
+    # Overwriting ActiveResource::Collection#initialize
+    #---
+    # Concern cannot call `super` from module to base class (we think)
+    def initialize(elements = [])
+      if Hash === elements && elements.has_key?('meta')
+        metadata = (elements.delete('meta')||{}).with_indifferent_access  # save and strip any metadata supplied in the response
+        elements = ActiveResource::Formats.remove_root(elements)          # re-evaluate removing root since we've removed a key
+      end
+
+      @metadata = metadata || {}
+      @elements = elements.each {|e| e['meta'] = @metadata }              # pass metadata down to resource records
+    end
+
+    ##
+    # Any attribute metadata about how the collection was obtained that is used
+    # when creating a new element in that collection.
+    #
+    # See
+    # #first_or_create
+    # #first_or_initialize
+    def where_values
+      metadata[:where_values] || {}
+    end
+
+    ##
+    # Alternate +first_or_create+ which removes all ResourceProxy parameters,
+    # merging +known_attributes+ and setting +query_params+ on +prefix_options+
+    #
+    # All other pararmeters are handled identically to the original method.
+    #
+    # See:
+    # ActiveResource::Collection#first_or_create
+    def first_or_create attributes={}
+      first || create_resource(attributes.reverse_merge(where_values))
+    rescue NoMethodError
+      raise "Cannot build resource from resource type: #{resource_class.inspect}"
+    end
+
+    ##
+    # Alternate +first_or_initialize+ which removes all ResourceProxy parameters,
+    # merging +known_attributes+ and setting +query_params+ on +prefix_options+
+    #
+    # All other pararmeters are handled identically to the original method.
+    #
+    # See:
+    # ActiveResource::Collection#first_or_initialize
+    def first_or_initialize attributes={}
+      first || initialize_resource(attributes.reverse_merge(where_values))
+    rescue NoMethodError
+      raise "Cannot create resource from resource type: #{resource_class.inspect}"
+    end
+
+    protected
+      ##
+      # Performs the work of merging known attributes to the supplied attributes
+      # on the resource, setting the +prefix_options+ to the known params, attempting
+      # to save, and returning the resource.
+      def create_resource attributes={}
+        resource_class.new(attributes.update(known_attributes)).tap do |resource|
+          resource.prefix_options = query_params
+          resource.save
+        end
+      end
+
+      ##
+      # Performs the work of merging known attributes to the supplied +attributes+
+      # on the resource, setting the +prefix_options+ to the known params and and
+      # returning the initialized resource.
+      def initialize_resource attributes={}
+        resource_class.new(attributes.update(known_attributes)).tap do |resource|
+          resource.prefix_options = query_params
+        end
+      end
+
+    private
+      # Parameter values to be merged with supplied attributes
+      KNOWN_PARAMETER_KEYS = [:filters].freeze
+
+      # Parameters to continue to use as query parameters
+      QUERY_PARAMETER_KEYS = [:scopes].freeze
+
+      # Additional collection-based parameters to strip/ignore
+      STRIP_PARAMETER_KEYS = [:order, :limit, :offset].freeze
+
+      # All parameters that are used by ResourceProxy that should be removed from attributes
+      PROXY_PARAMETER_KEYS = KNOWN_PARAMETER_KEYS + QUERY_PARAMETER_KEYS + STRIP_PARAMETER_KEYS
+
+      ##
+      # Helper to strip all params used by ResourceProxy from +orignal_params+
+      def clean_params
+        original_params.except(*PROXY_PARAMETER_KEYS)
+      end
+
+      # Helper to extract query params that will be used as +prefix_option+
+      def query_params
+        original_params.slice(*QUERY_PARAMETER_KEYS.inject(&:update)) || {}
+      end
+
+      # Helper to extract known params that will be used as known attributes
+      def known_params
+        original_params.values_at(*KNOWN_PARAMETER_KEYS).inject(&:update) || {}
+      end
+
+      # Helper to get additional known attributes from +original_params+
+      def known_attributes
+        clean_params.update(known_params)
+      end
+  end
+
+end
+
+##
+# Hook into ActiveResource::Collection to override their methods
+ActiveResource::Collection.class_eval do
+  include Daylight::Collection
+end

data/lib/daylight/errors.rb

@@ -0,0 +1,94 @@
+module Daylight::Errors
+  extend ActiveSupport::Concern
+
+  ##
+  # Regex for Content-Type
+  #--
+  # http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
+  CONTENT_TYPE_FORMAT = /([^\/]+)\/([^;]+)(?:;.*)?/
+
+  included do
+    ##
+    # Error messages from the root cause
+    # :attr: messages
+    attr_reader :messages
+
+    ##
+    # Parses the messages from the response
+    def initialize response, message = nil
+      super
+      @messages = []
+      parse(response)
+    end
+
+    ##
+    # Attaches the root cause messaging to included Client message
+    def to_s
+      super.tap do |message|
+        message << "  Root Cause = #{messages.join(', ')}" if messages?
+      end
+    end
+
+    def messages?
+      messages.present?
+    end
+
+    private
+      ##
+      # Sets the error messages when there is a payload on the response and a format that is handled
+      #--
+      # "application/xml; charset=utf-8"
+      # "application/json; charset=utf-8"
+      def parse response
+        _, subtype = CONTENT_TYPE_FORMAT.match(response.header['content-type']).captures rescue nil
+        return unless subtype.present? && response.body.present?
+
+        @messages =
+          case subtype
+            when  'xml'; self.class.from_xml(response.body)
+            when 'json'; self.class.from_json(response.body)
+            else
+              []
+          end
+      end
+  end
+
+  module ClassMethods
+    ##
+    # Parse payload that is in JSON
+    #--
+    # Examples:
+    #
+    # {'errors':'this is the problem'}
+    # {'errors':['this is problem one','this is problem two']}
+    def from_json(json)
+      decoded = ActiveSupport::JSON.decode(json) || {} rescue {}
+      if decoded.kind_of?(Hash) && decoded.has_key?('errors')
+        Array.wrap(decoded['errors'])
+      else
+        []
+      end
+    end
+
+    ##
+    # Parse payload that is in XML
+    #--
+    # Examples:
+    # <errors>
+    #   <error>this is a Problem<error>
+    # </errors>
+    # <errors>
+    #   <error>this is problem one<error>
+    #   <error>this is problem one<error>
+    # </errors>
+    def from_xml(xml)
+      Array.wrap(Hash.from_xml(xml)['errors']['error']) rescue []
+    end
+  end
+end
+
+##
+# Hook into ActiveResource::ClientError to parse the payload
+ActiveResource::ClientError.class_eval do
+  include Daylight::Errors
+end

data/lib/daylight/inflections.rb

@@ -0,0 +1,7 @@
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.acronym 'API'
+  inflect.acronym 'APIs'
+
+  inflect.acronym 'IP'
+  inflect.acronym 'IPs'
+end

data/lib/daylight/mock.rb

@@ -0,0 +1,282 @@
+require 'rack'
+
+##
+# Simple mocking framework that simplifies the process of writing tests for code that uses the Daylight client library.
+#
+# Works with both Rspec and TestUnit/Minitest.
+#
+# To start add this to your test_helper.rb or spec_helper.rb:
+#
+#     Daylight::Mock.setup
+#
+# The mock will simulate responses to calls so you don't have to stub out anything, especially not the HTTP calls themselves.
+# At the end of the test you can examine the calls that were made by calling *daylight_mock*.
+#
+# For example, this call returns a list of all the updated calls made on a *Host* object:
+#
+#     daylight_mock.updated(:host)
+#
+# To get only the last request use:
+#
+#     daylight_mock.last_updated(:host)
+#
+# Supported Calls: *created, updated, associated, indexed, shown, deleted*
+#
+module Daylight
+  module Mock
+
+    ##
+    # Represents a single mocked request-response pair.
+    class Handler
+      PathParts = Struct.new(:version, :resource, :id, :associated)
+      PATH_PARTS_REGEX = %r{^/([^/]+)/([^/]+)(?:/(\d+))?(?:/([^/]+))?\.json$}
+
+      attr_reader :request, :status, :response, :target_object
+
+      delegate :resource, to: :path_parts
+
+      def initialize(request)
+        @request = request
+      end
+
+      ##
+      # The request path split into logical parts: version, resource, id, and assocatied.
+      #
+      # Returns a PathParts Struct
+      def path_parts
+        @path_parts ||= PathParts.new(*path.match(PATH_PARTS_REGEX).captures)
+      end
+
+      ##
+      # The request's path
+      def path
+        request.uri.path
+      end
+
+      ##
+      # The mock respose body
+      def response_body
+        @response_body ||= handle_request
+      end
+
+      ##
+      # The request's POST data
+      def post_data
+        @post_data ||= JSON.parse(request.body)
+      end
+
+      ##
+      # The request's query params
+      def params
+        @params ||= Rack::Utils.parse_nested_query(request.uri.query)
+      end
+
+      ##
+      # The action to perform (based on the request path and method).
+      #
+      # Returns :associated, :shown, :indexed, :created, :updated or :deleted
+      def action
+        @action ||=
+          case request.method
+          when :get
+            if path_parts.associated.present?
+              :associated
+            elsif path_parts.id.present?
+              :shown
+            else
+              :indexed
+            end
+          when :post
+            :created
+          when :put
+            :updated
+          when :delete
+            :deleted
+          end
+      end
+
+      private
+        def model_class(model_name)
+          model_name.classify.constantize
+        end
+
+        def handle_request
+          send "process_#{action}"
+        end
+
+        def process_indexed
+          clazz = model_class(path_parts.resource)
+          list = [new_record(clazz)] * (rand(4)+1)
+
+          respond_with(body: list)
+        end
+
+        def process_shown
+          clazz = model_class(path_parts.resource)
+          @target_object = new_record(clazz, id: path_parts.id.to_i)
+
+          respond_with(body: @target_object)
+        end
+
+        def process_associated
+          clazz = model_class(path_parts.associated)
+          list = [new_record(clazz)] * (rand(4)+1)
+
+          respond_with(body: list)
+        end
+
+        def process_created
+          data = post_data[path_parts.resource.singularize]
+          clazz = model_class(path_parts.resource)
+          @target_object = new_record(clazz, data.merge(id:rand(100) + 1))
+
+          respond_with(body: @target_object, status: 201)
+        end
+
+        def process_updated
+          clazz = model_class(path_parts.resource)
+          data = post_data[path_parts.resource.singularize]
+          @target_object = new_record(clazz, data.merge(id: path_parts.id.to_i))
+
+          respond_with(status: 201)
+        end
+
+        def process_deleted
+          clazz = model_class(path_parts.resource)
+          @target_object = new_record(clazz, id: path_parts.id.to_i)
+
+          respond_with(status: 200)
+        end
+
+        def respond_with(options={})
+          @response = options[:body]
+          options[:body]   &&= encode(options[:body])
+          options[:status] ||= 200
+          @status = options[:status]
+          options
+        end
+
+        def encode(response)
+          if @response.is_a? Enumerable
+            {'foo'=>@response}.to_json
+          else
+            @response.encode
+          end
+        end
+
+        def new_record(clazz, options={})
+          filters = params['filters'] || {}
+          clazz.new(options.reverse_merge(filters).reverse_merge(id: rand(100) + 1))
+        end
+    end
+
+    ##
+    # Keeps track of all request and response pairs.
+    # Stored by action and resource.
+    #
+    # Example:
+    #
+    #     daylight_mock.created(:project).count.should == 3
+    #
+    #     daylight_mock.last_created(:project).name.should == 'Test Project'
+    class Recorder
+      def initialize
+        # hashy hash hash
+        @storage = Hash.new do |action_hash, action|
+          action_hash[action] =
+            Hash.new do |handler_hash, handler|
+              handler_hash[handler] = []
+            end
+        end
+      end
+
+      %w[created updated associated indexed shown deleted].each do |action|
+        define_method action do |resource|
+          @storage[action.to_s][resource.to_s.pluralize]
+        end
+
+        define_method "last_#{action}" do |resource|
+          @storage[action.to_s][resource.to_s.pluralize].last
+        end
+      end
+
+      ##
+      # Store a Handler in the Recorder
+      def record(handler)
+        @storage[handler.action.to_s][handler.resource.to_s] << handler
+      end
+    end
+
+    ##
+    # Minitest hook
+    module Minitest
+      # for minitest
+      def before_setup
+        capture_api_requests
+      end
+    end
+
+    class << self
+
+      ##
+      # Run in the test framework's setup to start and configure Daylight::Mock.
+      #
+      #     Daylight::Mock.setup
+      def setup
+        setup_rspec    if Module.const_defined? "RSpec"
+        setup_minitest if Module.qualified_const_defined?("MiniTest::Spec")
+      end
+
+      private
+        def setup_rspec
+          require 'webmock/rspec'
+
+          RSpec.configure do |config|
+            config.include Daylight::Mock
+
+            config.before(:each) do
+              capture_api_requests
+            end
+          end
+        end
+
+        def setup_minitest
+          require 'webmock/minitest'
+
+          clazz = MiniTest::Test rescue MiniTest::Unit::TestCase
+
+          clazz.class_eval do
+            include Daylight::Mock
+            include Daylight::Mock::Minitest
+          end
+        end
+    end
+
+    ##
+    # Access to Daylight::Mock::Recorder from within test definitions.
+    def daylight_mock
+      @daylight_mock ||= Recorder.new
+    end
+
+    private
+      def capture_api_requests
+        # capture all requests to the API server
+        stub_request(:any, /#{site_with_credentials}/)
+          .with(headers: {'X-Daylight-Framework' => /.*/})
+          .to_return do |request|
+            handler = Handler.new(request)
+            daylight_mock.record(handler)
+            handler.response_body
+          end
+      end
+
+      # Webmock prepends urls with any username and password when
+      # it does matching.
+      def site_with_credentials
+        @site_with_credentials ||= Daylight::API.site.dup.tap do |site|
+          site.userinfo = "#{Daylight::API.user}:#{Daylight::API.password}"
+          site.to_s
+        end
+      end
+  end
+end

data/lib/daylight/read_only.rb

@@ -0,0 +1,88 @@
+##
+# Support for read_only attributes.
+#
+# Attributes that are read_only are specified in the metadata from the response
+# from the API.
+#
+# Uses that information to keep from sending those read_only attributes in
+# subsequent requests to the API.
+#
+# This is useful for computational values that are served that do not have
+# corresponding column in the data store.
+
+module Daylight::ReadOnly
+  ##
+  # Get the list of read_only attributes from the metadata attribute.
+  # If there are none then an empty array is supplied.
+  #
+  # See:
+  # metadata
+
+  def read_only
+    metadata[:read_only] || []
+  end
+
+  ##
+  # Adds API specific options when generating json.
+  # Removes read_only attributes for requests.
+  #
+  # See
+  # except_read_only
+
+  def as_json(options={})
+    super(except_read_only(options))
+  end
+
+  ##
+  # Adds API specific options when generating xml.
+  # Removes read_only attributes for requests.
+  #
+  # See
+  # except_read_only
+
+  def to_xml(options={})
+    super(except_read_only(options))
+  end
+
+  ##
+  # Writers for read_only attributes are not included as methods
+  #--
+  # This is how we continue to prevent these read_only attributes to be set
+  # internally by removing ActiveResource's ability to set their values
+
+  def respond_to?(method_name, include_priv = false)
+    return false if read_only?(method_name)
+    super
+  end
+
+  private
+    ##
+    # Extends `method_missing` to raise an error when attempting to set a
+    # read_only attribute.
+    #
+    # Otherwise it continues with the `ActiveResource::Base#method_missing`
+    # functionality.
+
+    def method_missing(method_name, *arguments)
+      if read_only?(method_name)
+        logger.warn "Cannot set read_only attribute: #{method_name[0...-1]}" if logger
+        raise NoMethodError, "Cannot set read_only attribute: #{method_name[0...-1]}"
+      end
+
+      super
+    end
+
+    ##
+    # Ensures that read_only attributes are merged in with `:except` options.
+
+    def except_read_only options
+      options.merge(except: (options[:except]||[]).push(*read_only))
+    end
+
+    ##
+    # Determines if `method_name` is writing to a read_only attribute.
+
+    def read_only? method_name
+      !!(method_name =~ /(?:=)$/ && read_only.include?($`))
+    end
+end

data/lib/daylight/refinements.rb

@@ -0,0 +1,63 @@
+##
+# Support for handling ActiveRecord-like refinementmes and chaining them together
+# These refinements include: +where+, +find_by+, +order+, +limit+, and +offset+
+# Named +scopes+ are also supported.
+module Daylight::Refinements
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    delegate :where, :find_by, :order, :limit, :offset, to: :resource_proxy
+
+    attr_accessor :scope_names
+
+    # Define scopes that the class can be refined by
+    def scopes *names
+      self.scope_names ||= []
+
+      names.each do |scope|
+        self.scope_names << scope
+
+        # hand chaining duties off to the ResourceProxy instance
+        define_singleton_method scope do
+          resource_proxy.append_scope(scope)
+        end
+
+        # ResourceProxy instance also needs to respond to scopes
+        resource_proxy_class.send(:define_method, scope) do
+          append_scope(scope)
+        end
+      end
+
+      # self.scope_names.freeze
+    end
+
+    ##
+    # Use limits if no argument are supplied.  Otherwise, continue to use
+    # the ActiveRecord version which retrieves the full result set and calls
+    # first.
+    #
+    # See:
+    # ActiveRecord::Base#first
+    # Daylight::ResourceProxy#first
+    def first *args
+      args.size.zero? ? resource_proxy.first : super
+    end
+
+    protected
+      # Ensure the subclasses are setup with their ResourceProxy
+      def inherited subclass
+        Daylight::ResourceProxy[subclass]
+      end
+
+    private
+      # Sets up and saves the ResourceProxy in the resource class
+      def resource_proxy_class
+        Daylight::ResourceProxy[self]
+      end
+
+      # All chains create a new instance of the ResourceProxy
+      def resource_proxy
+        resource_proxy_class.new
+      end
+  end
+end