moonrope 1.4.1 → 2.0.0

data/lib/moonrope/dsl/structure_dsl.rb

@@ -1,3 +1,5 @@
+require 'moonrope/structure_attribute'
+
 module Moonrope
   module DSL
     class StructureDSL
@@ -26,6 +28,10 @@ module Moonrope
         @conditions = []
       end
 
+      def no_doc!
+        @structure.doc = false
+      end
+
       def scope(options = {}, &block)
         scope_dsl = self.class.new(@structure)
         scope_dsl.options = options
@@ -35,12 +41,21 @@ module Moonrope
       def group(name, &block)
         scope_dsl = self.class.new(@structure)
         scope_dsl.groups = [@groups, name].flatten
+        scope_dsl.conditions = @conditions
         scope_dsl.instance_eval(&block)
       end
 
-      def condition(condition, &block)
+      def condition(condition, description = nil, &block)
         scope_dsl = self.class.new(@structure)
+        if condition.is_a?(Hash) && condition.size == 1
+          condition = {:authenticator => condition.first[0], :access_rule => condition.first[1]}
+        elsif condition.is_a?(Symbol)
+          condition = {:authenticator => :default, :access_rule => condition}
+        else
+          condition = {:block => condition, :description => description}
+        end
         scope_dsl.conditions = [@conditions, condition].flatten
+        scope_dsl.groups = @groups
         scope_dsl.instance_eval(&block)
       end
 
@@ -61,6 +76,7 @@ module Moonrope
         attribute.source_attribute  = options[:source_attribute]
         attribute.value             = options[:value]
         attribute.example           = options[:eg] || options[:example]
+        attribute.doc               = options[:doc]
         attribute.groups            = @groups
         attribute.conditions        = @conditions
         @structure.attributes[type] << attribute
@@ -84,7 +100,16 @@ module Moonrope
 
       def expansion(name, *args, &block)
         if block_given?
-          @structure.expansions[name] = {:block => block, :conditions => @conditions}
+          if args[0].is_a?(String)
+            attrs = args[1] || {}
+            attrs[:description] = args[0]
+          elsif args[0].is_a?(Hash)
+            attrs = atrs[0]
+          else
+            attrs = {}
+          end
+
+          @structure.expansions[name] = attrs.merge({:block => block, :conditions => @conditions})
         else
           attribute(:expansion, name, *args)
         end

data/lib/moonrope/errors.rb

@@ -5,6 +5,9 @@ module Moonrope
     end
 
     class HelperAlreadyDefined < Error; end
+    class MissingAuthenticator < Error; end
+    class MissingAccessRule < Error; end
+    class InvalidSharedAction < Error; end
 
     class RequestError < Error
       attr_reader :options

data/lib/moonrope/eval_environment.rb

@@ -1,7 +1,11 @@
+require 'moonrope/eval_helpers'
+require 'moonrope/eval_helpers/filter_helper'
+
 module Moonrope
   class EvalEnvironment
 
     include Moonrope::EvalHelpers
+    include Moonrope::EvalHelpers::FilterHelper
 
     # @return [Moonrope::Base] the base object
     attr_reader :base
@@ -28,9 +32,10 @@ module Moonrope
     # @param request [Moonrope::Request]
     # @param accessors [Hash] additional variables which can be made available
     #
-    def initialize(base, request, accessors = {})
+    def initialize(base, request, action = nil, accessors = {})
       @base = base
       @request = request
+      @action = action
       @accessors = accessors
       @default_params = {}
       reset
@@ -46,8 +51,8 @@ module Moonrope
     #
     # @return [Object] the authenticated object
     #
-    def auth
-      request ? request.authenticated_user : nil
+    def identity
+      request ? request.identity : nil
     end
 
     #
@@ -143,6 +148,54 @@ module Moonrope
         raise Moonrope::Errors::Error, "No structure found named '#{structure_name}'"
       end
 
