moonrope 1.3.3 → 2.0.2

data/lib/moonrope/authenticator.rb

@@ -0,0 +1,42 @@
+require 'moonrope/dsl/authenticator_dsl'
+
+module Moonrope
+  class Authenticator
+
+    def initialize(name, &block)
+      @name = name
+      @headers = {}
+      @errors = {}
+      @rules = {}
+      if block_given?
+        dsl = Moonrope::DSL::AuthenticatorDSL.new(self)
+        dsl.instance_eval(&block)
+      end
+    end
+
+    # @return [Symbol] the name of the authenticator
+    attr_reader :name
+
+    # @return [String] the friendly name for the authenticator
+    attr_accessor :friendly_name
+
+    # @return [String] the description for the authenticator
+    attr_accessor :description
+
+    # @return [Proc] the lookup block
+    attr_accessor :lookup
+
+    # @return [Hash] the headers that this authenticator uses
+    attr_reader :headers
+
+    # @return [Hash] the errors this authenticator can raise
+    attr_reader :errors
+
+    # @return [Hash] the rules this authenticator provides
+    attr_reader :rules
+
+    # @return [Bool] whether or not the action should be documented
+    attr_accessor :doc
+
+  end
+end

data/lib/moonrope/base.rb

@@ -1,3 +1,5 @@
+require 'moonrope/dsl/base_dsl'
+
 module Moonrope
   class Base
 
@@ -14,6 +16,11 @@ module Moonrope
       api
     end
 
+    class << self
+      # @return [Moonrope::Base] return a global instance
+      attr_accessor :instance
+    end
+
     # @return [Array] the array of defined structures
     attr_reader :structures
 
@@ -26,11 +33,11 @@ module Moonrope
     # @return [Moonrope::DSL::BaseDSL] the base DSL
     attr_accessor :dsl
 
-    # @return [Proc] the authentictor
-    attr_accessor :authenticator
+    # @return [Hash] authenticators
+    attr_accessor :authenticators
 
-    # @return [Proc] the default access condition
-    attr_accessor :default_access
+    # @return [Hash] global shared actions
+    attr_accessor :shared_actions
 
     # @return [Array] the array of directories to load from  (if relevant)
     attr_accessor :load_directories
@@ -41,6 +48,9 @@ module Moonrope
     # @return [Proc] a proc to execute before every request
     attr_accessor :on_request
 
+    # @return [Boolean] is SSL forced?
+    attr_accessor :force_ssl
+
     #
     # Initialize a new instance of the Moonrope::Base
     #
@@ -54,6 +64,24 @@ module Moonrope
       @dsl.instance_eval(&block) if block_given?
     end
 
+    #
+    # Make a new base based on configuration
+    #
+    def copy_from(other)
+      @environment = other.environment
+      @load_directories = other.load_directories
+      @on_request = other.on_request
+      other.request_callbacks.each { |block| self.register_request_callback(&block) }
+      other.request_error_callbacks.each { |block| self.register_request_error_callback(&block) }
+      other.external_errors.each { |error, block| self.register_external_error(error, &block) }
+    end
+
+    def copy
+      new_base = self.class.new
+      new_base.copy_from(self)
+      new_base
+    end
+
     #
     # Reset the whole base to contain no data.
     #
@@ -61,7 +89,8 @@ module Moonrope
       @structures = []
       @controllers = []
       @helpers = @helpers.is_a?(Array) ? @helpers.select { |h| h.options[:unloadable] == false } : []
-      @authenticator = nil
+      @authenticators = {}
+      @shared_actions = {}
       @default_access = nil
     end
 
@@ -92,7 +121,17 @@ module Moonrope
     #
     def load_directory(directory)
       if File.exist?(directory)
-        Dir["#{directory}/**/*.rb"].each do |filename|
+        @loaded_files = []
+        Dir[
+          "#{directory}/structures/**/*.rb",
+          "#{directory}/shared_actions/**/*.rb",
+          "#{directory}/controllers/**/*.rb",
+          "#{directory}/helpers/**/*.rb",
+          "#{directory}/authenticators/**/*.rb",
+          "#{directory}/*.rb",
+        ].each do |filename|
+          next if @loaded_files.include?(filename)
+          @loaded_files << filename
           self.dsl.instance_eval(File.read(filename), filename)
         end
         true
@@ -196,5 +235,27 @@ module Moonrope
       @request_error_callbacks ||= []
     end
 
+    #
+    # Set a block which will be executed whenever a request is received by moonrope.
+    #
+    #
+    def register_request_callback(&block)
+      request_callbacks << block
+    end
+
+    #
+    # Return an array of request callbacks
+    #
+    def request_callbacks
+      @request_callbacks ||= []
+    end
+
+    #
+    # Should SSL be forced?
+    #
+    def force_ssl?
+      @force_ssl || false
+    end
+
   end
 end

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