haveapi 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c535654ced1007d57fa8d9c619ae9c17e9c3feea7ff45635579af316c2d18d85
-  data.tar.gz: 6de601f8d1ccb5de8343a517172f91f439c84c854439914334cab6aba8905a7b
+  metadata.gz: 5e44e03fec908d742be4499f22c97f16453cd53bd4a23a14928af94d3456bea2
+  data.tar.gz: '0339228a0003baae1528050052b930acedbad51651893e4ce8329945bf98a5f0'
 SHA512:
-  metadata.gz: f06faee46f829bc5c6facba8587317f3db4a08d293ed0981a3cabb9c521e877e886a90038f552974e14305333d18d5d7e4a21e31812c272f524eb871b102f67d
-  data.tar.gz: 1876ae96a3979b8e34f4e3c582450f73c3573431ba671ef0964e866214e7d59e74e7e2ecc15e8a42a4925c89f2c9be730749f16d87dc0a6c9c6536b7c1823970
+  metadata.gz: 157bfeeaf24ea9304e96051c4a05e9454cdfbb818ac7476efbb7e587547305bbd1cb54bb9acfebf0f7ac3a8b553766b7527fa80a8af575d306df051e46394be6
+  data.tar.gz: 1dbfe70f5b5e7f15c1cc779df344a09afcc0912df4a74ac27ff51f45f65f3eef574dd66ff0fee80c7f6b44f093491c0242494fbd52af7b46a1674ad3971f1933

data/doc/protocol.md

@@ -94,14 +94,29 @@ HTTP basic authentication needs no other configuration, only informs about its p
 
     "basic": {}
 
+HTTP basic authentication does not support multi-factor authentication.
+
 ### Token authentication
-Token authentication contains a resource ``token``, that is used
-to acquire and revoke token.
+Token authentication contains resource ``token``, that is used to acquire
+and revoke tokens.
+
+Tokens are acquired by action ``request``, in which the client provides arbitrary
+login credentials. If the login credentials match, the server either concludes
+the authentication process, or multiple authentication steps may be necessary.
+
+For single-step authentication processses, action ``request`` returns the
+token and its validity period. If multiple authentication steps are necessary,
+the server signals this by returning ``complete = true``. The client then has
+to call the next authentication step, which is an action on the ``token``
+resource, as returned in ``next_action``.
 
-Token is acquired by action ``request``. The client provides login and password and gets a token
-that is used afterwards. Token has a validity period, which may also be infinity.
+Tokens are returned in both cases. If the authentication is finished, the token
+is then used for authenticating further requests. If the authentication continues,
+the token is used to authenticate the next authentication request, which then
+returns another token.
 
-Token can be revoked by calling the ``revoke`` action.
+After the authentication is complete, acquired tokens can be renewed using action
+``renew`` and revoked by calling the ``revoke`` action.
 
     "token": {
         "http_header": "<name of HTTP header to transfer token in, by default X-HaveAPI-Auth-Token>",
@@ -113,7 +128,7 @@ Token can be revoked by calling the ``revoke`` action.
                     "input": {
                         ...
                         "parameters": {
-                            "login": ...
+                            "user": ...
                             "password": ...
                             "lifetime": ...
                             "interval": ...
@@ -125,6 +140,8 @@ Token can be revoked by calling the ``revoke`` action.
                         "parameters": {
                             "token": ...
                             "valid_to": ...
+			    "complete": true/false
+			    "next_action": ...
                         },
                         ...
                     },
@@ -176,7 +193,7 @@ Every action is described as:
             ... list of examples ...
         ],
 	"meta": ... metadata ...,
-        "url": "URL for this action",
+        "path": "URL for this action",
         "method": "HTTP method to be used",
         "help": "URL to get this very description of the action"
     }
@@ -365,12 +382,12 @@ This is used for associations between resources, e.g. car has a wheel.
         "value_id": "<name of a parameter that is used as an id>",
         "value_label": "<name of a parameter that is used as a value>",
         "value": {
-            "url": "URL to 'show' action of associated resource",
+            "path": "URL to 'show' action of associated resource",
             "method": "HTTP method to use",
             "help": "URL to get the associated resource's 'show' description"
         },
         "choices": {
-            "url": "URL to action that returns a list of possible associations",
+            "path": "URL to action that returns a list of possible associations",
             "method": "HTTP method to use",
             "help": "URL to description of the list action"
         }
