haveapi 0.3.0

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

@@ -0,0 +1,37 @@
+module HaveAPI::Authentication
+  module Basic
+    # HTTP basic authentication provider.
+    #
+    # Example usage:
+    #   class MyBasicAuth < HaveAPI::Authentication::Basic::Provider
+    #     protected
+    #     def find_user(request, username, password)
+    #       ::User.find_by(login: username, password: password)
+    #     end
+    #   end
+    #
+    # Finally put the provider in the authentication chain:
+    #   api = HaveAPI.new(...)
+    #   ...
+    #   api.auth_chain << MyBasicAuth
+    class Provider < Base
+      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)
+        end
+
+        user
+      end
+
+      protected
+      # Reimplement this method. It has to return an authenticated
+      # user or nil.
+      def find_user(request, username, password)
+
+      end
+    end
+  end
+end

data/lib/haveapi/authentication/chain.rb

@@ -0,0 +1,110 @@
+module HaveAPI::Authentication
+  # Authentication chain.
+  # At every request, #authenticate is called to authenticate user.
+  class Chain
+    def initialize(server)
+      @server = server
+      @chain = {}
+      @instances = {}
+    end
+
+    def setup(versions)
+      versions.each do |v|
+        @instances[v] ||= []
+
+        @chain[v] && @chain[v].each { |p| register_provider(v, p) }
+      end
+
+      if @chain[:all]
+        @chain[:all].each do |p|
+          @instances.each_key { |v| register_provider(v, p) }
+        end
+      end
+
+      # @chain.each do |p|
+      #   @instances << p.new(@server)
+      #
+      #   parts = p.to_s.split('::')
+      #   mod = Kernel.const_get((parts[0..-2] << 'Resources').join('::'))
+      #
+      #   @server.add_module(mod, prefix: parts[-2].tableize) if mod
+      # end
+    end
+
+    # Iterate through authentication providers registered for version +v+
+    # until authentication is successful or the end is reached and user
+    # is not authenticated.
+    # Authentication provider can deny the user access by calling Base#deny.
+    def authenticate(v, *args)
+      catch(:return) do
+        @instances[v].each do |provider|
+          u = provider.authenticate(*args)
+          return u if u
+        end
+      end
+
+      nil
+    end
+
+    def describe(context)
+      ret = {}
+
+      @instances[context.version].each do |provider|
+        ret[provider.name] = provider.describe
+
+        if provider.resources
+          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)
+          end
+        end
+      end
+
+      ret
+    end
+
+    # Return provider list for version +v+.
+    # Used for registering providers to specific version, e.g.
+    #   api.auth_chain[1] << MyAuthProvider
+    def [](v)
+      @chain[v] ||= []
+      @chain[v]
+    end
+
+    # Register authentication +provider+ for all available API versions.
+    # +provider+ may also be an Array of providers.
+    def <<(provider)
+      @chain[:all] ||= []
+
+      if provider.is_a?(Array)
+        provider.each { |p| @chain[:all] << p }
+      else
+        @chain[:all] << provider
+      end
+
+      self
+    end
+
+    def empty?
+      @chain.empty?
+    end
+
+    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)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,166 @@
+module HaveAPI::Authentication
+  module Token
+    # Exception that has to be raised when generated token already exists.
+    # Provider will catch it and generate another token.
+    class TokenExists < Exception
+
+    end
+
+    # Provider for token authentication. This class has to be subclassed
+    # and implemented.
+    #
+    # 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.
+    #
+    # Token can be revoked by calling Resources::Token::Revoke.
+    #
+    # === \Example usage:
+    #
+    # \Token model:
+    #   class ApiToken < ActiveRecord::Base
+    #     belongs_to :user
+    #
+    #     validates :user_id, :token, presence: true
+    #     validates :token, length: {is: 100}
+    #
+    #     enum lifetime: %i(fixed renewable_manual renewable_auto permanent)
+    #
+    #     def renew
+    #       self.valid_to = Time.now + interval
+    #     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
+    #
+    #     def revoke_token(request, user, token)
+    #       user.tokens.delete(token: token)
+    #     end
+    #
+    #     def renew_token(request, user, token)
+    #       t = ::Token.find_by(user: user, token: token)
+    #
+    #       if t.lifetime.start_with('renewable')
+    #         t.renew
+    #         t.save
+    #         t.valid_to
+    #       end
+    #     end
+    #
+    #     def find_user_by_credentials(request, username, password)
+    #       ::User.find_by(login: username, password: password)
+    #     end
+    #
+    #     def find_user_by_token(request, token)
+    #       t = ::Token.find_by(token: token)
+    #
+    #       if t
+    #         # Renew the token if needed
+    #         if t.lifetime == 'renewable_auto'
+    #           t.renew
+    #           t.save
+    #         end
+    #
+    #         t.user # return the user
+    #       end
+    #     end
+    #   end
+    #
+    # Finally put the provider in the authentication chain:
+    #   api = HaveAPI.new(...)
+    #   ...
+    #   api.auth_chain << MyTokenAuth
+    class Provider < Base
+      def setup
+        Resources::Token.token_instance ||= {}
+        Resources::Token.token_instance[@version] = self
+
+        @server.allow_header(http_header)
+      end
+
+      def authenticate(request)
+        t = token(request)
+
+        t && find_user_by_token(request, t)
+      end
+
+      def token(request)
+        request[query_parameter] || request.env[header_to_env]
+      end
+
+      def describe
+        {
+            http_header: http_header,
+            query_parameter: query_parameter,
+        }
+      end
+
+      protected
+      # HTTP header that is searched for token.
+      def http_header
+        'X-HaveAPI-Auth-Token'
+      end
+
+      # Query parameter searched for token.
+      def query_parameter
+        :_auth_token
+      end
+
+      # Generate token. Implicit implementation returns token of 100 chars.
+      def generate_token
+        SecureRandom.hex(50)
+      end
+
+      # 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)
+
+      end
+
+      # Revoke existing +token+ for +user+.
+      # Must be implemented.
+      def revoke_token(request, user, token)
+
+      end
+
+      # Renew existing +token+ for +user+.
+      # Returns a date time which is token expiration.
+      # Must be implemented.
+      def renew_token(request, user, token)
+
+      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)
+
+      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)
+
+      end
+
+      private
+      def header_to_env
+        "HTTP_#{http_header.upcase.gsub(/\-/, '_')}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+module HaveAPI::Authentication::Token
+  module Resources
+    class Token < HaveAPI::Resource
+      auth false
+      version :all
+
+      class << self
+        attr_accessor :token_instance
+      end
+
+      class Request < HaveAPI::Action
+        route ''
+        http_method :post
+
+        input(:hash) do
+          string :login, label: 'Login', required: true
+          string :password, label: 'Password', required: true
+          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
+
+        output(:hash) do
+          string :token
+          datetime :valid_to
+        end
+
+        authorize do
+          allow
+        end
+
+        def exec
+          klass = self.class.resource.token_instance[@version]
+
+          user = klass.send(
+              :find_user_by_credentials,
+              request,
+              input[:login],
+              input[:password]
+          )
+          error('bad login or password') unless user
+
+          token = expiration = nil
+
+          loop do
+            begin
+              token = klass.send(:generate_token)
+              expiration = klass.send(:save_token,
+                                      @request,
+                                      user,
+                                      token,
+                                      params[:token][:lifetime],
+                                      params[:token][:interval])
+              break
+
+            rescue TokenExists
+              next
+            end
+          end
+
+          {token: token, valid_to: expiration}
+        end
+      end
+
+      class Revoke < HaveAPI::Action
+        # route ''
+        http_method :post
+        auth true
+
+        authorize do
+          allow
+        end
+
+        def exec
+          klass = self.class.resource.token_instance[@version]
+          klass.send(:revoke_token, request, current_user, klass.token(request))
+        end
+      end
+
+      class Renew < HaveAPI::Action
+        http_method :post
+        auth true
+
+        output(:hash) do
+          datetime :valid_to
+        end
+
+        authorize do
+          allow
+        end
+
+        def exec
+          klass = self.class.resource.token_instance[@version]
+          klass.send(:renew_token, request, current_user, klass.token(request))
+        end
+      end
+    end
+  end
+end

