moonrope 1.4.1 → 2.0.0

data/lib/moonrope/controller.rb

@@ -1,7 +1,9 @@
+require 'moonrope/dsl/controller_dsl'
+
 module Moonrope
   class Controller
 
-    attr_accessor :name, :actions, :access, :befores
+    attr_accessor :name, :actions, :befores, :friendly_name, :description, :doc, :authenticator, :access_rule, :shared_actions
     attr_reader :base, :dsl
 
     #
@@ -15,7 +17,7 @@ module Moonrope
       @base = base
       @name = name
       @actions = {}
-      @access = nil
+      @shared_actions = {}
       @befores = []
       @dsl = Moonrope::DSL::ControllerDSL.new(self)
       @dsl.instance_eval(&block) if block_given?

data/lib/moonrope/doc_context.rb

@@ -0,0 +1,94 @@
+module Moonrope
+  class DocContext
+
+    attr_reader :vars
+
+    def initialize(generator, options = {})
+      @generator = generator
+      @vars = options.delete(:vars) || {}
+      @options = options
+    end
+
+    def set_page_title(title)
+      @vars[:page_title] = title
+    end
+
+    def set_active_nav(nav)
+      @vars[:active_nav] = nav
+    end
+
+    def base
+      @generator.base
+    end
+
+    def host
+      @generator.host
+    end
+
+    def prefix
+      @generator.prefix
+    end
+
+    def version
+      @generator.version
+    end
+
+    def method_missing(name)
+      if @vars.has_key?(name.to_sym)
+        @vars[name.to_sym]
+      else
+        super
+      end
+    end
+
+    def git_version
+      ENV["VDT_VERSION"] ||
+      (`git rev-parse HEAD`.strip rescue nil)
+    end
+
+    def asset_path(file)
+      path("assets/" + file)
+    end
+
+    def full_prefix
+      "#{host}/#{prefix}/#{version}"
+    end
+
+    def path(file)
+      depth = ((@options[:output_file] || '').split('/').size - 1).times.map { "../" }.join
+      if file == :root
+        file = depth + (@options[:welcome_file] || "welcome")
+      else
+        file = depth + file
+      end
+
+      if @options[:html_extensions] && !(file =~ /\.[a-z]+\z/)
+        file = "#{file}.html"
+      end
+
+      file
+    end
+
+    def render(template_file)
+      ERB.new(File.read(template_file), nil, '-').result(binding)
+    end
+
+    def partial(name, attributes = {})
+      erb = self.class.new(@generator, @options.merge(:vars => attributes))
+      erb.render(File.join(@generator.template_root_path, "_#{name}.erb"))
+    end
+
+    def friendly_type(type)
+      if type.is_a?(Symbol)
+        type.to_s.capitalize
+      else
+        type.to_s
+      end
+    end
+
+    def humanize(string)
+      string.to_s.gsub(/\_/, ' ')
+    end
+
+  end
+end

data/lib/moonrope/doc_server.rb

