haveapi 0.3.2 → 0.4.0

data/lib/haveapi/server.rb

@@ -1,3 +1,6 @@
+require 'erb'
+require 'redcarpet'
+
 module HaveAPI
   class Server
     attr_reader :root, :routes, :module_name, :auth_chain, :versions, :default_version,
@@ -7,7 +10,11 @@ module HaveAPI
 
     # Called after the user was authenticated (or not). The block is passed
     # current user object or nil as an argument.
-    has_hook :post_authenticated
+    has_hook :post_authenticated,
+        desc: 'Called after the user was authenticated',
+        args: {
+            current_user: 'object returned by the authentication backend',
+        }
 
     module ServerHelpers
       def authenticate!(v)
@@ -51,7 +58,7 @@ module HaveAPI
       def report_error(code, headers, msg)
         @halted = true
         content_type @formatter.content_type, charset: 'utf-8'
-        halt code, headers, @formatter.format(false, nil, msg)
+        halt code, headers, @formatter.format(false, nil, msg, version: false)
       end
 
       def root
@@ -90,7 +97,7 @@ module HaveAPI
       @versions ||= []
 
       if v == :all
-        @versions = HaveAPI.get_versions(@module_name)
+        @versions = HaveAPI.versions(@module_name)
       elsif v.is_a?(Array)
         @versions += v
         @versions.uniq!
@@ -101,7 +108,7 @@ module HaveAPI
     end
 
     # Set default version of API.
-    def set_default_version(v)
+    def default_version=(v)
       @default_version = v
     end
 
@@ -152,8 +159,11 @@ module HaveAPI
       @sinatra.get @root do
         authenticated?(settings.api_server.default_version)
 
-        @api = settings.api_server.describe(Context.new(settings.api_server, user: current_user,
-                                            params: params))
+        @api = settings.api_server.describe(Context.new(
+            settings.api_server,
+            user: current_user,
+            params: params
+        ))
 
         content_type 'text/html'
         erb :index, layout: :main_layout
@@ -166,16 +176,24 @@ module HaveAPI
 
         case params[:describe]
           when 'versions'
-            ret = {versions: settings.api_server.versions,
-                   default: settings.api_server.default_version}
+            ret = {
+                versions: settings.api_server.versions,
+                default: settings.api_server.default_version
+            }
 
           when 'default'
-            ret = settings.api_server.describe_version(Context.new(settings.api_server, version: settings.api_server.default_version,
-                                                                  user: current_user, params: params))
+            ret = settings.api_server.describe_version(Context.new(
+                settings.api_server,
+                version: settings.api_server.default_version,
+                user: current_user, params: params
+            ))
 
           else
-            ret = settings.api_server.describe(Context.new(settings.api_server, user: current_user,
-                                                           params: params))
+            ret = settings.api_server.describe(Context.new(
+                settings.api_server,
+                user: current_user,
+                params: params
+            ))
         end
 
         @formatter.format(true, ret)
@@ -195,6 +213,14 @@ module HaveAPI
           GitHub::Markdown.render(File.new(settings.views + '/../../../README.md').read)
         end
       end
+      
+      @sinatra.get "#{@root}doc/json-schema" do
+        content_type 'text/html'
+        erb :doc_layout, layout: :main_layout do
+          @content = erb :'../../../doc/json-schema'
+          @sidebar = erb :'doc_sidebars/json-schema'
+        end
+      end
 
       @sinatra.get %r{#{@root}doc/([^\.]+)[\.md]?} do |f|
         content_type 'text/html'
@@ -244,8 +270,12 @@ module HaveAPI
         authenticated?(v)
 
         @v = v
-        @help = settings.api_server.describe_version(Context.new(settings.api_server, version: v,
-                                                                 user: current_user, params: params))
+        @help = settings.api_server.describe_version(Context.new(
+            settings.api_server,
+            version: v,
+            user: current_user,
+            params: params
+        ))
         content_type 'text/html'
         erb :doc_layout, layout: :main_layout do
           @content = erb :version_page
@@ -257,13 +287,29 @@ module HaveAPI
         access_control
         authenticated?(v)
 
-        @formatter.format(true, settings.api_server.describe_version(Context.new(settings.api_server, version: v,
-                                                                              user: current_user, params: params)))
+        @formatter.format(true, settings.api_server.describe_version(Context.new(
+            settings.api_server,
+            version: v,
+            user: current_user,
+            params: params
+        )))
       end
 
       HaveAPI.get_version_resources(@module_name, v).each do |resource|
         mount_resource(prefix, v, resource, @routes[v][:resources])
       end
+
+      validate_resources(@routes[v][:resources])
+    end
+
+    def validate_resources(resources)
+      resources.each_value do |r|
+        r[:actions].each_key do |a|
+          a.validate_build
+        end
+
+        validate_resources(r[:resources])
+      end
     end
 
     def mount_resource(prefix, v, resource, hash)
@@ -271,7 +317,10 @@ module HaveAPI
 
       resource.routes(prefix).each do |route|
         if route.is_a?(Hash)
-          hash[resource][:resources][route.keys.first] = mount_nested_resource(v, route.values.first)
+          hash[resource][:resources][route.keys.first] = mount_nested_resource(
+              v,
+              route.values.first
+          )
 
         else
           hash[resource][:actions][route.action] = route.url
@@ -315,10 +364,15 @@ module HaveAPI
           report_error(400, {}, 'Bad JSON syntax')
         end
 
-        action = route.action.new(request, v, params, body, Context.new(settings.api_server, version: v,
-                                                                        action: route.action, url: route.url,
-                                                                        params: params,
-                                                                        user: current_user, endpoint: true))
+        action = route.action.new(request, v, params, body, Context.new(
+            settings.api_server,
+            version: v,
+            action: route.action,
+            url: route.url,
+            params: params,
+            user: current_user,
+            endpoint: true
+        ))
 
         unless action.authorized?(current_user)
           report_error(403, {}, 'Access denied. Insufficient permissions.')
@@ -330,7 +384,8 @@ module HaveAPI
             status,
             status  ? reply : nil,
             !status ? reply : nil,
-            errors
+            errors,
+            version: false
         )
       end
 
