daylight 0.9.0.rc1

data/rails/daylight/helpers.rb

@@ -0,0 +1,32 @@
+##
+# Mixin helpers to get specific params in an +ActionController+
+module Daylight::Helpers
+  def scoped_params
+    params[:scopes]
+  end
+
+  def filter_params
+    params[:filters]
+  end
+
+  def order_params
+    params[:order] if params[:order].present?
+  end
+
+  def limit_params
+    params[:limit] if params[:limit].present?
+  end
+
+  def offset_params
+    # non-integer offsets are allowed by offset, we do the check for you
+    Integer(params[:offset]) if params[:offset].present?
+  end
+
+  def associated_params
+    params[:associated]
+  end
+
+  def remoted_params
+    params[:remoted]
+  end
+end

data/rails/daylight/params.rb

@@ -0,0 +1,23 @@
+##
+# Mixin to simulate access to params (from Helpers) outside of ActiveController context
+module Daylight::Params
+  extend ActiveSupport::Concern
+
+  class HelperProxy
+    include Daylight::Helpers
+
+    attr_accessor :params
+
+    def initialize params
+      @params = params
+    end
+  end
+
+  included do
+    ##
+    # Creates +params+ method and yields to block, undefine the param method
+    def with_helper params
+      yield HelperProxy.new(params)
+    end
+  end
+end

data/rails/daylight/refiners.rb

@@ -0,0 +1,186 @@
+##
+# Methods in which to refine a query by a model's scopes or attributes
+module Daylight::Refiners
+  extend ActiveSupport::Concern
+
+  module Extension
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      ##
+      # Extends subclasses of ActiveRecord::Base with the Daylight::Refiners features
+      # This hooks into the `inherited` method chain to perform this extension.
+      def inherited active_record
+        active_record.send(:include, Daylight::Refiners)
+        super
+      end
+    end
+  end
+
+  ##
+  # Helper to determine whether a request to use an attribute is valid or invalid
+  # Keeps track of which attributes are part of the request.
+  class AttributeSeive
+    attr_reader :valid_attribute_names, :attribute_names
+
+    ##
+    # Initializes with the valid attributes and requested attributes
+    def initialize valid_attribute_names, attribute_names
+      @valid_attribute_names, @attribute_names = valid_attribute_names, [attribute_names].flatten.compact.map(&:to_s)
+    end
+
+    ##
+    # List of the invalid attributes
+    def invalid_attributes
+      @invalid_attributes ||= attribute_names - (attribute_names & valid_attribute_names)
+    end
+
+    ##
+    # List of the valid attributes
+    def valid_attributes
+      @valid_attributes ||= attribute_names & valid_attribute_names
+    end
+
+    ##
+    # Returns +true+ if there are any invalid attributes
+    #
+    # See:
+    # #invalid_attributes
+    def attributes_valid?
+      invalid_attributes.empty?
+    end
+  end
+
+  ##
+  # Mixin refiners into an +ActiveRecord+ model
+  module ClassMethods
+    include Daylight::Params
+
+    ##
+    # Returns currently registered scopes or empty Array
+    def registered_scopes
+      @registered_scopes ||= []
+    end
+
+    ##
+    # Remember the name of +scopes+ that are defined by the model
+    # This is a method chain and will call ActiveRecord.scope
+    def scope(name, body, &block)
+      registered_scopes << name.to_s
+      super
+    end
+
+    ##
+    # Returns whether the +name+ matches a defined scope
+    def scoped?(name)
+      name.present? && registered_scopes.include?(name.to_s)
+    end
+
+    ##
+    # Calls defined scopes on the model and returns the resulting +ActiveRecord::Relation+.
+    # Raises +ArgumentError+ if the model scope is unknown.
+    def scoped_by *scope_names
+      seive = AttributeSeive.new(registered_scopes, scope_names)
+      raise ArgumentError, "Unknown scope: #{seive.invalid_attributes.join(',')}" unless seive.attributes_valid?
+
+      seive.valid_attributes.inject(all) do |scopes, scope_name|
+        scopes.send(scope_name)
+      end
+    end
+
+    ##
+    # Helper to return the defined reflection names
+    #
+    # See:
+    # filter_by
+    def reflection_names
+      reflections.keys.map(&:to_s)
+    end
+
+    ##
+    # Supplies where conditions and returns the resulting +ActiveRecord::Relation+.
+    # Raises +ArgumentError+ if the keys are not valid attributes on the model.
+    def filter_by params
+      where (params||{}).with_indifferent_access.assert_valid_keys(attribute_names + reflection_names)
+    end
+
+    ##
+    # Wrapper around +order+ to perform key checking to +attribute_names+
+    # Raises +ArgumentError+ if the attribute is unknown.
+    def order_by value
+      keys =
+        case value
+          when String; value.split(',').map {|column| column.strip.split(/\s+/).first }
+          when Hash;   value.keys
+          when Array;  value
+        end
+
+      seive = AttributeSeive.new(self.attribute_names, keys)
+      raise ArgumentError, "Unknown attribute: #{seive.invalid_attributes.join(',')}" unless seive.attributes_valid?
+
+      order(value)
+    end
+
+    def refine_by params
+      with_helper(params) do |helper|
+        self.
+          scoped_by(helper.scoped_params).
+          filter_by(helper.filter_params).
+          order_by(helper.order_params).
+          limit(helper.limit_params).
+          offset(helper.offset_params)
+      end
+    end
+
+    def associated params
+      with_helper(params) do |helper|
+        self.
+          find(params[:id]).
+          associated(helper.associated_params).
+          scoped_by(helper.scoped_params).
+          filter_by(helper.filter_params).
+          order_by(helper.order_params).
+          limit(helper.limit_params).
+          offset(helper.offset_params)
+      end
+    end
+
+    def remoted params
+      with_helper(params) do |helper|
+        self.
+          find(params[:id]).
+          remoted(helper.remoted_params)
+      end
+    end
+
+    def remoted_methods
+      @remoted_methods ||= []
+    end
+
+    def add_remoted(method)
+      if method_defined?(method)
+        remoted_methods.push(method.to_sym).uniq!
+      else
+        Rails.logger.warn "Configured remote method '#{method}' in #{self.name} routes does not exist!"
+      end
+    end
+
+    def remoted?(method)
+      remoted_methods.include? method.to_sym
+    end
+  end
+
+  included do
+    ##
+    # Helper to follow a named association if it exists
+    def associated name
+      raise ArgumentError, "Unknown association: #{name}" unless self.class.reflection_names.include? name.to_s
+      public_send(name)
+    end
+
+    def remoted method
+      raise ArgumentError, "Unknown remote: #{method}" unless self.class.remoted?(method)
+      public_send(method)
+    end
+  end
+end

