gini-api 0.9.2

data/lib/gini-api/oauth.rb

@@ -0,0 +1,175 @@
+require 'oauth2'
+
+module Gini
+  module Api
+
+    # OAuth2 related methods to access API resources
+    #
+    class OAuth
+
+      attr_reader :token
+
+      # Instantiate a new Gini::Api::OAuth object and acquire token(s)
+      #
+      # @param [Gini::Api::Client] api Instance of Gini::Api::Client that contains all required params
+      # @param [Hash] opts Your authorization credentials
+      # @option opts [String] auth_code OAuth authorization code. Will be exchanged for a token
+      # @option opts [String] username API username
+      # @option opts [String] password API password
+      #
+      def initialize(api, opts)
+        # Initialize client. max_redirect is required as oauth2 will otherwise redirect to location from header (localhost)
+        # https://github.com/intridea/oauth2/blob/master/lib/oauth2/client.rb#L100
+        # Our code is encoded in the URL and has to be parsed from there.
+        client = OAuth2::Client.new(
+          api.client_id,
+          api.client_secret,
+          site: api.oauth_site,
+          authorize_url: '/authorize',
+          token_url: '/token',
+          max_redirects: 0,
+          raise_errors: true,
+        )
+
+        # Verify opts. Prefered authorization methis is auth_code. If no auth_code is present a login from username/password
+        # is done.
+        auth_code =
+          if opts.key?(:auth_code) && !opts[:auth_code].empty?
+            opts[:auth_code]
+          else
+            login_with_credentials(api, client, opts[:username], opts[:password])
+          end
+
+        # Exchange code for a real token.
+        # @token is a Oauth2::AccessToken object. Accesstoken is @token.token
+        @token = exchange_code_for_token(api, client, auth_code)
+
+        # Override OAuth2::AccessToken#refresh! to update self instead of returnign a new object
+        # Inspired by https://github.com/intridea/oauth2/issues/116#issuecomment-8097675
+        #
+        # @param [Hash] opts Refresh opts passed to original refresh! method
+        #
+        # @return [OAuth2::AccessToken] Updated access token object
+        #
+        def @token.refresh!(opts = {})
+          new_token = super
+          (new_token.instance_variables - %w[@refresh_token]).each do |name|
+            instance_variable_set(name, new_token.instance_variable_get(name))
+          end
+          self
+        end
+
+        # Override OAuth2::AccessToken#request to refresh token when less then 60 seconds left
+        #
+        # @param [Symbol] verb the HTTP request method
+        # @param [String] path the HTTP URL path of the request
+        # @param [Hash] opts the options to make the request with
+        #
+        def @token.request(verb, path, opts = {}, &block)
+          refresh! if refresh_token && (expires_at < Time.now.to_i + 60)
+          super
+        end
+      end
+
+      # Login with username/password
+      #
+      # @param [Gini::Api::Client] api API object
+      # @param [OAuth2::Client] client OAuth2 client object
+      # @param [String] username API username
+      # @param [String] password API password
+      #
+      # @return [String] Collected authorization code
+      #
+      def login_with_credentials(api, client, username, password)
+        # Generate CSRF token to verify the response
+        csrf_token = SecureRandom.hex
+
+        # Build authentication URI
+        auth_uri = client.auth_code.authorize_url(
+          redirect_uri: api.oauth_redirect,
+          state: csrf_token
+        )
+
+        begin
+          # Accquire auth code
+          response = client.request(
+            :post,
+            auth_uri,
+            body: { username: username, password: password }
+          )
+          unless response.status == 303
+            raise Gini::Api::OAuthError.new(
+              "API login failed (code=#{response.status})",
+              response
+            )
+          end
+        rescue OAuth2::Error => e
+          raise Gini::Api::OAuthError.new(
+            "Failed to acquire auth_code (code=#{e.response.status})",
+            e.response
+          )
+        end
+
+        # Parse the location header from the response and fill hash
+        # query_params ({'code' => '123abc', 'state' => 'supersecret'})
+        begin
+          q = URI.parse(response.headers['location']).query
+          query_params = Hash[*q.split(/\=|\&/)]
+        rescue => e
+          raise Gini::Api::OAuthError.new("Failed to parse location header: #{e.message}")
+        end
+
+        unless query_params['state'] == csrf_token
+          raise Gini::Api::OAuthError.new(
+            "CSRF token mismatch detected (should=#{csrf_token}, "\
+            "is=#{query_params['state']})"
+          )
+        end
+
+        unless query_params.key?('code') && !query_params['code'].empty?
+          raise Gini::Api::OAuthError.new(
+            "Failed to extract code from location #{response.headers['location']}"
+          )
+        end
+
+        query_params['code']
+      end
+
+      # Exchange auth_code for a real token
+      #
+      # @param [Gini::Api::Client] api API object
+      # @param [OAuth2::Client] client OAuth2 client object
+      # @param [String] auth_code authorization code
+      #
+      # @return [OAuth2::AccessToken] AccessToken object
+      #
+      def exchange_code_for_token(api, client, auth_code)
+        client.auth_code.get_token(auth_code, redirect_uri: api.oauth_redirect)
+      rescue OAuth2::Error => e
+        raise Gini::Api::OAuthError.new(
+          "Failed to exchange auth_code for token (code=#{e.response.status})",
+          e.response
+        )
+      end
+
+      # Destroy token
+      #
+      def destroy
+        @token.refresh_token && @token.refresh!
+        response = token.delete("/accessToken/#{@token.token}")
+        unless response.status == 204
+          raise Gini::Api::OAuthError.new(
+            "Failed to destroy token /accessToken/#{@token.token} "\
+            "(code=#{response.status})",
+            response
+          )
+        end
+      rescue OAuth2::Error => e
+        raise Gini::Api::OAuthError.new(
+          "Failed to destroy token (code=#{e.response.status})",
+          e.response
+        )
+      end
+    end
+  end
+end