+      if options.delete(:return)
+        if options.empty? && action && action.returns && action.returns[:structure_opts].is_a?(Hash)
+          options = action.returns[:structure_opts]
+        end
+      end
+
+      if request
+        if options[:paramable]
+          if options[:paramable].is_a?(Hash)
+            options[:expansions] = options[:paramable][:expansions]
+            options[:full] = options[:paramable][:full]
+          end
+
+          if options[:paramable] == true || options[:paramable].is_a?(Hash) && options[:paramable].has_key?(:expansions)
+            if request.params["_expansions"].is_a?(Array)
+              options[:expansions] = request.params["_expansions"].map(&:to_sym)
+              if options[:paramable].is_a?(Hash) && options[:paramable][:expansions].is_a?(Array)
+                whitelist = options[:paramable][:expansions]
+                options[:expansions].reject! { |e| !whitelist.include?(e) }
+              end
+            end
+
+            if request.params["_expansions"] == true
+              if options[:paramable].is_a?(Hash)
+                if options[:paramable][:expansions].is_a?(Array)
+                  options[:expansions] = options[:paramable][:expansions]
+                elsif options[:paramable].has_key?(:expansions)
+                  options[:expansions] = true
+                end
+              else
+                options[:expansions] = true
+              end
+            end
+
+            if request.params["_expansions"] == false
+              options[:expansions] = nil
+            end
+
+          end
+
+          if request.params.has?("_full")
+            if options[:paramable] == true || (options[:paramable].is_a?(Hash) && options[:paramable].has_key?(:full))
+              options[:full] = !!request.params["_full"]
+            end
+          end
+        end
+      end
+
       structure.hash(object, options.merge(:request => @request))
     end
 
@@ -169,5 +222,31 @@ module Moonrope
       self.structure_for(structure_name).is_a?(Moonrope::Structure)
     end
 
+    #
+    # Copy the list of parameters onto the given objectr
+    #
+    def copy_params_to(object, *params_to_copy)
+      if params_to_copy.first.is_a?(Hash)
+        options = params_to_copy.shift
+        if options[:from]
+          all_params = action.params.select { |_,p| p[:from_shared_action].include?(options[:from]) }
+          params_to_copy = params_to_copy + all_params.keys
+        end
+      end
+      params_to_copy.each do |param_name|
+        if param_definition = action.params[param_name]
+          if params.has?(param_name)
+            if param_definition[:apply]
+              instance_exec(object, params[param_name], &param_definition[:apply])
+            elsif object.respond_to?("#{param_name}=")
+              object.send("#{param_name}=", params[param_name])
+            end
+          end
+        else
+          raise Moonrope::Errors::Error, "Attempted to copy parameter #{parameter} to object but no definition exists"
+        end
+      end
+    end
+
   end
 end

data/lib/moonrope/eval_helpers/filter_helper.rb