data/rails/daylight/server.rb

@@ -0,0 +1,29 @@
+# Rails extensions, patches, fixes needed to execute a Daylight::Server
+# In the future, these could be configurable or contributed back
+
+require 'extensions/array_ext'                  # non-destructive version of `extract_options`
+require 'extensions/inflections'                # custom inflections for the ActiveSupport::Inflector
+require 'extensions/autosave_association_fix'   # fix for autosaving `inverse_of` associations
+require 'extensions/has_one_serializer_ext'     # serializer recognizes belong_to :through association
+require 'extensions/nested_attributes_ext'      # associates two previously existing records
+require 'extensions/read_only_attributes'       # serializer support for `read_only` attributes
+require 'extensions/render_json_meta'           # adds metadata to the json response
+require 'extensions/route_options'              # adds associated, remoted options to routes
+require 'extensions/versioned_url_for'          # uses versioned paths for `url_for`
+
+##
+# Include into Rails server to handle Daylight::API queries
+module Daylight
+  extend ActiveSupport::Autoload
+
+  autoload :Helpers
+  autoload :Params
+  autoload :Refiners
+  autoload :APIController
+end
+
+# A convinience alias that will avoids any name collisions
+APIController = Daylight::APIController unless defined?(APIController)
+
+# Hook into ActiveRecord::Base `inherited` chain to extend subclasses
+ActiveRecord::Base.send(:include, Daylight::Refiners::Extension)

data/rails/daylight/tasks.rb

@@ -0,0 +1,37 @@
+require 'rake'
+require 'rails/tasks'
+require 'rdoc/task'
+
+namespace :doc do
+  namespace :api do
+
+    desc 'Pre-generate the API documentation'
+    task generate: %w[environment doc:api:clean] do
+      require 'artifice'
+      require 'open-uri'
+
+      Artifice.activate_with(Rails.application.class)
+
+      Rails.application.eager_load!
+      helpers = Daylight::Documentation.routes.url_helpers
+      models = ActiveRecord::Base.descendants
+      open helpers.index_url(host: 'localhost')
+      models.each do |model|
+        open helpers.model_url(model.name.underscore, host: 'localhost')
+      end
+    end
+
+    desc 'Clear the API documentation'
+    task clean: %w[environment] do
+      helpers = Daylight::Documentation.routes.url_helpers
+      path = helpers.index_path
+
+      # remove the index
+      FileUtils.rm_rf File.join(Rails.root, 'public', path.sub(%r{/$}, '.html'))
+
+      # and the files
+      FileUtils.rm_rf File.join(Rails.root, 'public', path)
+    end
+
+  end
+end