@@ -343,10 +398,16 @@ module HaveAPI
         authenticate!(v) if route.action.auth
 
         begin
-          desc = route.action.describe(Context.new(settings.api_server, version: v,
-                                                   action: route.action, url: route.url,
-                                                   args: args, params: params,
-                                                   user: current_user, endpoint: true))
+          desc = route.action.describe(Context.new(
+              settings.api_server,
+              version: v,
+              action: route.action,
+              url: route.url,
+              args: args,
+              params: params,
+              user: current_user,
+              endpoint: true
+          ))
 
           unless desc
             report_error(403, {}, 'Access denied. Insufficient permissions.')

data/lib/haveapi/tasks/hooks.rb

@@ -0,0 +1,3 @@
+def document_hooks(file = 'doc/Hooks.md')
+  render_doc_file('doc/hooks.erb', 'doc/Hooks.md')
+end

data/lib/haveapi/tasks/yard.rb

@@ -0,0 +1,12 @@
+require 'haveapi/tasks/hooks'
+
+def render_doc_file(src, dst)
+  src = File.join(File.dirname(__FILE__), '..', '..', '..', src)
+
+  Proc.new do
+    File.write(
+        dst,
+        ERB.new(File.read(src), 0).result(binding)
+    )
+  end
+end

data/lib/haveapi/validator.rb

@@ -0,0 +1,134 @@
+module HaveAPI
+  # Validators are stored in this module.
+  module Validators ; end
+
+  # Base class for all validators.
+  #
+  # All validators can have a short and a full form. The short form is used
+  # when default configuration is sufficient. Custom settings can be set using
+  # the full form.
+  #
+  # The short form means the validator is configured as +<option> => <single value>+.
+  # The full form is +<option> => { hash with configuration options }+.
+  #
+  # It is up to each validator what exactly the short form means and what options
+  # can be set. Specify only those options that you wish to override. The only
+  # common option is +message+ - the error message sent to the client if the provided
+  # value did not pass the validator.
+  #
+  # The +message+ can contain +%{value}+, which is replaced by the actual value
+  # that did not pass the validator.
+  class Validator
+    class << self
+      # Set validator name used in API documentation.
+      def name(v = nil)
+        if v
+          @name = v
+
+        else
+          @name
+        end
+      end
+
+      # Specify options this validator takes from the parameter definition.
+      def takes(*opts)
+        @takes = opts
+      end
+
+      # True if this validator uses any of options in hash +opts+.
+      def use?(opts)
+        !(opts.keys & @takes).empty?
+      end
+
+      # Use the validator on given set of options in hash +opts+. Used
+      # options are removed from +opts+.
+      def use(opts)
+        keys = opts.keys & @takes
+
+        fail 'too many keys' if keys.size > 1
+        new(keys.first, opts.delete(keys.first))
+      end
+    end
+
+    attr_accessor :message, :params
+
+    def initialize(key, opts)
+      reconfigure(key, opts)
+    end
+
+    def reconfigure(key, opts)
+      @key = key
+      @opts = opts
+      setup
+    end
+
+    def useful?
+      @useful.nil? ? true : @useful
+    end
+
+    # Validators should be configured by the given options. This method may be
+    # called multiple times, if the validator is reconfigured after it was
+    # created.
+    def setup
+      raise NotImplementedError
+    end
+
+    # Return a hash documenting this validator.
+    def describe
+      raise NotImplementedError
+    end
+
+    # Return true if the value is valid.
+    def valid?(v)
+      raise NotImplementedError
+    end
+
+    # Calls method valid?, but before calling it sets instance variable
+    # +@params+. It contains of hash of all other parameters. The validator
+    # may use this information as it will.
+    def validate(v, params)
+      @params = params
+      ret = valid?(v)
+      @params = nil
+      ret
+    end
+
+    protected
+    # This method has three modes of function.
+    #
+    # 1. If +v+ is nil, it returns +@opts+. It is used if +@opts+ is not a hash
+    #    but a single value - abbreviation if we're ok with default settings
+    #    for given validator.
+    # 2. If +v+ is not nil and +@opts+ is not a hash, it returns +default+
+    # 3. If +v+ is not nil and +@opts+ is a hash and +@opts[v]+ is not nil, it is
+    #    returned. Otherwise the +default+ is returned.
+    def take(v = nil, default = nil)
+      if v.nil?
+        @opts
+
+      else
+        return default unless @opts.is_a?(::Hash)
+        return @opts[v] unless @opts[v].nil?
+        default
+      end
+    end
+
+    # Declare validator as useless. Such validator does not do anything and can
+    # be removed from validator chain. Validator can become useless when it's configuration
+    # makes it so.
+    def useless
+      @useful = false
+    end
+
+    # Returns true if +@opts+ is not a hash.
+    def simple?
+      !@opts.is_a?(::Hash)
+    end
+
+    # Returns the name of the option given to this validator. It may bear some
+    # meaning to the validator.
+    def opt
+      @key
+    end
+  end
+end

