haveapi 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f19eb81f8b3f54654715dfaa52c85e17675860a6
-  data.tar.gz: 5b5013c9f1b52af5a55935fd44d78a845d2fdd7d
+  metadata.gz: 00a5f09608d0287b5187d60b5e5f8528b8077c33
+  data.tar.gz: 728e896638ef103f0d62db8aea3d0a26cae3e818
 SHA512:
-  metadata.gz: 8b1df715121edd42ba79af47601e2d5daa87226a2a4cdf887d6d54b046e5a287e17451d8950a8c9ed722ccfb8eed4cd0e6343b1fd6aa574db4fa39515c41c048
-  data.tar.gz: a2c9fec65f9ab767b856f1144732109262f44c803c67d634fd7f9b62d81919bfc210d8ae660b43ef820762489eba54b35a7a1799a1f9ee91eb8fdfc3df16000c
+  metadata.gz: f3519a72a83f31a146da97ffb2422439231afa6a00b55eb55f3ceb1f77d8766f1afb76fe60454bc403fccd7fe2689d2c76fe2970b2557b594258c28f834f478e
+  data.tar.gz: 5296734002aca4221526d0bbd98ff2927bb61b6b74781f46d2d79c5bf01d29d5d0a16bfe59aa0b313b9819fe823150324f247387a7ed310d6fe747e9f8cb4a02

data/CHANGELOG

@@ -1,3 +1,14 @@
+* Tue Feb 9 2016 - version 0.5.0
+- Helper methods for testing APIs
+- Added tests covering the basic functionality
+- Fixed overflow in table of contents in online API doc
+- Authentication chain can be empty
+- Fixed Params.optional
+- Fixed coercion of Float input parameters
+- Renamed Params::Param to Parameters::Typed and Params::Resource to
+  Parameters::Resource
+- Instance-level hooks are stored in the object itself
+
 * Sun Jan 24 2016 - version 0.4.2
 - Inclusion validator: handle hash correctly, don't overwrite given values
 

data/Rakefile

@@ -7,6 +7,7 @@ require 'haveapi/tasks/yard'
 
 RSpec::Core::RakeTask.new(:spec) do |spec|
   spec.pattern = FileList['spec/**/*_spec.rb']
+  spec.rspec_opts = '--require spec_helper'
 end
 
 begin

data/haveapi.gemspec

@@ -5,7 +5,7 @@ require 'haveapi/version'
 Gem::Specification.new do |s|
   s.name        = 'haveapi'
   s.version     = HaveAPI::VERSION
-  s.date        = '2016-01-24'
+  s.date        = '2016-02-09'
   s.summary     =
   s.description = 'Framework for creating self-describing APIs'
   s.authors     = 'Jakub Skokan'

data/lib/haveapi/authentication/chain.rb

@@ -37,6 +37,8 @@ module HaveAPI::Authentication
     # Authentication provider can deny the user access by calling Base#deny.
     def authenticate(v, *args)
       catch(:return) do
+        return unless @instances[v]
+
         @instances[v].each do |provider|
           u = provider.authenticate(*args)
           return u if u
@@ -48,6 +50,8 @@ module HaveAPI::Authentication
 
     def describe(context)
       ret = {}
+      
+      return ret unless @instances[context.version]
 
       @instances[context.version].each do |provider|
         ret[provider.name] = provider.describe

data/lib/haveapi/hooks.rb

@@ -7,14 +7,36 @@ module HaveAPI
   # it is possible to connect to a specific instance and not for
   # all instances of a class.
   #
+  # Hook definition contains additional information for as a documentation:
+  # description, context, arguments, return value.
+  #
+  # Every hook can have multiple listeners. They are invoked in the order of
+  # registration. Instance-level listeners first, then class-level. Hooks are
+  # chained using the block's first argument and return value. The first block
+  # to be executed gets the initial value, may make changes and returns it.
+  # The next block gets the return value of the previous block as its first
+  # argument, may make changes and returns it. Return value of the last block
+  # is returned to the caller of the hook.
+  #
   # === \Usage
   # ==== \Register hooks
   #   class MyClass
   #     include Hookable
   #
