Add support for async conversions

- Bump Ruby version to latest 2.6 patch
- Request path method extraction with async prefix support
- Add async result class
- Refactor Task param handling

Author: danhorst

.ruby-version

@@ -1 +1 @@
-2.6.3
+2.6.10

lib/convert_api.rb

@@ -5,6 +5,7 @@
 require 'convert_api/errors'
 require 'convert_api/result'
 require 'convert_api/result_file'
+require 'convert_api/async_result'
 require 'convert_api/upload_io'
 require 'convert_api/file_param'
 require 'convert_api/format_detector'

lib/convert_api/async_result.rb

@@ -0,0 +1,13 @@
+module ConvertApi
+  class AsyncResult
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+    end
+
+    def job_id
+      response['JobId']
+    end
+  end
+end

lib/convert_api/task.rb

@@ -3,32 +3,45 @@ class Task
     def initialize(from_format, to_format, params, conversion_timeout: nil)
       @from_format = from_format
       @to_format = to_format
-      @params = params
       @conversion_timeout = conversion_timeout || config.conversion_timeout
-    end
-
-    def run
-      params = normalize_params(@params).merge(
+      @params = normalize_params(params).merge(
         Timeout: @conversion_timeout,
         StoreFile: true,
       )
+      @async = @params.delete(:Async)
+      @converter = detect_converter
+    end
 
-      from_format = @from_format || detect_format(params)
+    attr_reader :converter
+
+    def run
       read_timeout = @conversion_timeout + config.conversion_timeout_delta if @conversion_timeout
-      converter = detect_converter(params)
-      converter_path = converter ? "/converter/#{converter}" : ''
 
       response = ConvertApi.client.post(
-        "convert/#{from_format}/to/#{@to_format}#{converter_path}",
-        params,
+        request_path,
+        @params,
         read_timeout: read_timeout,
       )
 
+      return AsyncResult.new(response) if async?
+
       Result.new(response)
     end
 
     private
 
+    def async?
+      @async.to_s.downcase == 'true'
+    end
+
+    def request_path
+      from_format = @from_format || detect_format
+      converter_path = converter ? "/converter/#{converter}" : ''
+      async = async? ? 'async/' : ''
+
+      "#{async}convert/#{from_format}/to/#{@to_format}#{converter_path}"
+    end
+
     def normalize_params(params)
       result = {}
 
@@ -62,16 +75,16 @@ def files_batch(values)
       files
     end
 
-    def detect_format(params)
-      return DEFAULT_URL_FORMAT if params[:Url]
+    def detect_format
+      return DEFAULT_URL_FORMAT if @params[:Url]
 
-      resource = params[:File] || Array(params[:Files]).first
+      resource = @params[:File] || Array(@params[:Files]).first
 
       FormatDetector.new(resource, @to_format).run
     end
 
-    def detect_converter(params)
-      params.each do |key, value|
+    def detect_converter
+      @params.each do |key, value|
         return value if key.to_s.downcase == 'converter'
       end
 

spec/convert_api/task_spec.rb

@@ -8,14 +8,18 @@
   let(:file) { 'https://www.w3.org/TR/2003/REC-PNG-20031110/iso_8859-1.txt' }
   let(:result) { double }
 
-  it 'executes task and returns result' do
-    expect(ConvertApi.client).to(
-      receive(:post).with('convert/txt/to/pdf', instance_of(Hash), instance_of(Hash)).and_return(result)
-    )
+  shared_examples 'successful task' do
+    it 'executes task and returns result' do
+      expect(ConvertApi.client).to(
+        receive(:post).with('convert/txt/to/pdf', instance_of(Hash), instance_of(Hash)).and_return(result)
+      )
 
-    expect(subject).to be_instance_of(ConvertApi::Result)
+      expect(subject).to be_instance_of(ConvertApi::Result)
+    end
   end
 
+  it_behaves_like 'successful task'
+
   context 'with converter' do
     let(:params) { { File: file, Converter: 'openoffice' } }
 
@@ -53,5 +57,50 @@
 
       expect(subject).to be_instance_of(ConvertApi::Result)
     end
+
+    it 'executes task and returns result' do
+      expect(ConvertApi.client).to(
+        receive(:post).with('convert/txt/to/pdf', instance_of(Hash), instance_of(Hash)).and_return(result)
+      )
+
+      expect(subject).to be_instance_of(ConvertApi::Result)
+    end
+  end
+
+
+  describe 'async' do
+    shared_examples 'successful async task' do
+      it 'submits an async task and returns result' do
+        expect(ConvertApi.client).to(
+          receive(:post).with('async/convert/txt/to/pdf', instance_of(Hash), instance_of(Hash)).and_return(result)
+        )
+
+        expect(subject).to be_instance_of(ConvertApi::AsyncResult)
+      end
+    end
+
+    context 'Async: false' do
+      let(:params) { { Async: false, File: file } }
+
+      it_behaves_like 'successful task'
+    end
+
+    context 'Async: "false"' do
+      let(:params) { { Async: 'false', File: file } }
+
+      it_behaves_like 'successful task'
+    end
+
+    context 'Async: true' do
+      let(:params) { { Async: true, File: file } }
+
+      it_behaves_like 'successful async task'
+    end
+
+    context 'Async: "true"' do
+      let(:params) { { Async: "true", File: file } }
+
+      it_behaves_like 'successful async task'
+    end
   end
 end

spec/convert_api_spec.rb

@@ -112,6 +112,31 @@
         expect { subject }.to raise_error(ConvertApi::FormatError)
       end
     end
+
+    context 'async' do
+      shared_examples 'successful async conversion' do
+        it 'returns result' do
+          expect(subject).to be_instance_of(ConvertApi::AsyncResult)
+          expect(subject.job_id).to be_a_kind_of(String)
+        end
+      end
+
+      context 'with web resource' do
+        let(:from_format) { 'web' }
+        let(:params) { {Async: true, Url: 'http://convertapi.com' } }
+
+        it_behaves_like 'successful async conversion'
+      end
+
+      context 'with multiple files' do
+        let(:to_format) { 'zip' }
+        let(:params) { { Async: true, Files: [file1, file2] } }
+        let(:file1) { 'examples/files/test.pdf' }
+        let(:file2) { ConvertApi::UploadIO.new('examples/files/test.pdf', 'test2.pdf') }
+
+        it_behaves_like 'successful async conversion'
+      end
+    end
   end
 
   describe '.user' do