haveapi 0.12.1 → 0.13.0

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

@@ -1,4 +1,6 @@
 require 'haveapi/authentication/base'
+require 'haveapi/resource'
+require 'haveapi/action'
 
 module HaveAPI::Authentication
   module Token
@@ -8,15 +10,18 @@ module HaveAPI::Authentication
 
     end
 
-    # Provider for token authentication. This class has to be subclassed
-    # and implemented.
+    # Provider for token authentication.
     #
-    # Token auth contains resource token. User can request a token by calling
-    # action Resources::Token::Request. Returned token is then used for
-    # authenticating the user. Client sends the token with each request
-    # in configured #http_header or #query_parameter.
+    # This provider has to be configured using
+    # {HaveAPI::Authentication::Token::Config}.
     #
-    # Token can be revoked by calling Resources::Token::Revoke.
+    # Token auth contains API resource `token`. User can request a token by
+    # calling action `Request`. The returned token is then used for
+    # authenticating the user. Client sends the token with each request in
+    # configured {HaveAPI::Authentication::Token::Config#http_header} or
+    # {HaveAPI::Authentication::Token::Config#query_parameter}.
+    #
+    # Token can be revoked by calling action `Revoke` and renewed with `Renew`.
     #
     # === \Example usage:
     #
@@ -34,31 +39,60 @@ module HaveAPI::Authentication
     #     end
     #   end
     #
-    # Authentication provider:
-    #   class MyTokenAuth < HaveAPI::Authentication::Token::Provider
-    #     protected
-    #     def save_token(request, user, token, lifetime, interval)
-    #       user.tokens << ::Token.new(token: token, lifetime: lifetime,
-    #                                  valid_to: (lifetime != 'permanent' ? Time.now + interval : nil),
-    #                                  interval: interval, label: request.user_agent)
-    #     end
+    # Authentication provider configuration:
+    #   class MyTokenAuthConfig < HaveAPI::Authentication::Token::Config
+    #     request do
+    #       handle do |req, res|
+    #         user = ::User.find_by(login: input[:user], password: input[:password])
+    #
+    #         if user.nil?
+    #           res.error = 'invalid user or password'
+    #           next res
+    #         end
+    #
+    #         token = SecureRandom.hex(50)
+    #         valid_to =
+    #           if req.input[:lifetime] == 'permanent'
+    #             nil
+    #           else
+    #             Time.now + req.input[:interval]
+    #
+    #         user.tokens << ::Token.new(
+    #           token: token,
+    #           lifetime: req.input[:lifetime],
+    #           valid_to: valid_to,
+    #           interval: req.input[:interval],
+    #           label: req.request.user_agent,
+    #         )
     #
-    #     def revoke_token(request, user, token)
-    #       user.tokens.delete(token: token)
+    #         res.token = token
+    #         res.valid_to = valid_to
+    #         res.complete = true
+    #         res.ok
+    #       end
     #     end
     #
-    #     def renew_token(request, user, token)
-    #       t = ::Token.find_by(user: user, token: token)
+    #     renew do
+    #       handle do |req, res|
+    #         t = ::Token.find_by(user: req.user, token: req.token)
     #
-    #       if t.lifetime.start_with('renewable')
-    #         t.renew
-    #         t.save
-    #         t.valid_to
+    #         if t && t.lifetime.start_with('renewable')
+    #           t.renew
+    #           t.save
+    #           res.valid_to = t.valid_to
+    #           res.ok
+    #         else
+    #           res.error = 'unable to renew token'
+    #           res
+    #         end
     #       end
     #     end
     #
-    #     def find_user_by_credentials(request, username, password)
-    #       ::User.find_by(login: username, password: password)
+    #     revoke do
+    #       handle do |req, res|
+    #         req.user.tokens.delete(token: req.token)
+    #         res.ok
+    #       end
     #     end
     #
     #     def find_user_by_token(request, token)