data/lib/haveapi/authorization.rb

@@ -0,0 +1,108 @@
+module HaveAPI
+  class Authorization
+    def initialize(&block)
+      @block = block
+    end
+
+    # Returns true if user is authorized.
+    # Block must call allow to authorize user, default rule is deny.
+    def authorized?(user)
+      @restrict = []
+
+      catch(:rule) do
+        instance_exec(user, &@block) if @block
+        deny # will not be called if block throws allow
+      end
+    end
+
+    # Apply restrictions on query which selects objects from database.
+    # Most common usage is restrict user to access only objects he owns.
+    def restrict(*args)
+      @restrict << args.first
+    end
+
+    # Restrict parameters client can set/change.
+    # [whitelist]  allow only listed parameters
+    # [blacklist]  allow all parameters except listed ones
+    def input(whitelist: nil, blacklist: nil)
+      @input = {
+          whitelist: whitelist,
+          blacklist: blacklist,
+      }
+    end
+
+    # Restrict parameters client can retrieve.
+    # [whitelist]  allow only listed parameters
+    # [blacklist]  allow all parameters except listed ones
+    def output(whitelist: nil, blacklist: nil)
+      @output = {
+          whitelist: whitelist,
+          blacklist: blacklist,
+      }
+    end
+
+    def allow
+      throw(:rule, true)
+    end
+
+    def deny
+      throw(:rule, false)
+    end
+
+    def restrictions
+      ret = {}
+
+      @restrict.each do |r|
+        ret.update(r)
+      end
+
+      ret
+    end
+
+    def filter_input(input, params)
+      filter_inner(input, @input, params, false)
+    end
+
+    def filter_output(output, params, format = false)
+      filter_inner(output, @output, params, format)
+    end
+
+    private
+    def filter_inner(allowed_params, direction, params, format)
+      allowed = {}
+
+      allowed_params.each do |p|
+        if params.has_param?(p.name)
+          allowed[p.name] = format ? p.format_output(params[p.name]) : params[p.name]
+
+        elsif params.has_param?(p.name.to_s) # FIXME: remove double checking
+          allowed[p.name] = format ? p.format_output(params[p.name.to_s]) : params[p.name.to_s]
+        end
+      end
+
+      return allowed unless direction
+
+      if direction[:whitelist]
+        ret = {}
+
+        direction[:whitelist].each do |p|
+          ret[p] = allowed[p] if allowed && allowed[p]
+        end
+
+        ret
+
+      elsif direction[:blacklist]
+        ret = allowed.dup
+
+        direction[:blacklist].each do |p|
+          ret.delete(p)
+        end
+
+        ret
+
+      else
+        allowed
+      end
+    end
+  end
+end