@@ -0,0 +1,82 @@
+module Moonrope
+  module EvalHelpers
+    module FilterHelper
+
+      #
+      # Return information which has been passed through the filterable filters
+      #
+      def filter(collection, &block)
+        filters_flags = {}
+        if params.filters.is_a?(Hash)
+          params.filters.each do |key, value|
+            options = {}
+            if filter = action.filters[key.to_sym]
+              if value.is_a?(Hash)
+                options[:operator] = value['operator'] ? value['operator'].to_sym : filter[:operators].first
+                options[:value] = value['value']
+              else
+                # If no hash is provided, we'll always attempt to use the first operator
+                # for the filter.
+                options[:operator] = filter[:operators].first
+                options[:value] = value
+              end
+
+              # Check that the operator is supported
+              unless filter[:operators].include?(options[:operator])
+                error 'FilterError', :issue_code => 'InvalidOperator', :issue_message => "The operator '#{options[:operator]}' is not supported for the '#{key}' attribute."
+              end
+
+              # Add this item to the flags which will be set at the end of the method
+              filters_flags[key] = options
+
+              # Do the filtering...
+              if filter[:block]
+                # If a block is provided, we'll refer to that to do the lookups
+                # and ensure that return the collection
+                collection = instance_exec(options[:operator], options[:value], collection, &filter[:block])
+              else
+                # If no block is provided, we'll fall back to Active Record like where
+                # lookups on the original collection.
+                case options[:operator]
+                when :eq
+                  collection = collection.where("#{key} = ?", options[:value].to_s)
+                when :not_eq
+                  collection = collection.where("#{key} != ?", options[:value].to_s)
+                when :starts_with
+                  collection = collection.where("#{key} LIKE ?", "#{options[:value].to_s}%")
+                when :ends_with
+                  collection = collection.where("#{key} LIKE ?", "%#{options[:value].to_s}")
+                when :gt
+                  collection = collection.where("#{key} > ?", options[:value].to_s)
+                when :gte
+                  collection = collection.where("#{key} >= ?", options[:value].to_s)
+                when :lt
+                  collection = collection.where("#{key} < ?", options[:value].to_s)
+                when :lte
+                  collection = collection.where("#{key} <= ?", options[:value].to_s)
+                when :in, :not_in
+                  # For checking with arrays, we must make sure the user has sent us
+                  # an array otherwise we'll raise an error.
+                  unless options[:value].is_a?(Array)
+                    error 'FilterError', :issue_code => "ArrayNeeded", :issue_message => "An array value is needed for '#{key}' for in/not_in operator"
+                  end
+                  values = options[:value].map(&:to_s)
+                  collection = options[:operator] == :in ? collection.where(key => values) : collection.where.not(key => values)
+                else
+                  error 'FilterError', :issue_code => "UnsupportedOperator", :issue_message => "The operator '#{options[:operator]}' is not supported."
+                end
+              end
+            else
+              # Raise an error if the attribute has been provided by the consumer
+              # that isn't supported by the action.
+              error 'FilterError', :issue_code => "UnsupportedAttribute", :issue_message => "The '#{key}' attribute is not supported for filtering on this action."
+            end
+          end
+        end
+        set_flag :filters, filters_flags
+        instance_exec(collection, &block)
+      end
+
+    end
+  end
+end

data/lib/moonrope/eval_helpers.rb

@@ -7,7 +7,7 @@ module Moonrope
     # @param type [Symbol] the type of error to raise
     # @param message [String, Hash or Array] options to pass with the error (usually a message)
     #
-    def error(type, code_or_message, message = nil)
+    def error(type, code_or_message = nil, message = nil)
       case type
       when :not_found           then raise(Moonrope::Errors::NotFound, code_or_message)
       when :access_denied       then raise(Moonrope::Errors::AccessDenied, code_or_message)
@@ -16,7 +16,11 @@ module Moonrope
       when :structured_error    then structured_error(code_or_message, message)
       else
         if type.is_a?(String)
-          structured_error(type, code_or_message, message.is_a?(Hash) ? message : {})
+          if code_or_message.is_a?(Hash)
+            structured_error(type, nil, code_or_message)
+          else
+            structured_error(type, code_or_message, message.is_a?(Hash) ? message : {})
+          end
         else
           raise Moonrope::Errors::RequestError, code_or_message
         end
@@ -31,7 +35,17 @@ module Moonrope
     # @param additional [Hash] additional data to return with the error
     #
     def structured_error(code, message, additional = {})
-      raise Moonrope::Errors::StructuredError, additional.merge(:code => code, :message => message)
+      if action
+        if action.authenticator_to_use.is_a?(Moonrope::Authenticator)
+          errors = action.authenticator_to_use.errors.merge(action.errors)
+        else
+          errors = action.errors
+        end
+        if error = errors[code]
+          message = error[:description].gsub(/\{(\w+)\}/) { additional[$1.to_sym] }
+        end
+      end
+      raise Moonrope::Errors::StructuredError, {:code => code, :message => message}.merge(additional)
     end
 
     #
@@ -40,12 +54,21 @@ module Moonrope
     def paginate(collection, max_per_page = 60, &block)
       per_page = params.per_page || 30
       per_page = max_per_page if per_page < 1 || per_page > max_per_page
