daylight 0.9.0.rc1

data/lib/daylight/reflection_ext.rb

@@ -0,0 +1,67 @@
+require 'active_resource/reflection'
+
+##
+# Extension to use the API namespace and version modules to lookup classes for
+# a reflection.  The benefit is to be able to define an association wihtout
+# the module name or using the :class_name option.
+#
+# Without the extension, we have to specify the `:class_name`:
+#
+#    class API::V1::Post < Daylight::API
+#       has_many :comments, class_name: 'api/v1/comment'
+#    end
+#
+# With the extension, it will be determined using the namespace and version modules
+#
+#    class API::V1::Post < Daylight::API
+#       belongs_to :blog
+#    end
+#
+#    API::V1::Post.find(1).blog  #=>  #<API::V1::Blog:0x007ffa8a43f1e8 ...>
+#
+# The `:class_name` option still can be specified for alternate behavior
+#
+#    class API::V1::Post < Daylight::API
+#       belongs_to :author, class_name: 'api/v1/user', foreign_key: 'created_by'
+#    end
+
+module Daylight::ReflectionExt
+  extend ActiveSupport::Concern
+
+  included do
+    ##
+    # Determines and tests for the name with namespace and version.
+    #
+    # Falls back to the name of the association which was the original behavior
+    # of `AssociationReflection`.
+    #
+    # See
+    # ActiveResource::Reflection::AssociationReflection
+
+    def expanded_name
+      @expanded_name = begin
+        candidate_name = [Daylight::API.namespace, Daylight::API.version, name.to_s.classify].join("::")
+        candidate_name.classify.constantize # test for the name, raise if non-existant
+        candidate_name.underscore
+      rescue
+        name.to_s # fallback to using the original functionality
+      end
+    end
+
+    private
+      ##
+      # Uses the expanded or default name to derive the class name.  Changes
+      # original `AssociationReflection` functionality.
+      #
+      # See
+      # ActiveResource::Reflection::AssociationReflection.derive_class_name
+
+      def derive_class_name
+        return (options[:class_name] ? options[:class_name].to_s : expanded_name).classify
+      end
+  end
+end
+
+ActiveResource::Reflection::AssociationReflection.class_eval do
+  include Daylight::ReflectionExt
+end

data/lib/daylight/resource_proxy.rb