@@ -391,7 +408,7 @@ render them according to its syntax.
 
     {
         "title": "A title",
-        "url_params: [ ... array of integers ... ],
+        "path_params: [ ... array of integers ... ],
         "request": {
             ... a hash of request parameters ...
         },

data/haveapi.gemspec

@@ -5,7 +5,6 @@ require 'haveapi/version'
 Gem::Specification.new do |s|
   s.name        = 'haveapi'
   s.version     = HaveAPI::VERSION
-  s.date        = '2017-11-27'
   s.summary     =
   s.description = 'Framework for creating self-describing APIs'
   s.authors     = 'Jakub Skokan'
@@ -24,6 +23,6 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'rake'
   s.add_runtime_dependency 'github-markdown'
   s.add_runtime_dependency 'nesty', '~> 1.0'
-  s.add_runtime_dependency 'haveapi-client', '~> 0.12.0'
+  s.add_runtime_dependency 'haveapi-client', '~> 0.13.0'
   s.add_runtime_dependency 'mail'
 end

data/lib/haveapi/action.rb

@@ -31,7 +31,8 @@ module HaveAPI
     attr_accessor :flags
 
     class << self
-      attr_reader :resource, :authorization, :examples
+      attr_accessor :resource
+      attr_reader :authorization, :examples
 
       def inherited(subclass)
         # puts "Action.inherited called #{subclass} from #{to_s}"
@@ -45,7 +46,7 @@ module HaveAPI
       end
 
       def delayed_inherited(subclass)
-        resource = Kernel.const_get(subclass.to_s.deconstantize)
+        resource = subclass.resource || Kernel.const_get(subclass.to_s.deconstantize)
 
         inherit_attrs(subclass)
         inherit_attrs_from_resource(subclass, resource, [:auth])
@@ -177,14 +178,29 @@ module HaveAPI
         @examples << e
       end
 
+      def action_name
+        (@action_name ? @action_name.to_s : to_s).demodulize
+      end
+
+      def action_name=(name)
+        @action_name = name
+      end
+
       def build_route(prefix)
-        route = @route || to_s.demodulize.underscore
+        route = @route || action_name.underscore
+          if @route
+            @route
+          elsif action_name
+            action_name.to_s.demodulize.underscore
+          else
+            to_s.demodulize.underscore
+          end
 
         if !route.is_a?(String) && route.respond_to?(:call)
           route = route.call(self.resource)
         end
 
-        prefix + route % {resource: self.resource.to_s.demodulize.underscore}
+        prefix + route % {resource: self.resource.resource_name.underscore}
       end
 
       def describe(context)
@@ -214,9 +230,9 @@ module HaveAPI
             output: @output ? @output.describe(context) : {parameters: {}},
             meta: @meta ? @meta.merge(@meta) { |_, v| v && v.describe(context) } : nil,
             examples: @examples ? @examples.describe(context) : [],
-            url: context.resolved_url,
+            path: context.resolved_path,
             method: route_method,
-            help: "#{context.url}?method=#{route_method}"
+            help: "#{context.path}?method=#{route_method}"
         }
       end
 
@@ -245,7 +261,7 @@ module HaveAPI
         ret
       end
 
-      def resolve_url_params(object)
+      def resolve_path_params(object)
         if self.resolve
           self.resolve.call(object)
 

data/lib/haveapi/actions/default.rb

@@ -38,18 +38,18 @@ module HaveAPI
       end
 
       class Show < Action
-        route ->(r){ r.singular ? '' : ':%{resource}_id' }
+        route ->(r){ r.singular ? '' : '{%{resource}_id}' }
         http_method :get
         aliases %i(find)
       end
 
       class Update < Action
-        route ->(r){ r.singular ? '' : ':%{resource}_id' }
+        route ->(r){ r.singular ? '' : '{%{resource}_id}' }
         http_method :put
       end
 
       class Delete < Action
-        route ->(r){ r.singular ? '' : ':%{resource}_id' }
+        route ->(r){ r.singular ? '' : '{%{resource}_id}' }
         http_method :delete
         aliases %i(destroy)
       end