-  #     has_hook :myhook
+  #     has_hook :myhook,
+  #              desc: 'Called when I want to',
+  #              context: 'current',
+  #              args: {
+  #                  a: 'integer',
+  #                  b: 'integer',
+  #                  c: 'integer',
+  #              }
   #   end
   #
+  # Not that the additional information is just optional. A list of defined
+  # hooks and their description is a part of the reference documentation
+  # generated by yard.
+  #
   # ==== \Class level hooks
   #   # Connect hook
   #   MyClass.connect_hook(:myhook) do |ret, a, b, c|
@@ -43,7 +65,20 @@ module HaveAPI
   #   my.call_class_hooks_for(:myhook, args: [1, 2, 3])
   #   # Call both instance and class hooks at once
   #   my.call_hooks_for(:myhook, args: [1, 2, 3])
+  #
+  # ==== \Chaining
+  #   5.times do |i|
+  #     MyClass.connect_hook(:myhook) do |ret, a, b, c|
+  #       ret[:counter] += i
+  #       ret
+  #     end
+  #   end
+  #
+  #   p MyClass.call_hooks(:myhook, args: [1, 2, 3], initial: {counter: 0})
+  #   => {:counter=>5}
   module Hooks
+    INSTANCE_VARIABLE = '@_haveapi_hooks'
+
     # Register a hook defined by +klass+ with +name+.
     # +klass+ is an instance of Class, that is class name, not it's instance.
     # +opts+ is a hash and can have following keys:
@@ -72,16 +107,16 @@ module HaveAPI
     end
 
     # Connect instance hook from instance +klass+ with +name+ to +block+.
-    def self.connect_instance_hook(klass, name, &block)
-      unless @hooks[klass]
-        @hooks[klass] = {}
+    def self.connect_instance_hook(instance, name, &block)
+      hooks = instance.instance_variable_get(INSTANCE_VARIABLE)
 
-        @hooks[klass.class].each do |k, v|
-          @hooks[klass][k] = {listeners: []}
-        end
+      unless hooks
+        hooks = {}
+        instance.instance_variable_set(INSTANCE_VARIABLE, hooks)
       end
 
-      @hooks[klass][name][:listeners] << block
+      hooks[name] ||= {listeners: []}
+      hooks[name][:listeners] << block
     end
 
     # Call all blocks that are connected to hook in +klass+ with +name+.
@@ -98,17 +133,39 @@ module HaveAPI
     # A block may decide that no further blocks should be executed.
     # In such a case it calls Hooks.stop with the return value. It is then
     # returned to the caller immediately.
-    def self.call_for(klass, name, where = nil, args: [], initial: {})
+    #
+    # @param klass [Class instance, instance]
+    # @param name [Symbol] hook name
+    # @param where [Class instance] class in whose context hooks are executed
+    # @param args [Array] an array of arguments passed to hooks
+    # @param initial [Hash] initial return value
+    # @param instance [Boolean] call instance hooks or not; nil means auto-detect
+    def self.call_for(
+        klass,
+        name,
+        where = nil,
+        args: [],
+        initial: {},
+        instance: nil
+    )
       classified = hook_classify(klass)
 
+      if (instance.nil? && !classified.is_a?(Class)) || instance
+        all_hooks = klass.instance_variable_get(INSTANCE_VARIABLE)
+
+      else
+        all_hooks = @hooks[classified]
+      end
+
       catch(:stop) do
-        return initial unless @hooks[classified]
-        hooks = @hooks[classified][name][:listeners]
+        return initial unless all_hooks
+        hooks = all_hooks[name][:listeners]
         return initial unless hooks
 
         hooks.each do |hook|
           if where
             ret = where.instance_exec(initial, *args, &hook)
+
           else
             ret = hook.call(initial, *args)
           end