data/rails/extensions/array_ext.rb

@@ -0,0 +1,9 @@
+class Array
+  ##
+  # Return any options without removing them from the Array.
+  # This is a non-destrcutive version of `extract_options!`
+  # Although the name is a misnomer, leaving it for consistency
+  def extract_options
+    last.is_a?(Hash) && last.extractable_options? ? last : {}
+  end
+end

data/rails/extensions/autosave_association_fix.rb

@@ -0,0 +1,49 @@
+##
+# The problem is that autosaving with models that have `inverse_of` and
+# `accepts_nested_attributes_for` causes SystemStackError
+#
+# Solution is to keep track in an instance variable on each instance whether
+# the object has been already autosaved.  On first pass it will determine if
+# it needs saving (original behavior), later passes stop cyclic traversing by
+# always return false.
+#
+# This should be removed when similar behavior is applied to ActiveRecord's
+# `changed_for_autosave?`, likely candidate is 4.1.0 version of the gem.
+#
+# Original problem pulled together by:
+# https://github.com/rails/rails/pull/8549
+#
+# Bug is is documented here:
+# https://github.com/rails/rails/issues/7809
+#
+# Monkey patch supplied here:
+# https://github.com/mtaylor/Rails-Inverse-Nested-Attr-Bug/blob/master/app/patches/rails/active_record/autosave_association.rb
+#
+# See
+# ActiveRecord::Base#changed_for_autosave?
+
+module AutosaveAssociationFix
+  extend ActiveSupport::Concern
+
+  # Returns whether or not this record has been changed in any way (including whether
+  # any of its nested autosave associations are likewise changed)
+  def changed_for_autosave?
+    @_changed_for_autosave_called ||= false
+    if @_changed_for_autosave_called
+      # traversing a cyclic graph of objects; stop it
+      result = false
+    else
+      begin
+        @_changed_for_autosave_called = true
+        result = super
+      ensure
+        @_changed_for_autosave_called = false
+      end
+    end
+    result
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  include AutosaveAssociationFix
+end

data/rails/extensions/has_one_serializer_ext.rb

@@ -0,0 +1,111 @@
+require 'active_model_serializers'
+
+##
+# Allows `:through`	options	to be specified	on has_one associations
+#
+# A `has_one` associations may be specified so that:
+# 1. `belongs_to` which has a foreign_key
+# 2. through another association
+#
+# For example:
+#
+#   class Foo
+#     belongs_to :bar
+#     belongs_to :biz, through: :bar
+#   end
+#
+#  When the serializer is specified:
+#
+#    class FooSerializer
+#      embed :ids
+#
+#      has_one :bar
+#      has_one :biz
+#    end
+#
+# The serializer does not know it doesn't have a direct association to "biz"
+#
+# In this case, the serializer will attempt to put the foreign_key for "biz"
+# in the rendered json.  If the original `Foo` object is saved it will fail
+# because it does not know about this foreign_key.
+#
+# HasOneThrough adds functionality to the serializer to specify through
+# relationships will put "biz" data in an nested attributes hash instead.
+# When used in concert with `accepts_nested_attributes_for`, the data
+# will be passed correctly back to the update methods on `Foo`:
+#
+#    class FooSerializer
+#      embed :ids
+#
+#      has_one :bar
+#      has_one :biz, through: :bar
+#    end
+
+module ActiveModel::Serializer::Associations
+
+  class HasOneThrough < HasOne
+    def embeddable?
+      false
+    end
+
+    def key
+      "#{through}_attributes"
+    end
+
+    def through
+      option :through
+    end
+
+    def through_object
+      @object ||= source_serializer.object.send(through)
+    end
+
+    def attributes
+      source_serializer.node[key] || {}
+    end
+
+    def primary_key
+      through_object.class.primary_key
+    end
+
+    def serialize
+      return unless associated_object
+
+      serialize_ids.merge({
+        :"#{@name}_attributes" => find_serializable(associated_object).serializable_hash
+      })
+    end
+
+    def serialize_ids
+      return unless associated_object
+
+      attributes.merge({
+        :"#{primary_key}" => through_object.send(primary_key),
+        :"#{@name}_id"    => associated_object.read_attribute_for_serialization(embed_key)
+      })
+    end
+  end
+end
+
+module HasOneSerializerExt
+  extend ActiveSupport::Concern
+
+  included do
+    attr_reader :node
+
+    def self.has_one(*attrs)
+      klass = if attrs.extract_options[:through]
+          ActiveModel::Serializer::Associations::HasOneThrough
+        else
+          ActiveModel::Serializer::Associations::HasOne
+        end
+
+      associate(klass, attrs)
+    end
+  end
+end
+
+# Add the HasOneSerializerExt to the Serializer
+ActiveModel::Serializer.class_eval do
+  include HasOneSerializerExt
+end

