haveapi-client 0.3.0 → 0.4.0

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

@@ -1,6 +1,7 @@
 module HaveAPI::Client::Authentication
   class Token < Base
     register :token
+    attr_reader :token, :valid_to
 
     def setup
       @via = @opts[:via] || :header

data/lib/haveapi/client/client.rb

@@ -8,11 +8,17 @@ class HaveAPI::Client::Client
   # The client by default uses the default version of the API.
   # API is asked for description only when needed or by calling #setup.
   # +identity+ is sent in each request to the API in User-Agent header.
-  def initialize(url, v = nil, identity: 'haveapi-client')
+  def initialize(url, v = nil, identity: 'haveapi-client', communicator: nil)
     @setup = false
     @version = v
-    @api = HaveAPI::Client::Communicator.new(url, v)
-    @api.identity = identity
+
+    if communicator
+      @api = communicator
+
+    else
+      @api = HaveAPI::Client::Communicator.new(url, v)
+      @api.identity = identity
+    end
   end
 
   # Get the description from the API now.
@@ -36,6 +42,18 @@ class HaveAPI::Client::Client
     @api.authenticate(*args)
   end
 
+  # Get uthentication provider
+  # @return [HaveAPI::Client::Authentication::Base] if authenticated
+  # @return [nil] if not authenticated
+  def auth
+    @api.auth
+  end
+
+  # @see Communicator#compatible?
+  def compatible?
+    @api.compatible?
+  end
+
   # Initialize the client if it is not yet initialized and call the resource
   # if it exists.
   def method_missing(symbol, *args)

data/lib/haveapi/client/communicator.rb

@@ -4,182 +4,214 @@ require 'active_support/inflections'
 require 'active_support/inflector'
 require_rel '../../restclient_ext'
 
-module HaveAPI
-  module Client
-    class Communicator
-      class << self
-        attr_reader :auth_methods
-
-        def register_auth_method(name, klass)
-          @auth_methods ||= {}
-          @auth_methods[name] = klass
-        end
+module HaveAPI::Client
+  class Communicator
+    class << self
+      attr_reader :auth_methods
+
+      def register_auth_method(name, klass)
+        @auth_methods ||= {}
+        @auth_methods[name] = klass
       end
+    end
 
-      attr_reader :url
-      attr_accessor :identity
+    attr_reader :url, :auth
+    attr_accessor :identity
 
-      def initialize(url, v = nil)
-        @url = url
-        @auth = Authentication::NoAuth.new(self, {}, {})
-        @rest = RestClient::Resource.new(@url)
-        @version = v
-        @identity = 'haveapi-client-ruby'
-        @desc = {}
-      end
+    def initialize(url, v = nil)
+      @url = url
+      @auth = Authentication::NoAuth.new(self, {}, {})
+      @rest = RestClient::Resource.new(@url)
+      @version = v
+      @identity = 'haveapi-client-ruby'
+      @desc = {}
+    end
 
-      # Authenticate user with selected +auth_method+.
-      # +auth_method+ is a name of registered authentication provider.
-      # +options+ are specific for each authentication provider.
-      def authenticate(auth_method, options = {})
-        desc = describe_api(@version)
+    # @return [:compatible] if perfectly compatible
+    # @return [:imperfect] if minor version differs
+    # @return [false] if not compatible
+    def compatible?
+      description_for(path_for, {describe: :versions})
+      @proto_version == HaveAPI::Client::PROTOCOL_VERSION ? :compatible
+                                                          : :imperfect
 
-        @auth = self.class.auth_methods[auth_method].new(self, desc[:authentication][auth_method], options)
-        @rest = @auth.resource || @rest
-      end
+    rescue ProtocolError
+      false
+    end
 
-      def auth_save
-        @auth.save
-      end
+    # Authenticate user with selected +auth_method+.
+    # +auth_method+ is a name of registered authentication provider.
+    # +options+ are specific for each authentication provider.
+    def authenticate(auth_method, options = {})
+      desc = describe_api(@version)
 
-      def available_versions
-        description_for(path_for, {describe: :versions})
-      end
+      @auth = self.class.auth_methods[auth_method].new(self, desc[:authentication][auth_method], options)
+      @rest = @auth.resource || @rest
+    end
 
-      def describe_api(v=nil)
-        return @desc[v] if @desc.has_key?(v)
+    def auth_save
+      @auth.save
+    end
 