data/lib/haveapi/model_adapters/active_record.rb

@@ -362,7 +362,7 @@ END
 
       def validator_for(param, key, opts)
         @params.each do |p|
-          next unless p.is_a?(::HaveAPI::Parameters::Param)
+          next unless p.is_a?(::HaveAPI::Parameters::Typed)
 
           if p.db_name == param
             p.add_validator(key, opts)

data/lib/haveapi/{params/param.rb → parameters/typed.rb}

@@ -1,5 +1,5 @@
 module HaveAPI::Parameters
-  class Param
+  class Typed
     ATTRIBUTES = %i(label desc type db_name default fill clean)
 
     attr_reader :name, :label, :desc, :type, :default
@@ -76,6 +76,9 @@ module HaveAPI::Parameters
 
       elsif @type == Integer
         raw.to_i
+      
+      elsif @type == Float
+        raw.to_f
 
       elsif @type == Boolean
         Boolean.to_b(raw)

data/lib/haveapi/params.rb

@@ -83,7 +83,7 @@ module HaveAPI
     end
 
     def optional(*args)
-      add_param(*apply(args, required: true))
+      add_param(*apply(args, required: false))
     end
 
     def string(*args)
@@ -268,7 +268,7 @@ module HaveAPI
 
     private
     def add_param(*args)
-      p = Parameters::Param.new(*args)
+      p = Parameters::Typed.new(*args)
 
       return if @include && !@include.include?(p.name)
       return if @exclude && @exclude.include?(p.name)

data/lib/haveapi/spec/api_builder.rb

@@ -0,0 +1,75 @@
+module HaveAPI::Spec
+  # Contains methods for specification of API to be used in `description` block.
+  module ApiBuilder
+    # Uses an empty module as the source for the API. It will have no resources,
+    # no actions. Version default to `1`.
+    def empty_api
+      api(Module.new)
+      default_version(1)
+    end
+
+    # Set an API module or create the API using DSL.
+    # @param mod [Module] module name or nil
+    # @yield block is executed in a dynamically created module
+    def api(mod = nil, &block)
+      unless mod
+        mod = Module.new do
+          def self.define_resource(name, superclass: Resource, &block)
+            return false if const_defined?(name)
+
+            cls = Class.new(superclass)
+            const_set(name, cls)
+            cls.class_exec(&block) if block
+            cls
+          end
+
+          module_eval(&block)
+        end
+
+        const_set(:ApiModule, mod)
+      end
+
+      opt(:api_module, mod)
+    end
+
+    # Set authentication chain.
+    def auth_chain(chain)
+      opt(:auth_chain, chain)
+    end
+
+    # Select API versions to be used.
+    def use_version(v)
+      before(:each) do
+        opts(:versions, v)
+      end
+    end
+
+    # Set default API version.
+    def default_version(v)
+      opt(:default_version, v)
+    end
+
+    # Set a custom mount path.
+    def mount_to(path)
+      opts(:mount, path)
+    end
+
+    # Login using HTTP basic.
+    def login(*credentials)
+      before(:each) do
+        basic_authorize(*credentials)
+      end
+    end
+
+    # @private
+    def opts
+      @opts
+    end
+
+    # @private
+    def opt(name, v)
+      @opts ||= {}
+      @opts[name] = v
+    end
+  end
+end

data/lib/haveapi/spec/api_response.rb

@@ -0,0 +1,41 @@
+module HaveAPI::Spec    
+  # This class wraps raw reply from the API and provides a more friendly
+  # interface.
+  class ApiResponse
+    def initialize(body)
+      @data = JSON.parse(body, symbolize_names: true)
+    end
+
+    def envelope
+      @data
+    end
+
+    def status
+      @data[:status]
+    end
+
+    def ok?
+      @data[:status]
+    end
+
+    def failed?
+      !ok?
+    end
+
+    def response
+      @data[:response]
+    end
+
+    def message
+      @data[:message]
+    end
+
+    def errors
+      @data[:errors]
+    end
+
+    def [](k)
+      @data[:response][k]
+    end
+  end
+end