data/lib/haveapi/authentication/base.rb

@@ -2,14 +2,32 @@ module HaveAPI
   module Authentication
     # Base class for authentication providers.
     class Base
-      attr_accessor :name, :resources
+      # Get or set auth method name
+      # @param v [Symbol, nil]
+      # @return [Symbol]
+      def self.auth_method(v = nil)
+        if v
+          @auth_method = v
+        else
+          @auth_method || name.split('::').last.underscore.to_sym
+        end
+      end
+
+      # @return [Symbol]
+      attr_reader :name
 
       def initialize(server, v)
+        @name = self.class.auth_method
         @server = server
         @version = v
         setup
       end
 
+      # @return [Module, nil]
+      def resource_module
+        nil
+      end
+
       # Reimplement this method in your authentication provider.
       # +request+ is passed directly from Sinatra.
       def authenticate(request)

data/lib/haveapi/authentication/basic/provider.rb

@@ -17,12 +17,18 @@ module HaveAPI::Authentication
     #   ...
     #   api.auth_chain << MyBasicAuth
     class Provider < Base
+      auth_method :basic
+
       def authenticate(request)
         user = nil
 
         auth = Rack::Auth::Basic::Request.new(request.env)
         if auth.provided? && auth.basic? && auth.credentials
-          user = find_user(request, *auth.credentials)
+          begin
+            user = find_user(request, *auth.credentials)
+          rescue HaveAPI::AuthenticationError
+            user = nil
+          end
         end
 
         user

data/lib/haveapi/authentication/chain.rb

@@ -50,17 +50,17 @@ module HaveAPI::Authentication
 
     def describe(context)
       ret = {}
-      
+
       return ret unless @instances[context.version]
 
       @instances[context.version].each do |provider|
         ret[provider.name] = provider.describe
 
-        if provider.resources
+        if provider.resource_module
           ret[provider.name][:resources] = {}
 
           @server.routes[context.version][:authentication][provider.name][:resources].each do |r, children|
-            ret[provider.name][:resources][r.to_s.demodulize.underscore.to_sym] = r.describe(children, context)
+            ret[provider.name][:resources][r.resource_name.underscore.to_sym] = r.describe(children, context)
           end
         end
       end
@@ -97,17 +97,15 @@ module HaveAPI::Authentication
     protected
     def register_provider(v, p)
       instance = p.new(@server, v)
-      parts = p.superclass.name.split('::')
-
-      instance.name = parts[-2].underscore.to_sym
-
       @instances[v] << instance
 
-      provider = Kernel.const_get(parts[0..-2].join('::'))
-
-      if provider.const_defined?('Resources')
-        instance.resources = provider.const_get('Resources')
-        @server.add_auth_module(v, instance.name, instance.resources, prefix: parts[-2].underscore)
+      if resource_module = instance.resource_module
+        @server.add_auth_module(
+          v,
+          instance.name,
+          resource_module,
+          prefix: instance.name.to_s,
+        )
       end
     end
   end

data/lib/haveapi/authentication/token/action_config.rb

@@ -0,0 +1,53 @@
+module HaveAPI::Authentication
+  module Token
+    class ActionConfig
+      # @param block [Proc]
+      # @param opts [Hash]
+      # @option opts [Boolean] :input
+      # @option opts [Boolean] :handle
+      def initialize(block, opts = {})
+        @block = block
+        @opts = with_defaults(opts)
+        update(block)
+      end
+
+      # @param block [Proc]
+      def update(block)
+        instance_exec(&block)
+      end
+
+      # Configure input parameters in the context of {HaveAPI::Params}
+      def input(&block)
+        if block && check!(:input)
+          @input = block
+        else
+          @input
+        end
+      end
+
+      # Handle the action
+      # @yieldparam request [ActionRequest]
+      # @yieldparam result [ActionResult]
+      # @yieldreturn [ActionResult]
+      def handle(&block)
+        if block && check!(:handle)
+          @handle = block
+        else
+          @handle
+        end
+      end
+
+      private
+      def check!(name)
+        fail "#{name} cannot be configured" unless @opts[name]
+        true
+      end
+
+      def with_defaults(opts)
+        Hash[%i(input handle).map do |v|
+          [v, opts.has_key?(v) ? opts[v] : true]
+        end]
+      end
+    end
+  end
+end