data/lib/haveapi/validator_chain.rb

@@ -0,0 +1,99 @@
+module HaveAPI
+  # A chain of validators for one input parameter.
+  class ValidatorChain
+    def initialize(args)
+      @validators = []
+      @required = false
+
+      find_validators(args) do |validator|
+        obj = validator.use(args)
+        next unless obj.useful?
+        @required = true if obj.is_a?(Validators::Presence)
+        @validators << obj
+      end
+    end
+
+    # Adds validator that takes option +name+ with configuration in +opt+.
+    # If such validator already exists, it is reconfigured with newly provided
+    # +opt+.
+    #
+    # If +opt+ is +nil+, the validator is removed.
+    def add_or_replace(name, opt)
+      args = { name => opt }
+
+      unless v_class = find_validator(args)
+        fail "validator for '#{name}' not found"
+      end
+
+      exists = @validators.detect { |v| v.is_a?(v_class) }
+      obj = exists
+
+      if exists
+        if opt.nil?
+          @validators.delete(exists)
+
+        else
+          exists.reconfigure(name, opt)
+          @validators.delete(exists) unless exists.useful?
+        end
+
+      else
+        obj = v_class.use(args)
+        @validators << obj if obj.useful?
+      end
+
+      if v_class == Validators::Presence
+        @required = !opt.nil? && obj.useful? ? true : false
+      end
+    end
+
+    # Returns true if validator Validators::Presence is used.
+    def required?
+      @required
+    end
+
+    def describe
+      ret = {}
+      @validators.each do |v|
+        ret[v.class.name] = v.describe
+      end
+
+      ret
+    end
+
+    # Validate +value+ using all configured validators. It returns
+    # either +true+ if the value passed all validators or an array
+    # of errors.
+    def validate(value, params)
+      ret = []
+
+      @validators.each do |validator|
+        next if validator.validate(value, params)
+        ret << validator.message % {
+            value: value
+        }
+      end
+
+      ret.empty? ? true : ret
+    end
+
+    protected
+    def find_validator(args)
+      HaveAPI::Validators.constants.select do |v|
+        validator = HaveAPI::Validators.const_get(v)
+
+        return validator if validator.use?(args)
+      end
+
+      nil
+    end
+
+    def find_validators(args)
+      HaveAPI::Validators.constants.select do |v|
+        validator = HaveAPI::Validators.const_get(v)
+
+        yield(validator) if validator.use?(args)
+      end
+    end
+  end
+end

data/lib/haveapi/validators/acceptance.rb

@@ -0,0 +1,38 @@
+module HaveAPI
+  # Accepts a single configured value.
+  #
+  # Short form:
+  #   string :param, accept: 'value'
+  #
+  # Full form:
+  #   string :param, accept: {
+  #     value: 'value',
+  #     message: 'the error message'
+  #   }
+  class Validators::Acceptance < Validator
+    name :accept
+    takes :accept
+
+    def setup
+      if simple?
+        @value = take
+
+      else
+        @value = take(:value)
+      end
+
+      @message = take(:message, "has to be #{@value}")
+    end
+
+    def describe
+      {
+          value: @value,
+          message: @message,
+      }
+    end
+
+    def valid?(v)
+      v == @value
+    end
+  end
+end