data/lib/haveapi/spec/helpers.rb

@@ -1,103 +1,9 @@
 require 'rack/test'
 
 module HaveAPI
-  # Contains methods for specification of API to be used in +description+ block.
-  module ApiBuilder
-    def auth_chain(chain)
-      @auth_chain = chain
-    end
-
-    def use_version(v)
-      before(:each) do
-        @versions = v
-      end
-    end
-
-    def default_version(v)
-      @default_version = v
-    end
-
-    def mount_to(path)
-      @mount = path
-    end
-
-    def login(*credentials)
-      @username, @password = credentials
-
-      before(:each) do
-        basic_authorize(*credentials)
-      end
-    end
-  end
-
-  # Helper methods for specs.
-  module SpecMethods
-    include Rack::Test::Methods
-
-    # This class wraps raw reply from the API and provides more friendly
-    # interface.
-    class ApiResponse
-      def initialize(body)
-        @data = JSON.parse(body, symbolize_names: true)
-      end
-
-      def status
-        @data[:status]
-      end
-
-      def ok?
-        @data[:status]
-      end
-
-      def failed?
-        !ok?
-      end
-
-      def response
-        @data[:response]
-      end
-
-      def message
-        @data[:message]
-      end
-
-      def errors
-        @data[:errors]
-      end
-
-      def [](k)
-        @data[:response][k]
-      end
-    end
-
-    def app
-      api = HaveAPI::Server.new
-      api.auth_chain << @auth_chain if @auth_chain
-      api.use_version(@versions || :all)
-      api.set_default_version(@default_version) if @default_version
-      api.mount(@mount || '/')
-      api.app
-    end
-
-    # Login with HTTP basic auth.
-    def login(*credentials)
-      basic_authorize(*credentials)
-    end
-
-    # Make API request.
-    # This method is a wrapper for Rack::Test::Methods. Input parameters
-    # are encoded into JSON and sent with correct Content-Type.
-    def api(http_method, url, params={})
-      method(http_method).call(
-          url,
-          params.to_json,
-          {'Content-Type' => 'application/json'}
-      )
-    end
-
-    # Return parsed API response.
-    def api_response
-      @api_response ||= ApiResponse.new(last_response.body)
-    end
-  end
+  module Spec ; end
 end
+
+require_relative 'api_builder'
+require_relative 'api_response'
+require_relative 'spec_methods'

data/lib/haveapi/spec/mock_action.rb

@@ -0,0 +1,32 @@
+module HaveAPI::Spec
+  class MockAction
+    def initialize(test, server, action, url, v)
+      @test = test
+      @server = server
+      @action = action
+      @url = url
+      @v = v
+    end
+
+    def call(input, user: nil, &block)
+      action = @action.new(nil, @v, input, nil, HaveAPI::Context.new(
+          @server,
+          version: @v,
+          action: @action,
+          url: @url,
+          params: input,
+          user: user,
+          endpoint: true
+      ))
+
+      unless action.authorized?(user)
+        fail 'Access denied. Insufficient permissions.'
+      end
+
+      status, data, errors = action.safe_exec
+      fail (data || 'action failed') unless status
+      action.instance_exec(@test, &block)
+      data
+    end
+  end
+end

data/lib/haveapi/spec/spec_methods.rb