@@ -79,94 +113,238 @@ module HaveAPI::Authentication
     # Finally put the provider in the authentication chain:
     #   api = HaveAPI.new(...)
     #   ...
-    #   api.auth_chain << MyTokenAuth
+    #   api.auth_chain << HaveAPI::Authentication::Token.with_config(MyTokenAuthConfig)
     class Provider < Base
+      auth_method :token
+
+      # Configure the token provider
+      # @param cfg [Config]
+      def self.with_config(cfg)
+        Module.new do
+          define_singleton_method(:new) do |*args|
+            Provider.new(*args, cfg)
+          end
+        end
+      end
+
+      attr_reader :config
+
+      def initialize(server, v, cfg)
+        @config = cfg.new(server, v)
+        super(server, v)
+      end
+
       def setup
-        Resources::Token.token_instance ||= {}
-        Resources::Token.token_instance[@version] = self
+        @server.allow_header(config.class.http_header)
+      end
 
-        @server.allow_header(http_header)
+      def resource_module
+        return @module if @module
+        provider = self
+
+        @module = Module.new do
+          const_set(:Token, provider.send(:token_resource))
+        end
       end
 
+      # Authenticate request
+      # @param request [Sinatra::Request]
       def authenticate(request)
         t = token(request)
 
-        t && find_user_by_token(request, t)
+        t && config.find_user_by_token(request, t)
       end
 
+      # Extract token from HTTP request
+      # @param request [Sinatra::Request]
+      # @return [String]
       def token(request)
-        request[query_parameter] || request.env[header_to_env]
+        request[config.class.query_parameter] || request.env[header_to_env]
       end
 
       def describe
         {
-            http_header: http_header,
-            query_parameter: query_parameter,
-            description: "The client authenticates with username and password and gets "+
-                         "a token. From this point, the password can be forgotten and "+
-                         "the token is used instead. Tokens can have different lifetimes, "+
-                         "can be renewed and revoked. The token is passed either via HTTP "+
-                         "header or query parameter."
+          http_header: config.class.http_header,
+          query_parameter: config.class.query_parameter,
+          description: "The client authenticates with credentials, usually "+
+                       "username and password, and gets a token. "+
+                       "From this point, the credentials can be forgotten and "+
+                       "the token is used instead. Tokens can have different lifetimes, "+
+                       "can be renewed and revoked. The token is passed either via HTTP "+
+                       "header or query parameter."
         }
       end
 
-      protected
-      # HTTP header that is searched for token.
-      def http_header
-        'X-HaveAPI-Auth-Token'
+      private
+      def header_to_env
+        "HTTP_#{config.class.http_header.upcase.gsub(/\-/, '_')}"
       end
 
-      # Query parameter searched for token.
-      def query_parameter
-        :_auth_token
-      end
+      def token_resource
+        provider = self
 
-      # Generate token. Implicit implementation returns token of 100 chars.
-      def generate_token
-        SecureRandom.hex(50)
-      end
+        HaveAPI::Resource.define_resource(:Token) do
+          define_singleton_method(:token_instance) { provider }
 
-      # Save generated +token+ for +user+. Token has given +lifetime+
-      # and when not permanent, also a +interval+ of validity.
-      # Returns a date time which is token expiration.
-      # It is up to the implementation of this method to remember
-      # token lifetime and interval.
-      # Must be implemented.
-      def save_token(request, user, token, lifetime, interval)
+          auth false
+          version :all
 
-      end
+          define_action(:Request) do
+            route ''
+            http_method :post
 
-      # Revoke existing +token+ for +user+.
-      # Must be implemented.
-      def revoke_token(request, user, token)
+            input(:hash) do
+              if block = provider.config.class.request.input
+                instance_exec(&block)
+              end
 