-        @desc[v] = description_for(path_for(v), v.nil? ? {describe: :default} : {})
-      end
+    def available_versions
+      description_for(path_for, {describe: :versions})
+    end
 
-      def describe_resource(path)
-        tmp = describe_api(@version)
+    def describe_api(v=nil)
+      return @desc[v] if @desc.has_key?(v)
 
-        path.each do |r|
-          tmp = tmp[:resources][r.to_sym]
+      @desc[v] = description_for(path_for(v), v.nil? ? {describe: :default} : {})
+    end
 
-          return false unless tmp
-        end
+    def describe_resource(path)
+      tmp = describe_api(@version)
 
-        tmp
-      end
+      path.each do |r|
+        tmp = tmp[:resources][r.to_sym]
 
-      def describe_action(action)
-        description_for(action.prepared_help)
+        return false unless tmp
       end
 
-      def get_action(resources, action, args)
-        tmp = describe_api(@version)
+      tmp
+    end
 
-        resources.each do |r|
-          tmp = tmp[:resources][r.to_sym]
+    def describe_action(action)
+      description_for(action.prepared_help)
+    end
 
-          return false unless tmp
-        end
+    def get_action(resources, action, args)
+      tmp = describe_api(@version)
 
-        a = tmp[:actions][action]
+      resources.each do |r|
+        tmp = tmp[:resources][r.to_sym]
 
-        unless a # search in aliases
-           tmp[:actions].each do |_, v|
-            if v[:aliases].include?(action.to_s)
-              a = v
-              break
-            end
-          end
-        end
-
-        if a
-          obj = Action.new(self, action, a, args)
-          obj.resource_path = resources
-          obj
-        else
-          false
-        end
+        return false unless tmp
       end
 
-      def call(action, params, raw: false)
-        args = []
-        input_namespace = action.namespace(:input)
-        meta = nil
+      a = tmp[:actions][action]
 
-        if params.is_a?(Hash) && params[:meta]
-          meta = params[:meta]
-          params.delete(:meta)
+      unless a # search in aliases
+         tmp[:actions].each do |_, v|
+          if v[:aliases].include?(action.to_s)
+            a = v
+            break
+          end
         end
+      end
 
-        if %w(POST PUT).include?(action.http_method)
-          ns = {input_namespace => params}
-          ns[:_meta] = meta if meta
-          ns.update(@auth.request_payload)
+      if a
+        obj = Action.new(self, action, a, args)
+        obj.resource_path = resources
+        obj
+      else
+        false
+      end
+    end
 
-          args << ns.to_json
-          args << {content_type: :json, accept: :json, user_agent: @identity}.update(@auth.request_headers)
+    def call(action, params, raw: false)
+      args = []
+      input_namespace = action.namespace(:input)
+      meta = nil
 
-        elsif %w(GET DELETE).include?(action.http_method)
-          get_params = {}
+      if params.is_a?(Hash) && params[:meta]
+        meta = params[:meta]
+        params.delete(:meta)
+      end
 
-          params.each do |k, v|
-            get_params["#{input_namespace}[#{k}]"] = v
-          end
+      if %w(POST PUT).include?(action.http_method)
+        ns = {input_namespace => params}
+        ns[:_meta] = meta if meta
+        ns.update(@auth.request_payload)
 
-          meta.each do |k, v|
-            get_params["_meta[#{k}]"] = v # FIXME: read _meta namespace from the description
+        args << ns.to_json
+        args << {content_type: :json, accept: :json, user_agent: @identity}.update(@auth.request_headers)
 
-          end if meta
+      elsif %w(GET DELETE).include?(action.http_method)
+        get_params = {}
 
-          args << {params: get_params.update(@auth.request_url_params), accept: :json, user_agent: @identity}.update(@auth.request_headers)
+        params.each do |k, v|
+          get_params["#{input_namespace}[#{k}]"] = v
         end
 
-        begin
-          response = parse(@rest[action.prepared_url].method(action.http_method.downcase.to_sym).call(*args))
+        meta.each do |k, v|
+          get_params["_meta[#{k}]"] = v # FIXME: read _meta namespace from the description
 
-        rescue RestClient::Forbidden
-          return error('Access forbidden. Bad user name or password? Not authorized?')
+        end if meta
 
-        rescue => e
-          return error("Fatal API error: #{e.inspect}")
-        end
+        args << {params: get_params.update(@auth.request_url_params), accept: :json, user_agent: @identity}.update(@auth.request_headers)
+      end
 