@@ -0,0 +1,121 @@
+module HaveAPI::Spec
+  # Helper methods for specs.
+  module SpecMethods
+    include Rack::Test::Methods
+
+    def app
+      return @api.app if @api
+
+      auth = get_opt(:auth_chain)
+      default = get_opt(:default_version)
+
+      @api = HaveAPI::Server.new(get_opt(:api_module))
+      @api.auth_chain << auth if auth
+      @api.use_version(get_opt(:versions) || :all)
+      @api.default_version = default if default
+      @api.mount(get_opt(:mount) || '/')
+      @api.app
+    end
+
+    # Login with HTTP basic auth.
+    def login(*credentials)
+      basic_authorize(*credentials)
+    end
+
+    # Make API request.
+    # This method is a wrapper for Rack::Test::Methods. Input parameters
+    # are encoded into JSON and sent with a correct Content-Type.
+    # Two modes:
+    #   http_method, url, params = {}
+    #   [resource], action, params, &block
+    def call_api(*args, &block)
+      if args[0].is_a?(::Array) || args[1].is_a?(::Symbol)
+        r_name, a_name, params = args
+
+        app
+
+        action, url = find_action(
+            (params && params[:version]) || @api.default_version,
+            r_name, a_name
+        )
+
+        method(action.http_method).call(
+            url,
+            params && params.to_json,
+            {'Content-Type' => 'application/json'}
+        )
+
+      else
+        http_method, url, params = args
+
+        method(http_method).call(
+            url,
+            params && params.to_json,
+            {'Content-Type' => 'application/json'}
+        )
+      end
+    end
+
+    # Mock action call. Note that this method does not involve rack request/response
+    # in any way. It simply creates an instance of specified action and executes it.
+    # Provided block is executed in the context of the action instance after `exec()`
+    # has been called.
+    #
+    # If `exec()` signals error, the block is not called at all, but `RuntimeError`
+    # is raised instead.
+    #
+    # Authentication does not take place. Argument `user` may be used to provide
+    # user object. That will signify that the user is authenticated and it will be passed
+    # to Action.authorize.
+    #
+    # @param r_name [Array, Symbol] path to resource in the API
+    # @param a_name [Symbol] name of wanted action
+    # @param params [Hash] a hash of parameters, must contain correct namespace
+    # @param version [any] API version, if not specified, the default version is used
+    # @param user [any] object representing authenticated user
+    # @yield [self] the block is executed in the action instance
+    def mock_action(r_name, a_name, params, version: nil, user: nil, &block)
+      app
+      v = version || @api.default_version
+      action, url = find_action(v, r_name, a_name)
+      m = MockAction.new(self, @api, action, url, v)
+      m.call(params, user: user, &block)
+    end
+
+    # Return parsed API response.
+    # @return [HaveAPI::Spec::ApiResponse]
+    def api_response
+      if last_response != @last_response
+        @last_response = last_response
+        @api_response = ApiResponse.new(last_response.body)
+
+      else
+        @api_response ||= ApiResponse.new(last_response.body)
+      end
+    end
+
+    protected
+    def get_opt(name)
+      self.class.opts && self.class.opts[name]
+    end
+
+    def find_action(v, r_name, a_name)
+      # Make sure the API is built
+      app
+
+      resources = r_name.is_a?(::Array) ? r_name : [r_name]
+
+      top = @api.routes[v]
+      
+      resources.each do |r|
+        top = top[:resources].detect do |k, _|
+          k.resource_name.to_sym == r
+        end.second
+      end
+
+      top[:actions].detect do |k, v|
+        k.to_s.demodulize.underscore.to_sym == a_name
+      end
+    end
+  end
+end

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
   PROTOCOL_VERSION = '1.0'
-  VERSION = '0.4.2'
+  VERSION = '0.5.0'
 end

data/lib/haveapi/views/main_layout.erb

@@ -20,7 +20,9 @@
     }
     .affix {
       width: inherit;
-      position: fixed;
+      height: 100%;
+	  position: fixed;
+      overflow-y: auto;
     }
     .affix-bottom {
       width: inherit;

data/lib/haveapi.rb

@@ -13,7 +13,7 @@ module HaveAPI
 end
 
 require_relative 'haveapi/params'
-require_rel 'haveapi/params/'
+require_rel 'haveapi/parameters/'
 require_rel 'haveapi/*.rb'
 require_rel 'haveapi/model_adapters/hash'
 require_rel 'haveapi/model_adapters/active_record' if ar