data/lib/haveapi/common.rb

@@ -0,0 +1,38 @@
+module HaveAPI
+  class Common
+    class << self
+      attr_accessor :custom_attrs
+
+      def has_attr(name, default=nil)
+        @custom_attrs ||= []
+        @custom_attrs << name
+
+        instance_variable_set("@#{name}", default)
+
+        self.class.send(:define_method, name) do |value=nil|
+          if value.nil?
+            instance_variable_get("@#{name}")
+          else
+            instance_variable_set("@#{name}", value)
+          end
+        end
+      end
+
+      # Called before subclass defines it's attributes (before has_attr or custom
+      # attr setting), so copy defaults from parent and let it override it.
+      def inherit_attrs(subclass)
+        return unless @custom_attrs
+
+        subclass.custom_attrs = []
+
+        @custom_attrs.each do |attr|
+          # puts "#{subclass}: Inherit #{attr} = #{instance_variable_get("@#{attr}")}"
+          subclass.method(attr).call(instance_variable_get("@#{attr}"))
+          subclass.custom_attrs << attr
+        end
+      end
+    end
+
+    has_attr :obj_type
+  end
+end

data/lib/haveapi/context.rb

@@ -0,0 +1,78 @@
+module HaveAPI
+  class Context
+    attr_accessor :server, :version, :resource, :action, :url, :args,
+                  :params, :current_user, :authorization, :endpoint,
+                  :action_instance, :action_prepare, :layout
+
+    def initialize(server, version: nil, resource: [], action: nil,
+                  url: nil, args: nil, params: nil, user: nil,
+                  authorization: nil, endpoint: nil)
+      @server = server
+      @version = version
+      @resource = resource
+      @action = action
+      @url = url
+      @args = args
+      @params = params
+      @current_user = user
+      @authorization = authorization
+      @endpoint = endpoint
+    end
+
+    def resolved_url
+      return @url unless @args
+
+      ret = @url.dup
+
+      @args.each do |arg|
+        resolve_arg!(ret, arg)
+      end
+
+      ret
+    end
+
+    def url_for(action, args=nil)
+      top_module = Kernel
+      top_route = @server.routes[@version]
+
+      action.to_s.split('::').each do |name|
+        top_module = top_module.const_get(name)
+
+        begin
+          top_module.obj_type
+
+        rescue NoMethodError
+          next
+        end
+
+        if top_module.obj_type == :resource
+          top_route = top_route[:resources][top_module]
+        else
+          top_route = top_route[:actions][top_module]
+        end
+      end
+
+      ret = top_route.dup
+
+      args.each { |arg| resolve_arg!(ret, arg) } if args
+
+      ret
+    end
+
+    def call_url_params(action, obj)
+      ret = params && action.resolve.call(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))
+    end
+
+    private
+    def resolve_arg!(url, arg)
+      url.sub!(/:[a-zA-Z\-_]+/, arg.to_s)
+    end
+  end
+end

data/lib/haveapi/example.rb

@@ -0,0 +1,36 @@
+module HaveAPI
+  class Example
+    def initialize(title)
+      @title = title
+    end
+
+    def request(f)
+      @request = f
+    end
+
+    def response(f)
+      @response = f
+    end
+
+    def comment(str)
+      @comment = str
+    end
+
+    def provided?
+      @request || @response || @comment
+    end
+
+    def describe
+      if provided?
+        {
+            title: @title,
+            request: @request,
+            response: @response,
+            comment: @comment
+        }
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/haveapi/extensions/action_exceptions.rb

@@ -0,0 +1,25 @@
+module HaveAPI::Extensions
+  class ActionExceptions < Base
+    class << self
+      def enabled
+        HaveAPI::Action.connect_hook(:exec_exception) do |ret, action, e|
+          break(ret) unless @exceptions
+
+          @exceptions.each do |handler|
+            if e.is_a?(handler[:klass])
+              ret = handler[:block].call(ret, e)
+              break
+            end
+          end
+
+          ret
+        end
+      end
+
+      def rescue(klass, &block)
+        @exceptions ||= []
+        @exceptions << {klass: klass, block: block}
+      end
+    end
+  end
+end