data/lib/haveapi/validators/confirmation.rb

@@ -0,0 +1,46 @@
+module HaveAPI
+  # Checks that two parameters are equal or not equal.
+  #
+  # Short form:
+  #   string :param, confirm: :other_parameter
+  #
+  # Full form:
+  #   string :param, confirm: {
+  #     param: :other_parameter,
+  #     equal: true/false,
+  #     message: 'the error message'
+  #   }
+  #
+  # +equal+ defaults to +true+.
+  class Validators::Confirmation < Validator
+    name :confirm
+    takes :confirm
+
+    def setup
+      @param = simple? ? take : take(:param)
+      @equal = take(:equal, true)
+      @message = take(
+        :message,
+        @equal ? "must be the same as #{@param}"
+               : "must be different from #{@param}"
+      )
+    end
+
+    def describe
+      {
+          equal: @equal ? true : false,
+          parameter: @param,
+          message: @message,
+      }
+    end
+
+    def valid?(v)
+      if @equal
+        v == params[@param]
+
+      else
+        v != params[@param]
+      end
+    end
+  end
+end

data/lib/haveapi/validators/custom.rb

@@ -0,0 +1,21 @@
+module HaveAPI
+  # Custom validator. It has only a short form, taking the description
+  # of the validator. This validator passes every value. It is up to the
+  # developer to implement the validation in HaveAPI::Action.exec.
+  class Validators::Custom < Validator
+    name :custom
+    takes :validate
+
+    def setup
+      @desc = take
+    end
+
+    def describe
+      @desc
+    end
+
+    def valid?(v)
+      true
+    end
+  end
+end

data/lib/haveapi/validators/exclusion.rb

@@ -0,0 +1,38 @@
+module HaveAPI
+  # Checks that the value is not reserved.
+  #
+  # Short form:
+  #   string :param, exclude: %i(one two three)
+  #
+  # Full form:
+  #   string :param, exclude: {
+  #     values: %i(one two three),
+  #     message: 'the error message'
+  #   }
+  #
+  # In this case, the value could be anything but +one+, +two+ or
+  # +three+.
+  class Validators::Exclusion < Validator
+    name :exclude
+    takes :exclude
+
+    def setup
+      @values = (simple? ? take : take(:values)).map! do |v|
+        v.is_a?(::Symbol) ? v.to_s : v
+      end
+
+      @message = take(:message, '%{value} cannot be used')
+    end
+
+    def describe
+      {
+          values: @values,
+          message: @message,
+      }
+    end
+
+    def valid?(v)
+      !@values.include?(v)
+    end
+  end
+end

data/lib/haveapi/validators/format.rb

@@ -0,0 +1,42 @@
+module HaveAPI
+  # Checks that the value is or is not in specified format.
+  #
+  # Short form:
+  #   string :param, format: /^[a-z0-9]+$/
+  #
+  # Full form:
+  #   string :param, format: {
+  #     rx: /^[a-z0-9]+$/,
+  #     match: true/false,
+  #     message: 'the error message'
+  #   }
+  class Validators::Format < Validator
+    name :format
+    takes :format
+
+    def setup
+      @rx = simple? ? take : take(:rx)
+      @match = take(:match, true)
+      @desc = take(:desc)
+      @message = take(:message, @desc || '%{value} is not in a valid format')
+    end
+
+    def describe
+      {
+          rx: @rx.source,
+          match: @match,
+          description: @desc,
+          message: @message,
+      }
+    end
+
+    def valid?(v)
+      if @match
+        @rx.match(v) ? true : false
+
+      else
+        @rx.match(v) ? false : true
+      end
+    end
+  end
+end

data/lib/haveapi/validators/inclusion.rb

@@ -0,0 +1,42 @@
+module HaveAPI
+  # Checks that the value is from given set of allowed values.
+  #
+  # Short form:
+  #   string :param, choices: %i(one two three)
+  #
+  # Full form:
+  #   string :param, choices: {
+  #     values: %i(one two three),
+  #     message: 'the error message'
+  #   }
+  #
+  # Option +choices+ is an alias to +include+.
+  class Validators::Inclusion < Validator
+    name :include
+    takes :choices, :include
+
+    def setup
+      @values = (simple? ? take : take(:values)).map! do |v|
+        v.is_a?(::Symbol) ? v.to_s : v
+      end
+
+      @message = take(:message, '%{value} cannot be used')
+    end
+
+    def describe
+      {
+          values: @values,
+          message: @message,
+      }
+    end
+
+    def valid?(v)
+      if @values.is_a?(::Hash)
+        @values.has_key?(v)
+
+      else
+        @values.include?(v)
+      end
+    end
+  end
+end