data/lib/gini-api/version.rb

@@ -0,0 +1,9 @@
+module Gini
+  module Api
+    # Base version for semantic versioning
+    BASE_VERSION = '0.9'
+
+    # Version string
+    VERSION = "#{BASE_VERSION}.2"
+  end
+end

data/lib/gini-api.rb

@@ -0,0 +1,15 @@
+require 'gini-api/error'
+require 'gini-api/oauth'
+require 'gini-api/client'
+require 'gini-api/version'
+require 'gini-api/document'
+require 'gini-api/document/layout'
+require 'gini-api/document/extractions'
+require 'gini-api/documentset'
+
+# Gini module namespace
+module Gini
+  # Gini::Api module namespace
+  module Api
+  end
+end

data/spec/gini-api/client_spec.rb

@@ -0,0 +1,505 @@
+require 'spec_helper'
+
+describe Gini::Api::Client do
+
+  let(:user)      { 'user@gini.net' }
+  let(:pass)      { 'secret' }
+  let(:auth_code) { '1234567890' }
+  let(:header)    { 'application/vnd.gini.v1+json' }
+  let(:oauth) do
+    double(
+      'Gini::Api::OAuth',
+      :token => 'TOKEN',
+      :destroy => nil
+    )
+  end
+
+  subject(:api) do
+    Gini::Api::Client.new(
+      client_id: 'gini-rspec',
+      client_secret: 'secret',
+      log: (Logger.new '/dev/null'),
+    )
+  end
+
+  it { should respond_to(:register_parser) }
+  it { should respond_to(:login) }
+  it { should respond_to(:logout) }
+  it { should respond_to(:version_header) }
+  it { should respond_to(:request) }
+  it { should respond_to(:upload) }
+  it { should respond_to(:delete) }
+  it { should respond_to(:get) }
+  it { should respond_to(:list) }
+  it { should respond_to(:search) }
+
+  describe '#new' do
+
+    it 'fails with missing options' do
+      expect { Gini::Api::Client.new }.to \
+        raise_error(Gini::Api::Error, /Mandatory option key is missing/)
+    end
+
+    it do
+      expect(api.log.class).to eq(Logger)
+    end
+
+  end
+
+  describe '#register_parser' do
+
+    it do
+      expect(OAuth2::Response::PARSERS.keys).to \
+        include(:gini_json)
+    end
+
+    it do
+      expect(OAuth2::Response::PARSERS.keys).to \
+        include(:gini_xml)
+    end
+
+  end
+
+  describe '#login' do
+
+    context 'with auth_code' do
+
+      it 'sets @token' do
+        expect(Gini::Api::OAuth).to \
+          receive(:new).with(
+            api, auth_code: auth_code
+          ) { oauth }
+        expect(oauth).to receive(:token)
+
+        api.login(auth_code: auth_code)
+        expect(api.token).to eql('TOKEN')
+      end
+
+    end
+
+    context 'with username/password' do
+
+      it 'sets @token' do
+        expect(Gini::Api::OAuth).to \
+          receive(:new).with(
+            api, username:
+            user, password: pass
+          ) { oauth }
+        expect(oauth).to receive(:token)
+
+        api.login(username: user, password: pass)
+        expect(api.token).to eql('TOKEN')
+      end
+
+    end
+
+  end
+
+  describe '#logout' do
+
+    it 'destroys token' do
+      expect(Gini::Api::OAuth).to \
+        receive(:new).with(
+          api,
+          auth_code: auth_code
+        ) { oauth }
+      expect(oauth).to receive(:token)
+      api.login(auth_code: auth_code)
+
+      expect(oauth).to receive(:destroy)
+      api.logout
+    end
+
+  end
+
+  describe '#version_header' do
+
+    let(:api) do
+      Gini::Api::Client.new(
+        client_id: 1,
+        client_secret: 2,
+        log: (Logger.new '/dev/null')
+      )
+    end
+
+    context 'with json' do
+
+      it 'returns accept header with json type' do
+        expect(api.version_header(:json)).to \
+          eql({ accept: header })
+      end
+
+    end
+
+    context 'with xml' do
+
+      it 'returns accept header with xml type' do
+        expect(api.version_header(:xml)).to \
+          eql({ accept: 'application/vnd.gini.v1+xml' })
+      end
+
+    end
+
+  end
+
+  context 'being logged in' do
+
+    before do
+      expect(Gini::Api::OAuth).to \
+        receive(:new).with(
+          api,
+          auth_code: auth_code
+        ) { oauth }
+      api.login(auth_code: auth_code)
+    end
+
+    describe '#request' do
+
+      let(:response) do
+        double('Response',
+          status: 200,
+          headers: {
+            'content-type' => header
+          },
+          body: body
+        )
+      end
+
+      it 'token receives call' do
+        expect(api.token).to receive(:get)
+        api.request(:get, '/dummy')
+      end
+
+      it 'raises RequestError from OAuth2::Error' do
+        expect(api.token).to \
+          receive(:get).and_raise(
+            OAuth2::Error.new(double.as_null_object)
+          )
+        expect { api.request(:get, '/invalid') }.to \
+          raise_error(Gini::Api::RequestError)
+      end
+
+      it 'raises ProcessingError on timeout' do
+        expect(api.token).to \
+          receive(:get).and_raise(Timeout::Error)
+        expect { api.request(:get, '/timeout') }.to \
+          raise_error(Gini::Api::ProcessingError)
+      end
+
+      context 'return JSON as default' do
+
+        let(:body) do
+          {
+            a: 1,
+            b: 2
+          }.to_json
+        end
+
+        it do
+          expect(api.token).to \
+            receive(:get).and_return(OAuth2::Response.new(response))
+          expect(api.request(:get, '/dummy').parsed).to be_a Hash
+        end
+
+      end
+
+      context 'return XML on request' do
+
+        let(:header) { 'application/vnd.gini.v1+xml' }
+        let(:body)   { '<data><a>1</a><b>2</b></data>' }
+
+        it do
+          expect(api.token).to \
+            receive(:get).and_return(
+              OAuth2::Response.new(response)
+            )
+
+          expect(api.request(
+            :get,
+            '/dummy',
+            type: 'xml'
+          ).parsed).to be_a Hash
+        end
+
+      end
+
+      context 'set custom accept header' do
+
+        let(:header) { 'application/octet-stream' }
+        let(:body)   { 'Just a string' }
+
+        it do
+          expect(api.token).to \
+            receive(:get).with(
+              %r{/dummy},
+              headers: {
+                accept: 'application/octet-stream'
+                }
+            ).and_return(OAuth2::Response.new(response))
+          expect(api.request(
+            :get,
+            '/dummy',
+            headers: {
+              accept: 'application/octet-stream'
+            }
+          ).body).to be_a String
+        end
+
+      end
+
+    end
+
+    describe '#upload' do
+
+      let(:doc) { double(Gini::Api::Document, poll: true, id: 'abc-123') }
+
+      before do
+        allow(doc).to receive(:duration=)
+          allow(Gini::Api::Document).to \
+            receive(:new).with(api, 'LOC'
+          ) { doc }
+        api.token.stub(:token).and_return('abc-123')
+        stub_request(
+          :post,
+          %r{/documents}
+        ).to_return(
+          status: status,
+          headers: {
+            location: 'LOC'
+          },
+          body: {}
+        )
+      end
+
+      context 'when failed' do
+
+        let(:status) { 500 }
+
+        it do
+          expect { api.upload('spec/integration/files/test.pdf') }.to \
+            raise_error(Gini::Api::UploadError)
+        end
+
+      end
+
+      context 'when successful' do
+
+        let(:status) { 201 }
+
+        it 'Gini::Api::Document is created' do
+          api.upload('spec/integration/files/test.pdf')
+        end
+      end
+
+      context 'on timeout' do
+
+        let(:status) { 201 }
+
+        it 'raises ProcessingError on timeout' do
+          expect(doc).to receive(:poll).and_raise(Timeout::Error)
+          expect { api.upload('spec/integration/files/test.pdf') }.to \
+            raise_error(Gini::Api::ProcessingError)
+        end
+
+      end
+
+    end
+
+    describe '#delete' do
+
+      let(:response) do
+        double('Response',
+          status: status,
+          env: {},
+          body: {}
+        )
+      end
+
+      context 'with invalid docId' do
+
+        let(:status) { 203 }
+
+        it do
+          api.token.stub(:delete).and_return(response)
+          expect { api.delete('abc-123') }.to \
+            raise_error(Gini::Api::DocumentError, /Deletion of docId abc-123 failed/)
+        end
+
+      end
+
+      context 'with valid docId' do
+
+        let(:status) { 204 }
+
+        it do
+          api.token.stub(:delete).and_return(response)
+          expect(api.delete('abc-123')).to be_true
+        end
+
+      end
+
+    end
+
+    describe '#get' do
+
+      it do
+        expect(Gini::Api::Document).to \
+          receive(:new) { double('Gini::Api::Document') }
+        api.get('abc-123')
+      end
+
+    end
+
+    describe '#list' do
+
+      let(:response) do
+        double('Response',
+          status: 200,
+          headers: {
+            'content-type' => header
+          },
+          body: {
+            totalCount: doc_count,
+            next: nil,
+            documents: documents
+          }.to_json)
+      end
+
+      before do
+        api.token.stub(:get).and_return(OAuth2::Response.new(response))
+      end
+
+      context 'with documents' do
+
+        let(:doc_count) { 1 }
+        let(:documents) do
+          [
+            {
+              id: 42,
+              :_links => {
+                :document => 'https://rspec/123-abc'
+              }
+            }
+          ]
+        end
+
+        it do
+          expect(api.list.total).to eql(1)
+          expect(api.list.offset).to be_nil
+          expect(api.list.documents[0]).to be_a(Gini::Api::Document)
+          expect(api.list).to be_a(Gini::Api::DocumentSet)
+        end
+
+      end
+
+      context 'without documents' do
+
+        let(:doc_count) { 0 }
+        let(:documents) { [] }
+
+        it do
+          expect(api.list.total).to eql(0)
+          expect(api.list.offset).to be_nil
+          expect(api.list.documents).to eql([])
+          expect(api.list).to be_a(Gini::Api::DocumentSet)
+        end
+
+      end
+
+      context 'with failed http request' do
+
+        let(:response) do
+          double('Response',
+            status: 500,
+            env: {},
+            body: {}
+          )
+        end
+
+        it do
+          expect { api.list }.to \
+            raise_error(Gini::Api::DocumentError, /Failed to get list of documents/)
+        end
+
+      end
+
+    end
+
+    describe '#search' do
+
+      before do
+        api.token.stub(:get).and_return(OAuth2::Response.new(response))
+      end
+
+      let(:status) { 200 }
+      let(:response) do
+        double('Response',
+          status: status,
+          headers: {
+            'content-type' => header
+          },
+          body: {
+            totalCount: doc_count,
+            next: nil,
+            documents: documents
+          }.to_json
+        )
+      end
+
+      context 'with found documents' do
+
+        let(:doc_count) { 1 }
+        let(:documents) do
+          [
+            {
+              id: '0f122e10-8dba-11e3-8a85-02015140775',
+              _links: {
+                document: 'https://rspec/123-abc'
+              }
+            }
+          ]
+        end
+
+        it do
+          result = api.search('invoice')
+
+          expect(result.total).to eql(1)
+          expect(result.offset).to be_nil
+          expect(result.documents[0]).to be_a(Gini::Api::Document)
+          expect(result).to be_a(Gini::Api::DocumentSet)
+        end
+
+      end
+
+      context 'with no found documents' do
+
+        let(:doc_count) { 0 }
+        let(:documents) { [] }
+
+        it do
+          result = api.search('invoice')
+
+          expect(result.total).to eql(0)
+          expect(result.offset).to be_nil
+          expect(result.documents).to eql([])
+          expect(result).to be_a(Gini::Api::DocumentSet)
+        end
+
+      end
+
+      context 'with failed query' do
+
+        let(:response) { double('Response', status: 500, env: {}, body: {}) }
+
+        it do
+          expect{api.search('invoice')}.to \
+            raise_error(Gini::Api::SearchError, /Search query failed with code 500/)
+        end
+
+      end
+
+    end
+
+  end
+
+end