data/lib/haveapi/authentication/token/action_request.rb

@@ -0,0 +1,23 @@
+module HaveAPI::Authentication
+  module Token
+    class ActionRequest
+      # @return [Sinatra::Request]
+      attr_reader :request
+
+      # @return [Hash]
+      attr_reader :input
+
+      # @return [Object, nil]
+      attr_reader :user
+
+      # @return [String, nil]
+      attr_reader :token
+
+      def initialize(opts = {})
+        opts.each do |k, v|
+          instance_variable_set(:"@#{k}", v)
+        end
+      end
+    end
+  end
+end

data/lib/haveapi/authentication/token/action_result.rb

@@ -0,0 +1,42 @@
+module HaveAPI::Authentication
+  module Token
+    class ActionResult
+      # @param complete [Boolean]
+      # @return [Boolean]
+      attr_accessor :complete
+
+      # @param error [String]
+      # @return [String, nil]
+      attr_accessor :error
+
+      # @param token [String]
+      # @return [String, nil]
+      attr_accessor :token
+
+      # @param valid_to [Time]
+      # @return [Time, nil]
+      attr_accessor :valid_to
+
+      # @param next_action [String]
+      # @return [String, nil]
+      attr_accessor :next_action
+
+      def initialize
+        @ok = false
+      end
+
+      def ok
+        @ok = true
+        self
+      end
+
+      def ok?
+        @ok && @error.nil?
+      end
+
+      def complete?
+        @complete ? true : false
+      end
+    end
+  end
+end

data/lib/haveapi/authentication/token/config.rb

@@ -0,0 +1,115 @@
+module HaveAPI::Authentication
+  module Token
+    # Configuration for {HaveAPI::Authentication::Token::Provider}
+    #
+    # Create a subclass and use with {HaveAPI::Authentication::Token#with_config}.
+    class Config
+      class << self
+        # Configure token request action
+        def request(&block)
+          if block
+            if @request
+              @request.update(block)
+            else
+              @request = ActionConfig.new(block)
+            end
+          else
+            @request
+          end
+        end
+
+        %i(renew revoke).each do |name|
+          # Configuration method
+          define_method(name) do |&block|
+            var = :"@#{name}"
+            val = instance_variable_get(var)
+
+            if block
+              if val
+                val.update(block)
+              else
+                instance_variable_set(var, ActionConfig.new(block, input: false))
+              end
+            else
+              val
+            end
+          end
+        end
+
+        # @param name [Symbol]
+        def action(name, &block)
+          @actions ||= {}
+          @actions[name] = ActionConfig.new(block)
+        end
+
+        # @return [Hash]
+        def actions
+          @actions || {}
+        end
+
+        # HTTP header that is searched for token
+        # @param header [String, nil]
+        # @return [String]
+        def http_header(header = nil)
+          if header
+            @http_header = header
+          else
+            @http_header || 'X-HaveAPI-Auth-Token'
+          end
+        end
+
+        # Query parameter searched for token
+        # @param param [Symbol]
+        # @return [Symbol]
+        def query_parameter(param = nil)
+          if param
+            @query_param = param
+          else
+            @query_param || :_auth_token
+          end
+        end
+
+        def inherited(subclass)
+          # Default request
+          subclass.request do
+            input do
+              string :user, label: 'User', required: true
+              password :password, label: 'Password', required: true
+            end
+
+            handle do
+              raise NotImplementedError
+            end
+          end
+
+          # Default renew and revoke
+          %i(renew revoke).each do |name|
+            subclass.send(name) do
+              handle do
+                raise NotImplementedError
+              end
+            end
+          end
+        end
+      end
+
+      def initialize(server, v)
+        @server = server
+        @version = v
+      end
+
+      # Authenticate request by `token`
+      #
+      # Return user object or nil.
+      # If the token was created as auto-renewable, this method
+      # is responsible for its renewal.
+      # Must be implemented.
+      # @param request [Sinatra::Request]
+      # @param token [String]
+      # @return [Object, nil]
+      def find_user_by_token(request, token)
+
+      end
+    end
+  end
+end