daylight 0.9.0.rc1

data/lib/daylight/api.rb

@@ -0,0 +1,293 @@
+##
+# Daylight API Client Library
+#
+# Use this client in your Ruby/Rails applications for ease of use access to the
+# Client API.
+#
+# Unlike typical ActiveResource clients, the Daylight API Client has been
+# designed to be used similarly to ActiveRecord with scopes and the ability to
+# chain queries.
+#
+#     ClientAPI::Post.all
+#     ClientAPI::Post.where(code:'iad1')
+#     ClientAPI::Post.published                  # scope
+#     ClientAPI::Post.find(1).comments           # associations
+#     ClientAPI::Post.find(1).public_commenters  # remote method on model
+#     ClientAPI::Post.find(1).commenters.
+#       where(username: 'reidmix')               # chaining
+#
+# Build your client models using Daylight::API, it is a wrapper with extended
+# functionality to ActiveResource::Base
+#
+#     class ClientAPI::Post < Daylight::API
+#       scopes :internal
+#
+#       belongs_to :user
+#       has_many   :comments
+#       has_many   :commenters, through: :comments
+#
+#       remote :public_commenters, class_name: 'client_api/user'
+#     end
+#
+# Once all your client models are built, setup your API Client Library and
+# startup via `setup!` (in an intitializer):
+#
+#     require 'client_api'
+#
+#     Daylight::API.setup!({
+#       namespace: 'client_api',
+#       password:  'test',
+#       endpoint:  'http://api.example.org/
+#     })
+
+class Daylight::API < ActiveResource::Base
+  include Daylight::ReadOnly
+  include Daylight::Refinements
+  include Daylight::Associations
+
+  class << self
+    attr_reader    :version, :versions, :namespace
+    cattr_accessor :request_root_in_json
+    alias_method   :endpoint, :site
+
+    DEFAULT_CONFIG = {
+      namespace: 'API',
+      endpoint:  'http://localhost',
+      versions:  %w[v1]
+    }.freeze
+
+    ##
+    # Setup and configure the Daylight API. Must be called before Client API use.
+    # Will use the following defaults:
+    #
+    #     Daylight::API.setup!({
+    #       namespace: 'API',
+    #       password:  nil,
+    #       endpoint:  'http://localhost',
+    #       versions:  ['v1'],
+    #       version:   'v1'
+    #       timeout:   60  # in seconds
+    #     })
+    #
+    # Daylight currenly requires that your API is within a module `namespace`
+    #
+    # The `endpoint` sets ActiveResource#site configuration.
+    # The `password` is the HTTP Authentication password.
+    #
+    # Daylight assumes you're versioning your API, you can supply the `versions`
+    # that are supported by your API and which `version` is active.
+    #
+    # By default, ActiveResource#request_root_in_json is set to true.
+    # You can turn this off with the `request_root_in_json` configuration.
+    #
+    # A convenience for versioned APIs is to alias the active Client API models
+    # to versionless constance.  For example
+    #
+    #     ClientAPI::V1::Post
+    #
+    # Aliased to:
+    #
+    #     ClientAPI::Post
+    #
+    # This functionalitity is turned on using the `alias_apis` configuration.
+
+    def setup! options={}
+      config = options.with_indifferent_access.reverse_merge(DEFAULT_CONFIG)
+
+      self.namespace = config[:namespace]
+      self.password  = config[:password]
+      self.endpoint  = config[:endpoint]
+      self.versions  = config[:versions].freeze
+      self.version   = config[:version] || config[:versions].last  # specify or use most recent version
+      self.timeout   = config[:timeout] if config[:timeout]        # default read_timeout is 60
+
+      # Only "parent" elements required to emit a root node
+      self.request_root_in_json = config[:request_root_in_json] || true
+
+      headers['X-Daylight-Framework'] = Daylight::VERSION
+
+      alias_apis unless config[:no_alias_apis]
+    end
+
+    ##
+    # Find a single resource from the default URL
+    #
+    # Fixes bug to short-circuit and return `nil` if scope/id is nil.
+    # ActiveResource::Base will perform the call and return with an error.
+
+    def find_single(scope, options)
+      return if scope.nil?
+      super
+    end
+
+    ##
+    ##
+    # Whether to show root for the request
+    #
+    # API requires JSON request to emit a root node named after the object’s
+    # type this is different from `include_root_in_json` where _every_
+    # `ActiveResource` supplies its root.
+    #
+    # This causes problems with `accepts_nessted_attributes_for` where the
+    # *_attributes do not need it (and is broken by having a root elmenet)
+    #
+    # Turned on by default when transmitting JSON requests.
+    #
+    # See:
+    # encode
+    def request_root_in_json?
+      request_root_in_json && format.extension == 'json'
+    end
+
+    private
+      attr_writer  :versions, :namespace
+      alias_method :endpoint=, :site=
+
+      ##
+      # Set the `version` and make sure it's a member of the supported versions
+
+      def version= v
+        unless versions.include?(v)
+          raise "Unsupported version #{v} is not one of #{versions.join(', ')}"
+        end
+
+        @version     = v.upcase
+        version_path = "/#{v.downcase}/".gsub(/\/+/, '/')
+
+        set_prefix version_path
+      end
+
+      ##
+      # Alias the configured client API constants to be references without a
+      # version number for the active version:
+      #
+      # For example, if the active version is 'v1':
+      #
+      #     API::Post   # => API::V1::Post
+      #
+      # Assumes all your model classes are loaded (defined)
+
+      def alias_apis
+        api_classes   = "#{namespace}::#{version}".constantize.constants
+        api_namespace = namespace.constantize
+
+        api_classes.each do |api_class|
+          api_namespace.const_set(api_class, "#{namespace}::#{version}::#{api_class}".constantize)
+        end
+
+        true
+      rescue => e
+        logger.error("Could not alias_apis #{e.class}:\n\t#{e.message}") if logger
+
+        false
+      end
+  end
+
+  attr_reader :metadata
+
+  ##
+  # Extends ActiveResource to allow for saving metadata from the responses on
+  # the `meta` key.  Will store this metadata on the `metadata` attribute.
+  #---
+  # Does this extension by overwritting ActiveResource::Base#initialize method
+  # Concern cannot call `super` from module to base class (we think)
+
+  def initialize(attributes={}, persisted = false)
+    extract_metadata!(attributes)
+
+    super
+  end
+
+  ##
+  # Get the list of nested_resources from the metadata attribute.
+  # If there are none then an empty array is supplied.
+  #
+  # See:
+  # metadata
+
+  def nested_resources
+    @nested_resources ||= metadata[:nested_resources] || []
+  end
+
+  ##
+  # Used to assist `find_or_create_resource_for` to use embedded attributes
+  # to new Daylight::API model objects.
+  #
+  # See:
+  # find_or_create_resource_for
+
+  class HashResourcePassthrough
+    def self.new(value, _)
+      # load values using ActiveResource::Base and extract them as attributes
+      Daylight::API.new(value.duplicable? ? value.dup : value).attributes
+    end
+  end
+
+  ##
+  # When an association is supplied via a hash of `*_attributes` then create
+  # (a set) of new Client API objects instead of leaving as a hash.
+
+  def find_or_create_resource_for name
+    # if the key is attributes attributes for a configured association
+    if /(?:_attributes)\z/ =~ name && reflections.key?($`.to_sym)
+      HashResourcePassthrough
+    else
+      super
+    end
+  end
+
+  ##
+  # Returns the serialized string representation of the resource in the configured
+  # serialization format specified in ActiveResource::Base.format.
+  #
+  # For JSON formatted requests default option is to include the root element
+  # depending on the `request_root_in_json` configuration.
+
+  def encode(options={})
+    super(self.class.request_root_in_json? ? { :root => self.class.element_name }.merge(options) : options)
+  end
+
+  protected
+    ##
+    # Override `ActiveResource` method so it strips the meta attributes for create and update actions.
+    #
+    # Solves problem where `remove_root` was not performing because meta was still in the response.
+    # For GET objects, this is handled by `initialize` but that's too late in this case.
+    #
+    # See:
+    # ActiveResource::Base#load_attributes_from_response
+
+    def load_attributes_from_response(response)
+      if response_loadable?(response)
+        decoded_body = self.class.format.decode(response.body)
+        extract_metadata!(decoded_body)
+        load(decoded_body, true, true)
+        @persisted = true
+      end
+    end
+
+  private
+
+    ##
+    # Does this response actaully have a body?
+
+    def response_loadable?(response)
+      response_code_allows_body?(response.code) &&
+      (response['Content-Length'].nil? || response['Content-Length'] != "0") &&
+      !response.body.nil? &&
+      response.body.strip.size > 0
+    end
+
+    ##
+    # Extract meta attribute from attributes and save it
+
+    def extract_metadata!(attributes)
+      if Hash === attributes && attributes.has_key?('meta')
+        # save and strip any metadata supplied in the response
+        metadata = (attributes.delete('meta')||{}).with_indifferent_access
+        metadata.merge!(metadata.delete(self.class.element_name) || {})
+      end
+      @metadata = metadata || {}
+    end
+end
+

data/lib/daylight/associations.rb

@@ -0,0 +1,247 @@
+##
+# Support for quering associations between client objects
+#
+module Daylight::Associations
+  extend ActiveSupport::Concern
+
+  included do
+    private
+      # All chains create a new instance of the ResourceProxy for the supplied resource
+      def resource_proxy_for reflection, resource
+        Daylight::ResourceProxy[reflection.klass].new({reflection.name => resource})
+      end
+
+      # builds the path to the associated collection based on the has_many reflection
+      def association_path(reflection)
+        prefix          = self.class.prefix
+        collection_name = self.class.collection_name
+        member_id       = URI.parser.escape id.to_s
+        extension       = reflection.klass.format.extension
+
+        "#{prefix}#{collection_name}/#{member_id}/#{reflection.name}.#{extension}"
+      end
+
+      def call_remote(remoted_method, model)
+        response = get(remoted_method)
+        # strip the root, but take into consideration metadata
+        if Hash === response && response.has_key?(remoted_method.to_s)
+          response = response[remoted_method.to_s]
+        end
+        case response
+          when Array
+            model.send(:instantiate_collection, response)
+          when Hash
+            model.send(:instantiate_record, response)
+        end
+      end
+  end
+
+  module ClassMethods
+
+    def reflection_names
+      reflections.keys.map(&:to_s)
+    end
+
+    ##
+    # Support for the :through option so that the server-side handles the association.
+    #
+    #   Post.first.comments #=> GET /posts/1/comments.json
+    #
+    # Also adds the setter for assocations:
+    #
+    #   Post.first.comments = [new_comment]
+    #
+    # See:
+    # ActiveResource::Associations#has_many
+
+    def has_many name, options={}
+      through = options.delete(:through).to_s
+      return super unless through == 'associated'
+
+      create_reflection(:has_many, name, options).tap do |reflection|
+        nested_attribute_key = "#{reflection.name}_attributes"
+
+        # setup the resource_proxy to fetch the results
+        define_cached_method reflection.name, cache_key: nested_attribute_key do
+          # return a empty collection if this is a new record
+          return self.send("#{reflection.name}=", []) if new?
+
+          resource_proxy = resource_proxy_for(reflection, self)
+          resource_proxy.from(association_path(reflection))
+        end
+
+        # define setter that places the value directly in the attributes using
+        # the nested_attributes functionality server-side
+        define_method "#{reflection.name}=" do |value|
+          self.attributes[nested_attribute_key] = value
+          instance_variable_set(:"@#{reflection.name}", value)
+        end
+
+      end
+    end
+
+    ##
+    # Adds a setter to the original `belongs_to` method that uses nested_attributes.
+    # Also, hands off the :through option to `belongs_to_through`.
+    #
+    # Example:
+    #
+    #    comment = Comment.find(1)
+    #    comment.creator = current_user
+    #
+    # See:
+    # ActiveResource::Associations#belongs_to
+
+    def belongs_to name, options={}
+      # continue to let the original do all the work.
+      super.tap do |reflection|
+
+        # Defines a setter caching the value in an instance variable for later
+        # retrieval.  Stash value directly in the attributes using the
+        # nested_attributes functionality server-side.
+        define_method "#{reflection.name}=" do |value|
+          attributes[reflection.foreign_key] = value.id           # set the foreign key
+          attributes["#{reflection.name}_attributes"] = value     # set the nested_attributes
+          instance_variable_set(:"@#{reflection.name}", value)    # set the cached value
+        end
+      end
+    end
+
+    ##
+    # Adds getter and setter methods for `has_one` associations that are
+    # through a `belongs_to` association.  Assumes that the information about
+    # the association is generated in the nested attributes by a HasOneThrough
+    # serializer.
+    #
+    # In this example, if we did not go through the identity association the
+    # primary keys would be generated, but upon save, an error would be thrown
+    # because it is an unknown attribute.  This only happens with `belongs_to`
+    # methods as they contain the primary_key.
+    #
+    # For example, consider `user_id` and `zone_id` primary keys:
+    #
+    #   class PostSerializer < ActiveModel::Serializer
+    #     embed :ids
+    #
+    #     has_one :blog
+    #     has_one :company, :zone through: :blog
+    #    end
+    #
+    # It will generate the following json:
+    #
+    #    {
+    #      "post": {
+    #        "id": 1,
+    #        "blog_id": 2,
+    #        "blog_attributes": {
+    #          "id": 2,
+    #          "company_id": 3
+    #        }
+    #      }
+    #    }
+    #
+    # An ActiveResource can define `belongs_to` with :through to read from
+    # nested attributes for fetching by primary_key or setting to save.
+    #
+    #   class Post < Daylight::API
+    #     belongs_to :blog
+    #     has_one    :company, through: :blog
+    #   end
+    #
+    #  So that:
+    #
+    #   p = Post.find(1)
+    #   p.blog      # => #<Blog @attributes={"id"=>1}>
+    #   p.company   # => #<Company @attributes={"id"=>3}>
+    #
+    #  And setting these associations will work with passing validations:
+    #
+    #   p.company = Company.find(1)
+    #   p.save  # => true
+
+    def has_one_through name, options
+      through = options.delete(:through).to_s
+
+      create_reflection(:has_one, name, options).tap do |reflection|
+        nested_attributes_key  = "#{reflection.name}_attributes"
+        through_attributes_key = "#{through}_attributes"
+
+        define_cached_method reflection.name, index: through_attributes_key do
+          reflection.klass.find(attributes[through_attributes_key][reflection.foreign_key])
+        end
+
+        define_method "#{reflection.name}=" do |value|
+          through_attributes = attributes["#{through}_attributes"] ||= {}
+
+          through_attributes[reflection.foreign_key] = value.id
+          through_attributes[nested_attributes_key]  = value
+          instance_variable_set(:"@#{reflection.name}", value)
+        end
+      end
+    end
+
+    ##
+    # Fix bug in has_one that is not creating the request correctly.
+    # Use `where` functionality as it peforms the function that is needed
+    #
+    # Allows the has_one :through association.
+    #
+    # See:
+    # has_one_through
+
+    def has_one(name, options = {})
+      return has_one_through(name, options) if options.has_key? :through
+
+      create_reflection(:has_one, name, options).tap do |reflection|
+        define_cached_method reflection.name do
+          reflection.klass.where(:"#{self.class.element_name}_id" => self.id).first
+        end
+
+        define_method "#{reflection.name}=" do |value|
+          attributes["#{reflection.name}_attributes"] = value     # set the nested_attributes
+          value.attributes[:"#{self.class.element_name}_id"] = self.id
+          instance_variable_set(:"@#{reflection.name}", value)    # set the cached value
+        end
+      end
+    end
+
+    ##
+    # Adds a method to the model that calls the remote action for its data.
+    #
+    # Example:
+    #
+    #   remote :posts_by_popularity, class_name: 'post'
+    #
+
+    def remote name, options
+      create_reflection(:remote, name, options).tap do |reflection|
+        define_cached_method reflection.name do
+          call_remote(reflection.name, reflection.klass)
+        end
+      end
+    end
+
+    private
+      def define_cached_method method_name, options={}, &block
+        # define an uncached method to call
+        uncached_method_name = :"#{method_name}_without_cache"
+        define_method(uncached_method_name, block)
+
+        # define the cached wrapper around the uncached method
+        define_method method_name do
+          ivar_name  = :"@#{method_name}"
+          cache_key  = options[:cache_key] || method_name
+          attributes = options.has_key?(:index) ? @attributes[options[:index]] : @attributes
+
+          if instance_variable_defined?(ivar_name)
+            instance_variable_get(ivar_name)
+          elsif attributes.include?(cache_key)
+            attributes[cache_key]
+          else
+            instance_variable_set ivar_name, send(uncached_method_name)
+          end
+        end
+      end
+
+  end
+end

data/lib/daylight/client_reloader.rb

@@ -0,0 +1,45 @@
+##
+# Runs `alias_api` in the console during API development to re-alias the to the
+# reloaded constants.  Otherwise, they will hold onto the old un-reloaded
+# constants in memory.
+#
+# This is not intended for end-users of the API, but can be used by them if
+# needed.
+#
+# You must enable this functionality:
+#
+#     require 'daylight/client_reloader'
+#
+# NOTE: Currently only works with IRB
+
+module ClientReloader
+  extend ActiveSupport::Concern
+
+  included do
+    def reload! print=true
+      super
+
+      puts "Realiasing API..." if print
+      suppress_warnings do
+        Daylight::API.send(:alias_apis)
+      end
+    end
+  end
+
+  class << self
+    def include
+      if console && defined?(console::ExtendCommandBundle)
+        console::ExtendCommandBundle.class_eval do
+          include ClientReloader
+        end
+      end
+    end
+
+    def console
+      # we'll figure a way to set other consoles (eg. pry) later if neccessary
+      @console ||= IRB rescue nil
+    end
+  end
+end
+
+ClientReloader.include