-      end
+              string :lifetime, label: 'Lifetime', required: true,
+                      choices: %i(fixed renewable_manual renewable_auto permanent),
+                      desc: <<END
+fixed - the token has a fixed validity period, it cannot be renewed
+renewable_manual - the token can be renewed, but it must be done manually via renew action
+renewable_auto - the token is renewed automatically to now+interval every time it is used
+permanent - the token will be valid forever, unless deleted
+END
+              integer :interval, label: 'Interval',
+                      desc: 'How long will requested token be valid, in seconds.',
+                      default: 60*5, fill: true
+            end
 
-      # Renew existing +token+ for +user+.
-      # Returns a date time which is token expiration.
-      # Must be implemented.
-      def renew_token(request, user, token)
+            output(:hash) do
+              string :token
+              datetime :valid_to
+              bool :complete
+              string :next_action
+            end
 
-      end
+            authorize do
+              allow
+            end
 
-      # Used by action Resources::Token::Request when the user is requesting
-      # a token. This method returns user object or nil.
-      # Must be implemented.
-      def find_user_by_credentials(request, username, password)
+            def exec
+              config = self.class.resource.token_instance.config
 
-      end
+              begin
+                result = config.class.request.handle.call(ActionRequest.new(
+                  request: request,
+                  input: input,
+                ), ActionResult.new)
+              rescue HaveAPI::AuthenticationError => e
+                error(e.message)
+              end
 
-      # Authenticate user 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.
-      def find_user_by_token(request, token)
+              unless result.ok?
+                error(result.error || 'invalid authentication credentials')
+              end
 
-      end
+              {
+                token: result.token,
+                valid_to: result.valid_to,
+                complete: result.complete?,
+                next_action: result.next_action,
+              }
+            end
+          end
 
-      private
-      def header_to_env
-        "HTTP_#{http_header.upcase.gsub(/\-/, '_')}"
+          define_action(:Revoke) do
+            http_method :post
+            auth true
+
+            authorize do
+              allow
+            end
+
+            def exec
+              provider = self.class.resource.token_instance
+              result = provider.config.class.revoke.handle.call(ActionRequest.new(
+                request: request,
+                user: current_user,
+                token: provider.token(request),
+              ), ActionResult.new)
+
+              if result.ok?
+                ok
+              else
+                error(result.error || 'revoke failed')
+              end
+            end
+          end
+
+          define_action(:Renew) do
+            http_method :post
+            auth true
+
+            output(:hash) do
+              datetime :valid_to
+            end
+
+            authorize do
+              allow
+            end
+
+            def exec
+              provider = self.class.resource.token_instance
+              result = provider.config.renew_token(ActionRequest.new(
+                request: request,
+                user: current_user,
+                token: provider.token(request),
+              ), ActionResult.new)
+
+              if result.ok?
+                {valid_to: result.valid_to}
+              else
+                error(result.error || 'renew failed')
+              end
+            end
+          end
+
+          provider.config.class.actions.each do |name, config|
+            define_action(:"#{name.to_s.capitalize}") do
+              http_method :post
+              auth false
+
+              input(:hash) do
+                string :token, required: true
+                instance_exec(&config.input) if config.input
+              end
+
+              output(:hash) do
+                string :token
+                datetime :valid_to
+                bool :complete
+                string :next_action
+              end
+
+              authorize do
+                allow
+              end
+
+              define_method(:exec) do
+                begin
+                  result = config.handle.call(ActionRequest.new(
+                    request: request,
+                    input: input,
+                    token: input[:token],
+                  ), ActionResult.new)
+                rescue HaveAPI::AuthenticationError => e
+                  error(e.message)
+                end
+
+                unless result.ok?
+                  error(result.error || 'authentication failed')
+                end
+
+                {
+                  token: result.token,
+                  valid_to: result.valid_to,
+                  complete: result.complete?,
+                  next_action: result.next_action,
+                }
+              end
+            end
+          end
+        end
       end
     end
   end

data/lib/haveapi/authentication/token.rb

@@ -0,0 +1,9 @@
+module HaveAPI::Authentication
+  module Token
+    # Configure the token provider
+    # @param cfg [Config]
+    def self.with_config(cfg)
+      Provider.with_config(cfg)
+    end
+  end
+end