@@ -0,0 +1,226 @@
+##
+# Proxies requests to ActiveResource once the data has been accessed.
+# Allows chaining of scope calls ala ActiveRecord
+class Daylight::ResourceProxy
+  include Enumerable
+
+  delegate :to_xml, :to_yaml, :length, :each, :to_ary, :size, :last, :[], :==, to: :to_a
+  delegate :first_or_initialize, :first_or_create, to: :records
+  delegate :resource_class, to: :class
+
+  attr_reader :association_name, :association_resource
+
+  # turn off constructor, only use factory methods
+  private_class_method :new
+
+  def initialize association={}
+    @current_params = {}
+    @association_name, @association_resource = association.first
+  end
+
+  ##
+  # Delegates appending to the association resource when available
+
+  def << value
+    if association_resource
+      association_resource.send("#{association_name}=", records.elements << value)
+    else
+      raise NoMethodError, "undefined method `<<' for #{self}"
+    end
+  end
+
+  ##
+  # Sets `from` URL on a request
+  def from from
+    @from = from
+    self
+  end
+
+  ##
+  # Loads records from server based on current paremeters and from URL
+  def load
+    resource_class.find(:all, params: to_params, from: @from)
+  end
+
+  ##
+  # Returns a copy of the current parameters used to fetch records
+  def to_params
+    current_params.dup
+  end
+
+  ##
+  # Returns the records, requests them from server if not fetched
+  def records
+    @records ||= load
+  end
+
+  ##
+  # Returns the records, forces fetch from server
+  def reload
+    @records = load
+  end
+
+  ##
+  # Converts records to an Array
+  def to_a
+    records.to_a
+  end
+
+  ##
+  # Adds scopes to the current parameters
+  def append_scope scope
+    spawn.tap do |proxy|
+      proxy.current_params[:scopes] ||= []
+      proxy.current_params[:scopes] << scope
+      proxy.current_params[:scopes].uniq!
+    end
+  end
+
+  ##
+  # Merges conditions to the current parameters
+  def where conditions
+    spawn.tap do |proxy|
+      proxy.current_params[:filters] ||= {}
+      proxy.current_params[:filters].merge! conditions
+    end
+  end
+
+  ##
+  # Sets limit in the current parameters
+  def limit value
+    spawn.tap do |proxy|
+      proxy.current_params[:limit] = value
+    end
+  end
+
+  ##
+  # Sets order in the current parameters
+  def order value
+    spawn.tap do |proxy|
+      proxy.current_params[:order] = value
+    end
+  end
+
+  ##
+  # Sets offset in the current parameters
+  def offset value
+    spawn.tap do |proxy|
+      proxy.current_params[:offset] = value
+    end
+  end
+
+  ##
+  # Merges conditions to the current parameters, and fetches the first result.
+  # Immediately issues the request to the API.
+
+  def find_by conditions
+    where(conditions).limit(1).first
+  end
+
+  ##
+  # Sets the limit to the current parameters, and fetches the first result.
+  # Immediately issues the request to the API.
+
+  def first
+    limit(1).to_a.first
+  end
+
+  ##
+  # Special inspect that shows the fetched results (up to 10 fo them) and the
+  # current params to fetch those results.
+  #
+  # Immediately issues the request to the API.
+
+  def inspect
+    records = to_a.take(11)
+    records[10] = '...' if entries.size == 11
+
+    "#<#{self.class.name} #{records} @current_params=#{current_params}>"
+  end
+
+  class << self
+    # Each ResourceProxy will have thier own resource
+    attr_accessor :resource_class
+
+    ##
+    # Factory method to generate a child class for ResourceProxy with the
+    # required resource class.
+    #
+    #     proxy = ResourceProxy[User]  #=> User::ResourceProxy
+    #
+    # Onece a child class has been created, it can be use it to create
+    # instances:
+    #
+    #    ResourceProxy[User].new
+
+    def [] resource_class
+      if resource_class.const_defined?(:ResourceProxy)
+        return resource_class.const_get(:ResourceProxy)
+      end
+
+      Class.new(Daylight::ResourceProxy) do
+        # Allow instances to be created
+        public_class_method :new
+
+        # Set our resource
+        self.resource_class = resource_class
+
+        # Set our ResourceProxy constant
+        resource_class.const_set(:ResourceProxy, self)
+      end
+    end
+
+    ##
+    # Define a name for the class
+    def name
+      "#{resource_class}::ResourceProxy"
+    end
+
+    ##
+    # Use the class name as the inspect
+    alias_method :inspect, :name
+  end
+
+  ##
+  # Will attempt to fulfill the method if it exists on the resource or if it
+  # exists on an Array.  Defines or delegates the method on for subsequent
+  # execution.
+
+  def method_missing(method_name, *args, &block)
+    if resource_class.respond_to?(method_name)
+      self.class.send(:define_method, method_name) do |*method_args, &method_block|
+        resource_class.send(method_name, *method_args, &method_block)
+      end
+      resource_class.send(method_name, *args, &block)
+    elsif Array.method_defined?(method_name)
+      self.class.delegate method_name, :to => :to_a
+      to_a.send(method_name, *args, &block)
+    else
+      super
+    end
+  end
+
+  protected
+    attr_accessor :current_params
+
+    ##
+    # Clone current ResourceProxy and with `current_params` to keep its query
+    # context
+    #
+    # See
+    # reset
+
+    def spawn
+      clone.reset(current_params)
+    end
+
+    ##
+    # Resets a ResourceProxy marked to refetch results based on blank or
+    # supplied `current_params`
+
+    def reset old_params={}
+      @current_params = old_params.deep_dup
+      @records = nil
+      self
+    end
+end

data/lib/daylight/version.rb

@@ -0,0 +1,10 @@
+module Daylight
+  module Version
+    MAJOR = 0
+    MINOR = 9
+    PATCH = 0
+    BUILD = 'rc1'
+
+    Daylight::VERSION = STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
+  end
+end

data/lib/daylight.rb

@@ -0,0 +1,27 @@
+$:.unshift File.expand_path('../../rails', __FILE__)
+
+require 'active_support/core_ext'
+require 'active_resource'
+
+##
+# Include into API client to enable Daylight::API based queries
+
+module Daylight
+  extend ActiveSupport::Autoload
+
+  eager_autoload do
+    autoload :Version
+    autoload :Associations
+    autoload :Collection
+    autoload :Errors
+    autoload :Inflections
+    autoload :Refinements
+    autoload :ReadOnly
+    autoload :ResourceProxy
+    autoload :ReflectionExt
+    autoload :API
+  end
+end
+
+# run eager load
+Daylight.eager_load!

data/rails/daylight/api_controller.rb