-      paginated_results = collection.page(params.page).per(per_page)
-      set_flag :paginated, {:page => params.page, :per_page => per_page, :total_pages => paginated_results.total_pages, :total_records => paginated_results.total_count}
+      paginated_results = collection.page(params.page || 1).per(per_page)
+      set_flag :paginated, {:page => params.page || 1, :per_page => per_page, :total_pages => paginated_results.total_pages, :total_records => paginated_results.total_count}
       paginated_results.to_a.map do |result|
         block.call(result)
       end
     end
 
+    #
+    # Return information sorted by appropriate values from parameters
+    #
+    def sort(collection, &block)
+      collection = collection.order(params.sort_by => params.order)
+      set_flag :sorted, {:by => params.sort_by, :order => params.order}
+      block.call(collection)
+    end
+
   end
 end

data/lib/moonrope/guard.rb

@@ -0,0 +1,35 @@
+module ::Guard
+  class Moonrope < Plugin
+    def initialize(options)
+      super
+      @options = options
+      @options[:source] ||= "api"
+      @options[:destination] ||= ".apidoc"
+    end
+
+    def start
+      UI.info "Starting Moonrope Watching"
+    end
+
+    def reload
+      stop ; start
+    end
+
+    def run_all
+      generate_moonrope_docs
+    end
+
+    def run_on_modifications(paths)
+      generate_moonrope_docs
+    end
+
+    private
+
+    def generate_moonrope_docs
+      if File.exist?(File.join(@options[:destination], 'moonrope.txt'))
+        system("rm -Rf #{@options[:destination]}/*")
+      end
+      system("bundle exec moonrope #{@options[:source]} #{@options[:destination]}")
+    end
+  end
+end

data/lib/moonrope/html_generator.rb

@@ -0,0 +1,65 @@
+require 'erb'
+require 'fileutils'
+require 'moonrope/doc_context'
+
+module Moonrope
+  class HtmlGenerator
+
+    def initialize(base, template_root_path)
+      @base = base
+      @template_root_path = template_root_path
+    end
+
+    attr_reader :base
+    attr_reader :template_root_path
+
+    def host
+      ENV['MR_HOST']
+    end
+
+    def prefix
+      ENV['MR_PREFIX'] || 'api'
+    end
+
+    def version
+      ENV['MR_VERSION'] || 'v1'
+    end
+
+    def generate(output_path)
+      FileUtils.mkdir_p(output_path)
+      FileUtils.cp_r(File.join(@template_root_path, 'assets'), File.join(output_path, 'assets'))
+      FileUtils.touch(File.join(output_path, 'moonrope.txt'))
+      # Index
+      generate_file(output_path, "index.html", "index")
+      # Controllers
+      @base.controllers.select { |c| c.doc != false }.each do |controller|
+        generate_file(output_path, File.join("controllers", "#{controller.name}.html"), "controller", {:controller => controller})
+        controller.actions.select { |_,a| a.doc != false }.each do |_, action|
+          generate_file(output_path, File.join("controllers", controller.name.to_s, "#{action.name}.html"), "action", {:controller => controller, :action => action})
+        end
+      end
+      # Structures
+      @base.structures.select { |s| s.doc != false }.each do |structure|
+        generate_file(output_path, File.join("structures", "#{structure.name}.html"), "structure", {:structure => structure})
+      end
+      # Authenticators
+      @base.authenticators.values.select { |s| s.doc != false }.each do |authenticator|
+        generate_file(output_path, File.join("authenticators", "#{authenticator.name}.html"), "authenticator", {:authenticator => authenticator})
+      end
+
+    end
+
+    private
+
+    def generate_file(root_dir, output_file, template_file, variables = {})
+      file = DocContext.new(self, :html_extensions => true, :welcome_file => 'index', :output_file => output_file, :vars => variables)
+      file_string = file.render(File.join(@template_root_path, "#{template_file}.erb"))
+      layout = DocContext.new(self, :html_extensions => true, :welcome_file => 'index', :output_file => output_file, :vars => {:page_title => file.vars[:page_title], :active_nav =>file.vars[:active_nav], :body => file_string}).render(File.join(@template_root_path, "layout.erb"))
+      path = File.join(root_dir, output_file)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, 'w') { |f| f.write(layout) }
+    end
+
+  end
+
+end