data/lib/haveapi/client_examples/curl.rb

@@ -12,7 +12,7 @@ module HaveAPI::ClientExamples
     end
 
     def auth(method, desc)
-      login = {login: 'user', password: 'password', lifetime: 'fixed'}
+      login = {user: 'user', password: 'password', lifetime: 'fixed'}
 
       case method
       when :basic
@@ -50,8 +50,8 @@ END
           base_url,
           resolve_path(
               action[:method],
-              action[:url],
-              sample[:url_params] || [],
+              action[:path],
+              sample[:path_params] || [],
               sample[:request]
           )
       )

data/lib/haveapi/client_examples/fs_client.rb

@@ -43,13 +43,13 @@ END
       path = [mountpoint].concat(resource_path)
 
       unless class_action?
-        if !sample[:url_params] || sample[:url_params].empty?
+        if !sample[:path_params] || sample[:path_params].empty?
           fail "example {#{sample}} of action #{resource_path.join('.')}"+
                ".#{action_name} is for an instance action but does not include "+
                "URL parameters"
         end
 
-        path << sample[:url_params].first.to_s
+        path << sample[:path_params].first.to_s
       end
 
       path << 'actions' << action_name
@@ -112,7 +112,7 @@ END
     end
 
     def class_action?
-      action[:url].index(/:[a-zA-Z\-_]+/).nil?
+      action[:path].index(/:[a-zA-Z\-_]+/).nil?
     end
   end
 end

data/lib/haveapi/client_examples/http.rb

@@ -33,7 +33,7 @@ POST /_auth/token/tokens HTTP/1.1
 Host: #{host}
 Content-Type: application/json
 
-#{JSON.pretty_generate({token: {login: 'user', password: 'secret', lifetime: 'fixed'}})}
+#{JSON.pretty_generate({token: {user: 'user', password: 'secret', lifetime: 'fixed'}})}
 END
       end
     end
@@ -41,8 +41,8 @@ END
     def request(sample)
       path = resolve_path(
           action[:method],
-          action[:url],
-          sample[:url_params] || [],
+          action[:path],
+          sample[:path_params] || [],
           sample[:request]
       )
 
@@ -74,11 +74,11 @@ END
       res
     end
 
-    def resolve_path(method, url, url_params, input_params)
-      ret = url.clone
+    def resolve_path(method, path, path_params, input_params)
+      ret = path.clone
 
-      url_params.each do |v|
-        ret.sub!(/:[a-zA-Z\-_]+/, v.to_s)
+      path_params.each do |v|
+        ret.sub!(/\{[a-zA-Z\-_]+\}/, v.to_s)
       end
 
       return ret if method != 'GET' || !input_params || input_params.empty?

data/lib/haveapi/client_examples/js_client.rb

@@ -56,7 +56,7 @@ END
     def example(sample)
       args = []
 
-      args.concat(sample[:url_params]) if sample[:url_params]
+      args.concat(sample[:path_params]) if sample[:path_params]
 
       if sample[:request] && !sample[:request].empty?
         args << JSON.pretty_generate(sample[:request])

data/lib/haveapi/client_examples/php_client.rb

@@ -39,7 +39,7 @@ END
     def example(sample)
       args = []
 
-      args.concat(sample[:url_params]) if sample[:url_params]
+      args.concat(sample[:path_params]) if sample[:path_params]
 
       if sample[:request] && !sample[:request].empty?
         args << format_parameters(:input, sample[:request])

data/lib/haveapi/client_examples/ruby_cli.rb

@@ -47,7 +47,7 @@ END
       cmd = [init]
       cmd << resource_path.join('.')
       cmd << action_name
-      cmd.concat(sample[:url_params]) if sample[:url_params]
+      cmd.concat(sample[:path_params]) if sample[:path_params]
 
       if sample[:request] && !sample[:request].empty?
         cmd << "-- \\\n"