@@ -0,0 +1,123 @@
+require 'moonrope/doc_context'
+
+module Moonrope
+  class DocServer
+
+    CONTENT_TYPES = {
+      'css' => 'text/css',
+      'js' => 'text/javascript',
+      'svg' => 'image/svg+xml'
+    }
+
+    class << self
+      #
+      # Set the default path regex which should be matched for requests for
+      # API docmentation. By default, this is /api/docs/.
+      #
+      def path_regex
+        @path_regex ||= /\A\/#{Moonrope::Request.path_prefix}docs\/([\w\.]+)\/?([\w\/\-\.]+)?/
+      end
+      attr_writer :path_regex
+    end
+
+    def initialize(app, base, options = {})
+      @app = app
+      @base = base
+      @options = options
+    end
+
+    attr_reader :base
+
+    class Generator
+      def initialize(base, options = {})
+        @base = base
+        @options = options
+      end
+
+      attr_reader :base
+
+      def template_root_path
+        File.expand_path("../../../templates/basic", __FILE__)
+      end
+
+      def host
+        @options[:host]
+      end
+
+      def prefix
+        @options[:prefix]
+      end
+
+      def version
+        @options[:version]
+      end
+
+      def generate_file(output_file, template_file, variables = {})
+        # Generate the page for the requested template with the given variables
+        file = DocContext.new(self, :output_file => output_file, :vars => variables)
+        file_string = file.render(File.join(template_root_path, "#{template_file}.erb"))
+        # Generate the final page within the layout
+        DocContext.new(self, :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"))
+      end
+    end
+
+    def call(env)
+      if env['PATH_INFO'] =~ self.class.path_regex
+        version = $1
+        doc_path = $2
+        request = Rack::Request.new(env)
+        generator = Generator.new(@base, :host => "#{request.scheme}://#{request.host_with_port}", :version => version, :prefix => env['PATH_INFO'].split('/')[1])
+
+        if @options[:reload_on_each_request]
+          @base.load
+        end
+
+        file = nil
+        content_type = nil
+
+        case doc_path
+        when nil, ""
+          return [302, {'Location' => "#{env['PATH_INFO']}/welcome"}, ['']]
+        when /\Awelcome\z/, /\Aindex\.html\z/
+          file = generator.generate_file(doc_path, 'index')
+        when /\Acontrollers\/(\w+)(\.html)?\z/
+          if controller = @base.controller($1.to_sym)
+            file = generator.generate_file(doc_path, 'controller', :controller => controller)
+          end
+        when /\Acontrollers\/(\w+)\/(\w+)(\.html)?\z/
+          if controller = @base.controller($1.to_sym)
+            if action = controller.action($2.to_sym)
+              file = generator.generate_file(doc_path, 'action', :controller => controller, :action => action)
+            end
+          end
+        when /\Astructures\/(\w+)(\.html)?\z/
+          if structure = @base.structure($1.to_sym)
+            file = generator.generate_file(doc_path, 'structure', :structure => structure)
+          end
+        when /\Aauthenticators\/(\w+)(\.html)?\z/
+          if authenticator = @base.authenticators[$1.to_sym]
+            file = generator.generate_file(doc_path, 'authenticator', :authenticator => authenticator)
+          end
+        when /\Aassets\/([\w]+)\.([a-z]+)\z/
+          path = File.join(generator.template_root_path, 'assets', "#{$1}.#{$2}")
+          if File.exist?(path)
+            file = File.read(path)
+            content_type = CONTENT_TYPES[$2] || 'text/plain'
+          end
+        end
+
+        if file
+          [200, {
+            'Content-Type' => content_type || 'text/html',
+            'Content-Length' => file.bytesize.to_s},
+          [file]]
+        else
+          [404, {}, ['Not found']]
+        end
+      else
+        return @app.call(env)
+      end
+    end
+
+  end
+end

data/lib/moonrope/dsl/action_dsl.rb

@@ -1,3 +1,6 @@
+require 'moonrope/errors'
+require 'moonrope/dsl/filterable_dsl'
+
 module Moonrope
   module DSL
     class ActionDSL
@@ -11,6 +14,18 @@ module Moonrope
         @action = action
       end
 
+      #
+      # Set the title for the action
+      #
+      #   title "List all users"
+      #
+      # @param value [String]
+      # @return [void]
+      #
+      def title(value)
+        @action.title = value
+      end
+
       #
       # Set the description for the action
       #
@@ -23,6 +38,14 @@ module Moonrope
         @action.description = value
       end
 
+
+      #
+      # Set this action so that it isn't documented
+      #
+      def no_doc!
+        @action.doc = false
+      end
+
       #
       # Add a new param to the action's param set.
       #
@@ -33,27 +56,94 @@ module Moonrope
       # @param options_if_description [Hash] a hash of additional options if a description was provided
       # @return [void]
       #
-      def param(name, description_or_options = {}, options_if_description = {})
+      def param(name, description_or_options = {}, options_if_description = {}, &block)
         if description_or_options.is_a?(String)
           options = options_if_description.merge(:description => description_or_options)
         else
           options = description_or_options
         end
+
+        options[:from_structure] ||= @from_structure if @from_structure
+
+        if structure = options[:from_structure]
+          if @action.controller && structure = @action.controller.base.structure(structure)
+            if attribute = structure.attribute(name)
+              options[:description] ||= attribute.description
+              options[:type] ||= attribute.value_type
+            end
+          end
+        end
+
+        options[:apply] = block if block_given?
+        options[:from_shared_action] = @within_shared_action.dup if @within_shared_action
         @action.params[name] = options
       end
 
       #
-      # Set the access condition for the action.
+      # Specifies that all params within this block should be marked as being from
+      # a given structure
       #
-      #   access do
-      #     auth.is_a?(User)
-      #   end
+      #    from_structure :user do
+      #      param :username
+      #    end
+      #
+      # @param name [Symbol] the name of the structure
       #
-      # @yield the contents of the yield will be saved as the access condition
+      def from_structure(name, &block)
+        @from_structure = name
+        self.instance_eval(&block)
+      ensure
+        @from_structure = nil
+      end
+
+      #
+      # Add a new error to the actions' errors
+      #
+      #   error "NoUnitFound", "The unit with given {{id}} could not be found"
+      #
+      # @param name [String] the name of the error
+      # @param description [String] a description of the error
       # @return [void]
       #
-      def access(value = nil, &block)
-        @action.access = block_given? ? block : value
+      def error(name, description, options = {})
+        @action.errors[name] = options.merge(:description => description, :from_share => @within_share)
+      end
+
+      #
+      # Sets the type of return value that is expected from a successful call
+      # to this API action.
+      #
+      #   returns :array, :structure => :user
+      #
+      # @param type [Symbol] the type of object that will be returend
+      # @param options [Hash] further options about the returned value
+      # @return [void]
+      #
+      def returns(type, options = {})
+        @action.returns = options.merge(:type => type)
+      end
+
+      #
+      # Sets the name of the authenticator to use for this action
+      #
+      # @param name [Symbol] the name of the authenticator
+      #
+      def authenticator(name)
+        @action.authenticator = name
+      end
+
+      #
+      # Sets the name of the access rule to use for this action
+      #
+      # @param name [Symbol] the name of the authenticator
+      #
+      def access_rule(name)
+        if name.is_a?(Hash)
+          authenticator name.first[0]
+          access_rule name.first[1]
+        else
+          @action.access_rule = name
+        end
       end
 
       #
@@ -67,7 +157,67 @@ module Moonrope
       # @return [void]
       #
       def action(&block)
-        @action.action = block
+        @action.actions << block
+      end
+
+      #
+      # Specify that this action will be returning paginated data. Sets up the
+      # parameters for the action as appropriate.
+      #
+      def paginated(options = {})
+        @action.traits << :paginated
+        param :page, "The page number", :type => Integer, :required => true, :default => options[:page] || 1
+        param :per_page, "The number of items to return per page", :type => Integer, :required => true, :default => options[:per_page] || 30
+      end
+
+      #
+      # Specify that this action will return data sorted by user provided data.
+      #
+      def sortable(*fields)
+        if fields.empty?
+          raise Moonrope::Errors::Error, "You must specify at least one field when calling 'sortable'"
+        else
+          if fields.first.is_a?(Hash)
+            default_order = fields.first.first[1].to_s
+            fields[0] = fields.first.first[0]
+          else
+            default_order = 'asc'
+          end
+          @action.traits << :sortable
+          param :sort_by, "The field to sort by", :type => String, :required => true, :default => fields[0].to_s, :options => fields.map(&:to_s)
+          param :order, "The direction to order units by", :type => String, :required => true, :default => default_order, :options => ["asc", "desc"]
+        end
+      end
+
+      #
+      # Specify that this action will return data which can be filtered by specifying
+      # certain parameters on a filter parameter
+      #
+      def filterable(&block)
+        if @action.errors['FilterError'].nil?
+          error 'FilterError', "An error has occurred while processing filters for this action", :attributes => {:issue_code => "A more specific issue code", :issue_message => "A more specific message about the issue"}
+        end
+
+        if @action.params[:filters].nil?
+          param :filters, "A hash of filters to apply to results", :type => Hash, :default => {}
+        end
+        dsl = FilterableDSL.new(@action)
+        dsl.instance_eval(&block)
+      end
+
+      #
+      # Include any block from the controller shares
+      #
+      def use(name, options = {})
+        if block = (@action.controller.shared_actions[name] || @action.controller.base.shared_actions[name])
+          @within_shared_action ||= []
+          @within_shared_action << name
+          self.instance_exec(options, &block)
+        else
+          raise Moonrope::Errors::InvalidSharedAction, "Invalid share name #{name}"
+        end
+      ensure
+        @within_shared_action.delete(name) if @within_shared_action
       end
 
     end

data/lib/moonrope/dsl/authenticator_dsl.rb

@@ -0,0 +1,31 @@
+module Moonrope
+  module DSL
+    class AuthenticatorDSL
+
+      def initialize(authenticator)
+        @authenticator = authenticator
+      end
+
+      def description(value)
+        @authenticator.description = value
+      end
+
+      def header(name, description = nil, options = {})
+        @authenticator.headers[name] = options.merge(:name => name, :description => description)
+      end
+
+      def error(name, description = nil, options = {})
+        @authenticator.errors[name] = options.merge(:name => name, :description => description)
+      end
+
+      def lookup(&block)
+        @authenticator.lookup = block
+      end
+
+      def rule(name, error_code, description = nil, &block)
+        @authenticator.rules[name] = {:name => name, :error_code => error_code, :description => description, :block => block}
+      end
+
+    end
+  end
+end

data/lib/moonrope/dsl/base_dsl.rb

@@ -1,3 +1,7 @@
+require 'moonrope/structure'
+require 'moonrope/controller'
+require 'moonrope/authenticator'
+
 module Moonrope
   module DSL
     class BaseDSL
@@ -47,24 +51,6 @@ module Moonrope
         controller
       end
 
-      #
-      # Set the authenticator for the API.
-      #
-      # @yield stores the block as the authenticator
-      #
-      def authenticator(&block)
-        @base.authenticator = block
-      end
-
-      #
-      # Set the default access check block.
-      #
-      # @yield stores the block as the access check
-      #
-      def default_access(value = nil, &block)
-        @base.default_access = block_given? ? block : value
-      end
-
       #
       # Define a new helper in the global namespace
       #
@@ -81,6 +67,23 @@ module Moonrope
         helper_instance
       end
 
+      #
+      # Define a new authenticator
+      #
+      def authenticator(name, &block)
+        authenticator = Moonrope::Authenticator.new(name)
+        dsl = Moonrope::DSL::AuthenticatorDSL.new(authenticator)
+        dsl.instance_eval(&block) if block_given?
+        @base.authenticators[name] = authenticator
+      end
+
+      #
+      # Define a new global shared action
+      #
+      def shared_action(name, &block)
+        @base.shared_actions[name] = block
+      end
+
     end
   end
 end

data/lib/moonrope/dsl/controller_dsl.rb

@@ -1,3 +1,6 @@
+require 'moonrope/action'
+require 'moonrope/before_action'
+
 module Moonrope
   module DSL
     class ControllerDSL
@@ -14,6 +17,31 @@ module Moonrope
       # @return [Moonrope::Controller] the associated controller
       attr_reader :controller
 
+      #
+      # Stop this controller frmo being documented
+      #
+      def no_doc!
+        @controller.doc = false
+      end
+
+      #
+      # Set the friendly name for the controller
+      #
+      # @param name [String]
+      #
+      def friendly_name(string)
+        @controller.friendly_name = string
+      end
+
+      #
+      # Set the description for the controller
+      #
+      # @param description [String]
+      #
+      def description(description)
+        @controller.description = description
+      end
+
       #
       # Defines a new action within the controller.
       #
@@ -28,6 +56,29 @@ module Moonrope
         action
       end
 
+      #
+      # Set the name of the authenticator to use for all actions in this controller
+      #
+      # @param name [Symbol]
+      #
+      def authenticator(name)
+        @controller.authenticator = name
+      end
+
+      #
+      # Set the name of the access rule to use for all actions in this controller
+      #
+      # @param name [Symbol]
+      #
+      def access_rule(name)
+        if name.is_a?(Hash)
+          authenticator name.first[0]
+          access_rule name.first[1]
+        else
+          @controller.access_rule = name
+        end
+      end
+
       #
       # Defines a new before action within the controller.
       #
@@ -43,14 +94,6 @@ module Moonrope
         before_action
       end
 
-      #
-      # Defines the access required for controller methods which do not
-      # define their own access.
-      #
-      def access(value = nil, &block)
-        @controller.access = block_given? ? block : value
-      end
-
       #
       # Defines a new helper for this controller.
       #
@@ -61,9 +104,17 @@ module Moonrope
         if @controller.base.helper(name, @controller)
           raise Moonrope::Errors::HelperAlreadyDefined, "Helper has already been defined with name `#{name}`"
         end
-
         @controller.base.helpers << Moonrope::Helper.new(name, @controller, options, &block)
       end
+
+      #
+      # Define a shared action which can be used by any action
+      #
+      # @param name[Symbol] the name of the shared action
+      #
+      def shared_action(name, &block)
+        @controller.shared_actions[name] = block
+      end
     end
   end
 end

data/lib/moonrope/dsl/filterable_dsl.rb

@@ -0,0 +1,27 @@
+module Moonrope
+  module DSL
+    class FilterableDSL
+
+      def initialize(action)
+        @action = action
+      end
+
+      def attribute(name, options = {}, &block)
+        if options[:type] == Integer || options[:type] == Float
+          # Numbers
+          options[:operators] ||= [:eq, :not_eq, :gt, :gte, :lt, :lte, :in, :not_in]
+        elsif options[:type] == String
+          # Strings
+          options[:operators] ||= [:eq, :not_eq, :starts_with, :ends_with, :in, :not_in]
+        elsif options[:type] == :timestamp
+          # Times
+          options[:operators] ||= [:eq, :not_eq, :gt, :gte, :lt, :lte]
+        else
+          # Everything else
+          options[:operators] ||= [:eq, :not_eq]
+        end
+        @action.filters[name] = options.merge(:name => name, :block => block)
+      end
+    end
+  end
+end