data/lib/moonrope/param_set.rb

@@ -29,7 +29,7 @@ module Moonrope
     #
     def _value_for(key)
       # Get the value from the params and defaults
-      value = (@params[key.to_s] || @defaults[key.to_s])
+      value = @params.has_key?(key.to_s) ? @params[key.to_s] : @defaults[key.to_s]
       # Ensure that empty strings are actually nil.
       value = nil if value.is_a?(String) && value.length == 0
       # Return the value
@@ -39,6 +39,16 @@ module Moonrope
     alias_method :[], :_value_for
     alias_method :method_missing, :_value_for
 
+    #
+    # Set the value for a given param
+    #
+    # @param key [String]
+    # @param value [AnyObject]
+    #
+    def _set_value(name, value)
+      @params[name.to_s] = value
+    end
+
     #
     # Set the defaults for the param set
     #

data/lib/moonrope/rack_middleware.rb

@@ -79,7 +79,7 @@ module Moonrope
           result = request.execute
           json = result.to_json
           global_headers['Content-Length'] = json.bytesize.to_s
-          [200, global_headers.merge(result.headers), [result.to_json]]
+          [200, global_headers.merge(result.headers), [json]]
         rescue JSON::ParserError => e
           [400, global_headers, [{:status => 'invalid-json', :details => e.message}.to_json]]
         rescue => e

data/lib/moonrope/railtie.rb

@@ -1,19 +1,21 @@
+require 'moonrope/doc_server'
+
 module Moonrope
   class Railtie < Rails::Railtie
 
     initializer 'moonrope.initialize' do |app|
 
       # Initialize a new moonrope base.
-      app.config.moonrope = Moonrope::Base.load(Rails.root.join('api'))
+      Moonrope::Base.instance = Moonrope::Base.load(Rails.root.join('api'))
 
       # Set the logger
       Moonrope.logger = Rails.logger
 
       # Set the environment to match the Rails environment
-      app.config.moonrope.environment = Rails.env.to_s
+      Moonrope::Base.instance.environment = Rails.env.to_s
 
       # Ensure all request use UTC
-      app.config.moonrope.on_request = Proc.new do |base, env|
+      Moonrope::Base.instance.on_request = Proc.new do |base, env|
         Time.zone = 'UTC'
       end
 
@@ -22,29 +24,44 @@ module Moonrope
         Moonrope::Request.path_regex = app.config.moonrope_request_path_regex
       end
 
-      # Catch ActiveRecord::RecordNotFound exception as a standard not-found error
-      if defined?(ActiveRecord)
-        app.config.moonrope.register_external_error ActiveRecord::RecordNotFound do |exception, result|
+      ActiveSupport.on_load(:active_record) do
+
+        # Catch ActiveRecord::RecordNotFound exception as a standard not-found error
+        Moonrope::Base.instance.register_external_error ActiveRecord::RecordNotFound do |exception, result|
           result.status = 'not-found'
           result.data = {:message => exception.message}
         end
 
-        # Add a helper for auto setting parameters
-        app.config.moonrope.dsl.instance_eval do
-          helper :auto_set_params_for, :unloadable => false do |object|
-            current_action = object.new_record? ? :create_only : :update_only
-            request.action.params.select { |k,v| v[:set] == true || v[:set] == current_action }.keys.each do |param|
-              object.send("#{param}=", params[param])  if params.has?(param)
-            end
+        # Catch ActiveRecord::DeleteRestrictionError and raise an a DeleteRestrictionError
+        Moonrope::Base.instance.register_external_error ActiveRecord::DeleteRestrictionError do |exception, result|
+          result.status = 'error'
+          result.data = {:code => "DeleteRestrictionError", :message => "Object could not be deleted due to dependency"}
+          if exception.message =~ /([\w\-]+)\z/
+            result.data[:dependency] = $1
           end
         end