data/rails/extensions/inflections.rb

@@ -0,0 +1,6 @@
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.uncountable 'anonymous'
+
+  inflect.acronym 'API'
+  inflect.acronym 'APIs'
+end

data/rails/extensions/nested_attributes_ext.rb

@@ -0,0 +1,94 @@
+##
+# Problem:  Nested attributes will will fail to associate two records if they both already exist
+# Solution: Associate the existing records defined by 'id' attributes before updating them
+#
+# Idea abstracted from implementation detailed by:
+# https://stackoverflow.com/questions/6346134/use-rails-nested-model-to-create-outer-object-and-simultaneously-edit-existi/12064875#12064875
+module NestedAttributesExt
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :nested_resource_names
+    self.nested_resource_names = [].freeze
+
+    ##
+    # Associate any existing records that may be missing before running any updates on them.
+    #
+    # See:
+    # ActiveRecord::NestedAttributes#assign_nested_attributes_for_collection_association
+    def assign_nested_attributes_for_collection_association association_name, attributes_collection
+      return if attributes_collection.nil?
+
+      associate_existing_records(association_name, attributes_collection)
+
+      super
+    end
+
+    ##
+    # Ignore any association with nil attributes
+    #
+    # See:
+    # ActiveRecord::NestedAttributes#assign_nested_attributes_for_one_to_one_association
+    def assign_nested_attributes_for_one_to_one_association(association_name, attributes)
+      return if attributes.nil?
+
+      super
+    end
+  end
+
+  module ClassMethods
+    ##
+    # Saves off the reflection names that the nested attributes are accepted for.
+    # Does not alter original behavoir or arguments.
+    #
+    # See:
+    # ActiveRecord::NestedAttributes#accepts_nested_attributes_for
+    def accepts_nested_attributes_for *attr_names
+      nested_resources = attr_names.dup
+      nested_resources.extract_options!
+      self.nested_resource_names = nested_resources.map(&:to_sym).freeze
+
+      super
+    end
+  end
+
+
+  private
+    ##
+    # Determines unassociated records from existing records on the association and adds them
+    def associate_existing_records(association_name, attributes_collection)
+
+      # determine existing records, bail if there are none specified by 'id'
+      attribute_ids = attributes_collection.map {|a| (a['id'] || a[:id]) }.compact
+      return if attribute_ids.empty?
+
+      association = association(association_name)
+      primary_key = association.klass.primary_key.to_sym
+
+      # get known existing ids on the association
+      existing_record_ids = if association.loaded?
+          association.target.map(&primary_key)
+        else
+          association.scope.where(primary_key => attribute_ids).pluck(primary_key)
+        end
+
+      # unassociated records are those that are not part of existing in the association
+      unassociated_record_ids = attribute_ids.map(&:to_s) - existing_record_ids.map(&:to_s)
+
+      # we are about to set all foreign_keys, remove any foreign_key references in
+      # unassigned records attributes so they don't get clobbered
+      attributes_collection.map do |a|
+        if unassociated_record_ids.include?((a['id'] || a[:id]).to_s)
+          key = association.reflection.foreign_key
+          a.delete(key) || a.delete(key.to_sym)
+        end
+      end
+
+      # concat the unassociated records to the association
+      association.concat(association.klass.find(unassociated_record_ids))
+    end
+end
+
+ActiveRecord::Base.class_eval do
+  include NestedAttributesExt
+end

data/rails/extensions/read_only_attributes.rb

@@ -0,0 +1,35 @@
+module ReadOnlyAttributes
+  extend ActiveSupport::Concern
+
+  included do
+    # place the read_only attributes along side the other class_attributes for a Serializer
+    class << self
+      class_attribute :_read_only
+      self._read_only = []
+    end
+  end
+
+  module ClassMethods
+    ##
+    # Records the attribues as read only then stores them as attributes
+    #
+    # See
+    # ActiveModel::Serializer.attributes
+    def read_only(*attrs)
+      # strip predicate '?' marks of and convert them to symbols
+      normalized_attrs = attrs.map { |a| a.to_s.gsub(/\?$/,'').to_sym }
+
+      # record which attributes will be read only
+      self._read_only = _read_only.dup
+      self._read_only.push(*normalized_attrs).uniq
+
+      # pass them off to attributes to do all the work
+      attributes(*attrs)
+    end
+  end
+end
+
+# Add the ReadOnlyAttributes to the Serializer
+ActiveModel::Serializer.class_eval do
+  include ReadOnlyAttributes
+end