-        if response[:status]
-          if raw
-            ok(JSON.pretty_generate(response[:response]))
-          else
-            ok(response[:response])
-          end
+      begin
+        response = parse(@rest[action.prepared_url].method(action.http_method.downcase.to_sym).call(*args))
+
+      rescue RestClient::Forbidden
+        return error('Access forbidden. Bad user name or password? Not authorized?')
 
+      rescue => e
+        return error("Fatal API error: #{e.inspect}")
+      end
+
+      if response[:status]
+        if raw
+          ok(JSON.pretty_generate(response[:response]))
         else
-          error(response[:message], response[:errors])
+          ok(response[:response])
         end
+
+      else
+        error(response[:message], response[:errors])
       end
+    end
 
-      private
-        def ok(response)
-          {status: true, response: response}
-        end
+    private
+    def ok(response)
+      {status: true, response: response}
+    end
 
-        def error(msg, errors={})
-          {status: false, message: msg, errors: errors}
-        end
+    def error(msg, errors={})
+      {status: false, message: msg, errors: errors}
+    end
 
-        def path_for(v=nil, r=nil)
-          ret = '/'
+    def path_for(v=nil, r=nil)
+      ret = '/'
 
-          ret += "v#{v}/" if v
-          ret += r if r
+      ret += "v#{v}/" if v
+      ret += r if r
 
-          ret
-        end
+      ret
+    end
 
-        def description_for(path, query_params={})
-          parse(@rest[path].get_options({
-              params: @auth.request_payload.update(@auth.request_url_params).update(query_params),
-              user_agent: @identity
-          }.update(@auth.request_headers)))[:response]
-        end
+    def description_for(path, query_params={})
+      ret = parse(@rest[path].get_options({
+          params: @auth.request_payload.update(@auth.request_url_params).update(query_params),
+          user_agent: @identity
+      }.update(@auth.request_headers)))
+      
+      @proto_version = ret[:version]
+      p_v = HaveAPI::Client::PROTOCOL_VERSION
+      return ret[:response] if ret[:version] == p_v
+      
+      unless ret[:version]
+        raise ProtocolError,
+            "Incompatible protocol version: the client uses v#{p_v} "+
+            "while the API server uses an unspecified version (pre 1.0)"
+      end
 
-        def parse(str)
-          JSON.parse(str, symbolize_names: true)
-        end
+      major1, minor1 = ret[:version].split('.')
+      major2, minor2 = p_v.split('.')
+
+      if major1 != major2
+        raise ProtocolError,
+            "Incompatible protocol version: the client uses v#{p_v} "+
+            "while the API server uses v#{ret[:version]}"
+      end
+
+      warn "The client uses protocol v#{p_v} while the API server uses v#{ret[:version]}"
+      ret[:response]
+    end
+
+    def parse(str)
+      JSON.parse(str, symbolize_names: true)
     end
   end
 end

data/lib/haveapi/client/exceptions.rb

@@ -1,13 +1,26 @@
-module HaveAPI
-  module Client
-    class ActionFailed < Exception
-      def initialize(response)
-        @response = response
-      end
+module HaveAPI::Client
+  class ProtocolError < StandardError ; end
 
-      def message
-        "#{@response.action.name} failed: #{@response.message}"
-      end
+  class ActionFailed < StandardError
+    def initialize(response)
+      @response = response
+    end
+
+    def message
+      "#{@response.action.name} failed: #{@response.message}"
+    end
+  end
+
+  class ValidationError < ActionFailed
+    attr_reader :errors
+
+    def initialize(action, errors)
+      @action = action
+      @errors = errors
+    end
+
+    def message
+      "#{@action.name} failed: input parameters not valid"
     end
   end
-end
+end

data/lib/haveapi/client/parameters/resource.rb

@@ -0,0 +1,29 @@
+module HaveAPI::Client
+  class Parameters::Resource
+    attr_reader :errors
+
+    def initialize(params, desc, value)
+      @errors = []
+      @value = coerce(value)
+    end
+
+    def valid?
+      @errors.empty?
+    end
+
+    def to_api
+      @value
+    end
+
+    protected
+    def coerce(v)
+      if !v.is_a?(::Integer) && /\A\d+\z/ !~ v
+        @errors << 'not a valid resource id'
+        nil
+
+      else
+        v.to_i
+      end
+    end
+  end
+end