@@ -0,0 +1,354 @@
+##
+# Common conntroller built on top of `ApplicationController` that assists with
+# setting up standard, conventional REST and Daylight supported actions.
+#
+# Have your API Controllers subclass from APIController:
+#
+#   class ExampleController < APIController
+#   end
+#
+# You must "turn on" common actions to allow for functionality.  All common
+# actions are turned off by default so that what is exposed is
+# determiend by the API devloper.  For example, to turn on `index` action:
+#
+#   class ExampleController < APIController
+#     handles :index
+#   end
+#
+# The common actions provided by APIController are: `:index`, `:create`,
+# `:show`, `:update`, `:destroy`, `:associated`, and `:remoted`.
+#
+# The method implementations are simply methods in a superclass and can be
+# overwritten or called through `super`:
+#
+#   class ExampleController < APIController
+#     handles :index
+#
+#     def index
+#        @title = 'My Title'
+#        super
+#     end
+#   end
+#
+# The model and instance variable for these actions are based on the
+# controller name.  If you need to customize these, you can change them:
+#
+#   class ExampleController < APIController
+#     self.model_name  = :news
+#     self.record_name = :post
+#
+#     handles :index
+#   end
+#
+# Continue to use `ApplicationController` for shared methods.
+#
+# See:
+# ApplicationController
+
+class Daylight::APIController < ApplicationController
+  include Daylight::Helpers
+  include VersionedUrlFor
+
+  API_ACTIONS = [:index, :create, :show, :update, :destroy, :associated, :remoted].freeze
+  class_attribute :record_name, :collection_name, :model_name
+
+  alias_method :set_record_name,     :record_name=      #:nodoc:
+  alias_method :set_collection_name, :collection_name=  #:nodoc:
+  alias_method :set_model_name,      :model_name=       #:nodoc:
+
+  ##
+  # Ensure messaging when sending unknown attributes or improper SQL
+  rescue_from ArgumentError,
+              ActiveRecord::UnknownAttributeError,
+              ActiveRecord::StatementInvalid do |e|
+
+    render json: { errors: e.message }, status: :bad_request
+  end
+
+  ##
+  # Ensure messaging when there are validation errors on save and update
+  rescue_from ActiveRecord::RecordInvalid do |e|
+    render json: { errors: e.record.errors }, status: :unprocessable_entity
+  end
+
+  ##
+  # Ensure messaging when there unpermitted attributes on save and update
+  rescue_from ActionController::UnpermittedParameters do |e|
+    errors = {}
+    e.params.each { |key| errors[key] = ['unpermitted parameter'] }
+    render json: { errors: errors }, status: :unprocessable_entity
+  end
+
+  ##
+  # Ensure messaging when attributes have not been permitted on the controller
+  rescue_from ActiveModel::ForbiddenAttributesError do |e|
+    render json: { errors: 'parameters have not been permitted on this action' }, status: :bad_request
+  end
+
+
+  class << self
+    protected
+      ##
+      # Turns on common actions based on subclass needs (sets them as public methods).
+      # Uses whitelist of allowed actions to be handled.
+      #
+      # See:
+      # API_ACTIONS
+      #--
+      # `public` is called in context of the subclass
+      def handles *actions
+        actions = API_ACTIONS.dup if actions.any? {|a| a == :all }
+
+        whitelisted = actions.map(&:to_sym) & API_ACTIONS
+
+        if (unhandled = actions - whitelisted).present?
+          logger.warn "Daylight::APIController isn't handling unwhitelisted actions"
+          logger.warn "\tspecified in #{self.name}#handles: #{unhandled.join(',')}"
+        end
+
+        public(*whitelisted) if whitelisted.present?
+      end
+
+      ##
+      # Retrieves conventional key for a model name used in params
+      def model_key
+        model_name.to_s.singularize.to_sym
+      end
+
+      ##
+      # Retieves `const` for ActiveRecord model as defined by `model_name`
+      def model
+        model_name.to_s.classify.constantize
+      end
+
+      ##
+      # Delegates to `model#primary_key`
+      # Not using delegate as model may change via `model_name` configuration
+      def primary_key
+        model.primary_key
+      end
+
+      ##
+      # Sets the default `model_name` and `record_name` by default.
+      # By default, they are based on the value determined by `controller_name`
+      #
+      # See:
+      # ActionController::Base.controller_name
+      def inherited api
+        name = api.controller_name.singularize
+
+        api.model_name      = name
+        api.record_name     = name
+        api.collection_name = 'collection'
+      end
+  end
+
+  protected
+    ##
+    # Retrieves the value for the `record_name` instance variable
+    def record
+      instance_variable_get("@#{record_name}")
+    end
+
+    ##
+    # Sets the value for the `record_name` instance variable
+    def record= value
+      instance_variable_set("@#{record_name}", value)
+    end
+
+    ##
+    # Retrieves the value for the `record_name` instance variable
+    def collection
+      instance_variable_get("@#{collection_name}")
+    end
+
+    ##
+    # Sets the value for the `record_name` instance variable
+    def collection= value
+      instance_variable_set("@#{collection_name}", value)
+    end
+
+    ##
+    # Instance-level delegate of the `model` method
+    #
+    # See:
+    # #model
+    def model
+      self.class.send(:model)
+    end
+
+    ##
+    # Instance-level delegate of the `model_key` method
+    #
+    # See:
+    # #model_key
+    def model_key
+      self.class.send(:model_key)
+    end
+
+    ##
+    # Retrieves the strong parameters for a model based on the `model_key` name.
+    # Ex. post_params
+    #
+    # If strong parameters are not defined, it will use the `model_key` to
+    # dereference the raw params.
+    # Ex. params[:post]
+    def model_params
+      model_params_name = "#{model_key}_params"
+      respond_to?(model_params_name, true) ? send(model_params_name) : params[model_key]
+    end
+
+    ##
+    # Instance-level delegate of the `primary_key` method
+    #
+    # See:
+    # #primary_key
+    def primary_key
+      self.class.send(:primary_key)
+    end
+  private
+    #
+    # The common actions for Daylight::APIController
+    #
+
+    ##
+    # Retrieves the collection for the records for `model` with any refinements
+    # in the params passed to `refine_by`.  Accessed via:
+    #
+    #   GET /posts.json
+    #
+    # Subclass implementation:
+    #
+    #   def index
+    #     render json: Post.refine_by(params)
+    #   end
+    #
+    # See:
+    # Daylight::Refiners.refine_by
+    def index
+      render json: self.collection = model.refine_by(params)
+    end
+
+    ##
+    # Creates a record for the `model` with the attributes supplied in params.
+    # Accessed via:
+    #
+    #   POST /posts.json
+    #
+    # Subclass implementation:
+    #
+    #   def create
+    #     @post = Post.new(params[:post])
+    #     @post.save!
+    #
+    #     render json: @post, status: :created, location: @post
+    #   end
+    def create
+      self.record = model.new(model_params)
+      record.save!
+
+      render json: record, status: :created, location: record
+    end
+
+    ##
+    # Retrieves a record for the `model` with the `id` supplied in params.
+    # If the primary_key is configured to something besides `id` it will
+    # use that as a key.
+    #
+    # Accessed via:
+    #
+    #   GET /posts/1.json
+    #
+    # Subclass implementation:
+    #
+    #   def show
+    #     render json: Post.find(params[Post.primary_key])
+    #   end
+    def show
+      render json: self.record = model.find(params[primary_key])
+    end
+
+    ##
+    # Updates a record for the `model` with the `id` supplied in params.
+    # If the primary_key is configured to something besides `id` it will
+    # use that as a key.
+    #
+    # Accessed via:
+    #
+    #   PATCH/PUT /posts/1.json
+    #
+    # Subclass implementation:
+    #
+    #   def update
+    #     Post.find(params[Post.primary_key]).update!(params[:post])
+    #
+    #     head :no_content
+    #   end
+    def update
+      (self.record = model.find(params[primary_key])).update!(model_params)
+
+      head :no_content
+    end
+
+    ##
+    # Destroys a record for the `model` with the `id` supplied in params.
+    # If the primary_key is configured to something besides `id` it will
+    # use that as a key.
+    #
+    # Accessed via:
+    #
+    #   DELETE /posts/1.json
+    #
+    # Subclass implementation:
+    #
+    #   def destroy
+    #     Post.find(params[Post.primary_key]).destroy
+    #
+    #     head :no_content
+    #   end
+    def destroy
+      (self.record = model.find(params[primary_key])).destroy
+
+      head :no_content
+    end
+
+    ##
+    # Retrieves the collection for the associated records for a `model` with
+    # any refinements in the params passed to `associated`.  Accessed via:
+    #
+    #   GET /posts/1/comments.json
+    #
+    # Subclass implementation:
+    #
+    #   def associated
+    #     render json: Post.associated(params), root: associated_params
+    #   end
+    #
+    # See:
+    # Daylight::Refiners.associated
+    # Daylight::Helpers.associated_params
+    # RouteOptions
+    def associated
+      render json: self.collection = model.associated(params), root: associated_params
+    end
+
+    ##
+    # Retrieves the collection returned by the `remoted` method with
+    # any refinements in the params passed to `remoted`.  Accessed via:
+    #
+    #   GET /posts/1/all_authorized_users.json
+    #
+    # Subclass implementation:
+    #
+    #   def remoted
+    #     render json: Post.remoted(params), root: remoted_params
+    #   end
+    #
+    # See:
+    # Daylight::Refiners.remoted
+    # Daylight::Helpers.remoted_params
+    # RouteOptions
+    def remoted
+      render json: self.collection = model.remoted(params), root: remoted_params
+    end
+end

data/rails/daylight/documentation.rb

@@ -0,0 +1,13 @@
+require 'haml'
+require 'actionpack/page_caching'
+
+module DaylightDocumentation
+end
+
+##
+# Rails::Engine to add Documentation features to a Daylight::Server
+module Daylight
+  class Documentation < ::Rails::Engine
+    isolate_namespace DaylightDocumentation
+  end
+end