+
+        # Catch ActiveRecord::RecordInvalid and raise an a ValidationError
+        Moonrope::Base.instance.register_external_error ActiveRecord::RecordInvalid do |exception, result|
+          result.status = 'error'
+          errors = exception.record.errors.respond_to?(:to_api_hash) ? exception.record.errors.to_api_hash : exception.record.errors
+          result.data = {:code => "ValidationError", :message => "Object could not be saved due to a validation error", :errors => errors}
+        end
+
       end
 
+      # Insert the documentation middleware
+      app.middleware.use(
+        Moonrope::DocServer,
+        Moonrope::Base.instance,
+        :reload_on_each_request => !app.config.cache_classes
+      )
+
       # Insert the Moonrope middleware into the application's middleware
       # stack (at the bottom).
       app.middleware.use(
         Moonrope::RackMiddleware,
-        app.config.moonrope,
+        Moonrope::Base.instance,
         :reload_on_each_request => !app.config.cache_classes
       )
 

data/lib/moonrope/request.rb

@@ -3,10 +3,16 @@ module Moonrope
 
     class << self
       attr_accessor :path_regex
+      attr_accessor :path_prefix
 
       # @return [Regex] the regex which should be matched for all API requests
       def path_regex
-        @path_regex ||= /\A\/api\/([\w\/\-\.]+)?/
+        @path_regex ||= /\A\/#{path_prefix}([\w\/\-\.]+)?/
+      end
+
+      # @return [Regex] the initial path of the prefix to be matched
+      def path_prefix
+        @path_prefix ||= /api\//
       end
     end
 
@@ -17,7 +23,7 @@ module Moonrope
     # @return [String] the name of the action which was requested
     attr_reader :action_name
     # @return [Object] the authenticated user
-    attr_reader :authenticated_user
+    attr_reader :identity
 
     #
     # Initialize a new Moonrope::Request
@@ -80,25 +86,30 @@ module Moonrope
     # @return [Moonrope::ActionResult]
     #
     def execute
-      eval_env = EvalEnvironment.new(@base, self)
-      if @base.authenticator
+      eval_env = EvalEnvironment.new(@base, self, action)
+
+      if action.authenticator_to_use.is_a?(Moonrope::Authenticator)
         result = action.convert_errors_to_action_result do
-          @authenticated_user = eval_env.instance_eval(&@base.authenticator)
-          # If we are authenticated, check whether the action permits access to
-          # this user, if not raise an error.
-          if authenticated?
-            unless action.check_access(eval_env) == true
-              raise Moonrope::Errors::AccessDenied, "Access to #{controller.name}/#{action.name} is not permitted."
+          if block = action.authenticator_to_use.lookup
+            @identity = eval_env.instance_eval(&block)
+          end
+
+          unless action.check_access(eval_env) == true
+            if rule = action.authenticator_to_use.rules[action.access_rule_to_use]
+              eval_env.structured_error(rule[:error_code], rule[:description], :action => action.name, :controller => controller.name)
+            else
+              eval_env.structured_error("NotPermitted", "You are not permitted to access #{controller.name}/#{action.name}", :action => action.name, :controller => controller.name)
             end
           end
         end
 
         if result.is_a?(Moonrope::ActionResult)
-          # If we already have a result, we should return it and no longer execute
-          # this request.
           return result
         end
+      elsif action.authenticator_to_use == :not_found
+        raise Moonrope::Errors::MissingAuthenticator, "Wanted to use authenticator that was not defined."
       end
+
       action.execute(eval_env)
     end
 
@@ -132,7 +143,7 @@ module Moonrope
     # @return [Boolean]
     #
     def anonymous?
-      authenticated_user.nil?
+      identity.nil?
     end
 
     #
@@ -141,7 +152,7 @@ module Moonrope
     # @return [Boolean]
     #
     def authenticated?
-      !(authenticated_user.nil? || authenticated_user == false)
+      !(identity.nil? || identity == false)
     end
 
     #