data/lib/haveapi/client_examples/ruby_client.rb

@@ -42,7 +42,7 @@ END
     def example(sample)
       args = []
 
-      args.concat(sample[:url_params]) if sample[:url_params]
+      args.concat(sample[:path_params]) if sample[:path_params]
 
       if sample[:request] && !sample[:request].empty?
         args << PP.pp(sample[:request], '').strip

data/lib/haveapi/context.rb

@@ -1,18 +1,18 @@
 module HaveAPI
   class Context
-    attr_accessor :server, :version, :request, :resource, :action, :url, :args,
+    attr_accessor :server, :version, :request, :resource, :action, :path, :args,
                   :params, :current_user, :authorization, :endpoint,
                   :action_instance, :action_prepare, :layout
 
     def initialize(server, version: nil, request: nil, resource: [], action: nil,
-                  url: nil, args: nil, params: nil, user: nil,
+                  path: nil, args: nil, params: nil, user: nil,
                   authorization: nil, endpoint: nil)
       @server = server
       @version = version
       @request = request
       @resource = resource
       @action = action
-      @url = url
+      @path = path
       @args = args
       @params = params
       @current_user = user
@@ -20,10 +20,10 @@ module HaveAPI
       @endpoint = endpoint
     end
 
-    def resolved_url
-      return @url unless @args
+    def resolved_path
+      return @path unless @args
 
-      ret = @url.dup
+      ret = @path.dup
 
       @args.each do |arg|
         resolve_arg!(ret, arg)
@@ -32,7 +32,7 @@ module HaveAPI
       ret
     end
 
-    def url_for(action, args=nil)
+    def path_for(action, args=nil)
       top_module = Kernel
       top_route = @server.routes[@version]
 
@@ -60,20 +60,20 @@ module HaveAPI
       ret
     end
 
-    def call_url_params(action, obj)
-      ret = params && action.resolve_url_params(obj)
+    def call_path_params(action, obj)
+      ret = params && action.resolve_path_params(obj)
 
       return [ret] if ret && !ret.is_a?(Array)
       ret
     end
 
-    def url_with_params(action, obj)
-      url_for(action, call_url_params(action, obj))
+    def path_with_params(action, obj)
+      path_for(action, call_path_params(action, obj))
     end
 
     private
-    def resolve_arg!(url, arg)
-      url.sub!(/:[a-zA-Z\-_]+/, arg.to_s)
+    def resolve_arg!(path, arg)
+      path.sub!(/\{[a-zA-Z\-_]+\}/, arg.to_s)
     end
   end
 end

data/lib/haveapi/example.rb

@@ -8,8 +8,8 @@ module HaveAPI
       @authorization = block
     end
 
-    def url_params(*params)
-      @url_params = params
+    def path_params(*params)
+      @path_params = params
     end
 
     def request(f)
@@ -60,7 +60,7 @@ module HaveAPI
         {
             title: @title,
             comment: @comment,
-            url_params: @url_params,
+            path_params: @path_params,
             request: filter_input_params(context, @request),
             response: filter_output_params(context, @response),
             status: @status.nil? ? true : @status,

data/lib/haveapi/exceptions.rb

@@ -4,4 +4,6 @@ module HaveAPI
   class BuildError < StandardError
     include Nesty::NestedError
   end
+
+  class AuthenticationError < StandardError ; end
 end

data/lib/haveapi/extensions/exception_mailer.rb

@@ -58,6 +58,13 @@ module HaveAPI::Extensions
 
       env = context.request.env
 
+      user =
+        if context.current_user.respond_to?(:id)
+          context.current_user.id
+        else
+          context.current_user
+        end
+
       mail(context, exception, TEMPLATE.result(binding))
     end
 
@@ -222,7 +229,7 @@ module HaveAPI::Extensions
           </tr>
           <tr>
             <th>User</th>
-            <td><%=h context.request.current_user %></td>
+            <td><%=h user %></td>
           </tr>
         </table>
         <div class="clear"></div>