deepl-rb 2.5.3 → 3.0.0

data/lib/deepl/requests/base.rb

@@ -1,19 +1,29 @@
+# Copyright 2018 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL
   module Requests
-    class Base
+    class Base # rubocop:disable Metrics/ClassLength
       attr_reader :api, :response, :options
 
-      def initialize(api, options = {})
+      def initialize(api, options = {}, additional_headers = {})
         @api = api
         @options = options
+        @additional_headers = additional_headers
+        @num_retries = 0
+        @backoff_timer = Utils::BackoffTimer.new
       end
 
       def request
         raise NotImplementedError
       end
 
+      def details
+        "HTTP Headers #{headers}"
+      end
+
       private
 
       def option?(name)
@@ -36,43 +46,81 @@ module DeepL
         end
       end
 
-      def post(payload)
-        request = Net::HTTP::Post.new(uri.request_uri, headers)
-        request.set_form_data(payload.compact)
-        response = http.request(request)
-
-        validate_response!(request, response)
-        [request, response]
+      # Files to reset: list of file objects to rewind when retrying the request
+      def execute_request_with_retries(req, files_to_reset = []) # rubocop:disable all
+        api.configuration.logger&.info("Request to the DeepL API: #{self}")
+        api.configuration.logger&.debug("Request details: #{details}")
+        loop do
+          resp = api.http_client.request(req)
+          validate_response!(resp)
+          return [req, resp]
+        rescue DeepL::Exceptions::Error => e
+          raise e unless should_retry?(resp, e, @backoff_timer.num_retries)
+
+          unless e.nil?
+            api.configuration.logger&.info("Encountered a retryable exception: #{e.message}")
+          end
+          api.configuration.logger&.info("Starting retry #{@backoff_timer.num_retries + 1} for " \
+                                         "request #{request} after sleeping for " \
+                                         "#{format('%.2f', @backoff_timer.time_until_deadline)}")
+          files_to_reset.each(&:rewind)
+          @backoff_timer.sleep_until_deadline
+          next
+        rescue Net::HTTPBadResponse, Net::HTTPServerError, Net::HTTPFatalError, Timeout::Error,
+               SocketError => e
+          unless e.nil?
+            api.configuration.logger&.info("Encountered a retryable exception: #{e.message}")
+          end
+          api.configuration.logger&.info("Starting retry #{@backoff_timer.num_retries + 1} for " \
+                                         "request #{request} after sleeping for " \
+                                         "#{format('%.2f', @backoff_timer.time_until_deadline)}")
+          files_to_reset.each(&:rewind)
+          @backoff_timer.sleep_until_deadline
+          next
+        end
       end
 
-      def get
-        request = Net::HTTP::Get.new(uri.request_uri, headers)
-        response = http.request(request)
+      def should_retry?(response, exception, num_retries)
+        return false if num_retries >= api.configuration.max_network_retries
+        return exception.should_retry? if response.nil?
 
-        validate_response!(request, response)
-        [request, response]
+        response.is_a?(Net::HTTPTooManyRequests) || response.is_a?(Net::HTTPInternalServerError)
       end
 
-      def delete
-        request = Net::HTTP::Delete.new(uri.request_uri, headers)
-        response = http.request(request)
+      def post_request(payload)
+        http_headers = add_json_content_type(headers)
+        post_req = Net::HTTP::Post.new(uri.path, http_headers)
+        post_req.body = payload.merge(options).to_json
+        post_req
+      end
 
-        validate_response!(request, response)
-        [request, response]
+      def post_request_with_file(form_data)
+        http_headers = add_multipart_form_content_type(headers)
+        post_req = Net::HTTP::Post.new(uri.request_uri, http_headers)
+        # options are passed in `form_data`
+        form_data += options.map { |key, value| [key.to_s, value.to_s] }
+        post_req.set_form(form_data, 'multipart/form-data')
+        post_req
       end
 
-      def http
-        @http ||= begin
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = uri.scheme == 'https'
-          http
-        end
+      def get_request # rubocop:disable Naming/AccessorMethodName
+        http_headers = add_json_content_type(headers)
+        get_req = Net::HTTP::Get.new(uri.path, http_headers)
+        get_req.body = options.to_json
+        get_req
       end
 
-      def validate_response!(request, response)
+      def delete_request
+        http_headers = add_json_content_type(headers)
+        del_req = Net::HTTP::Delete.new(uri.path, http_headers)
+        del_req.body = options.to_json
+        del_req
+      end
+
+      def validate_response!(response)
         return if response.is_a?(Net::HTTPSuccess)
 
-        raise Utils::ExceptionBuilder.new(request, response).build
+        raise Utils::ExceptionBuilder.new(response).build
       end
 
       def path
@@ -84,12 +132,8 @@ module DeepL
       end
 
       def uri
-        @uri ||= begin
-          uri = URI(url)
-          new_query = URI.decode_www_form(uri.query || '') + query_params.to_a
-          uri.query = URI.encode_www_form(new_query)
-          uri
-        end
+        @uri ||= URI(url)
+        @uri
       end
 
       def host
@@ -101,7 +145,18 @@ module DeepL
       end
 
       def headers
-        { 'Authorization' => "DeepL-Auth-Key #{api.configuration.auth_key}" }
+        { 'Authorization' => "DeepL-Auth-Key #{api.configuration.auth_key}",
+          'User-Agent' => api.configuration.user_agent }.merge(@additional_headers)
+      end
+
+      def add_json_content_type(headers_to_add_to)
+        headers_to_add_to['Content-Type'] = 'application/json'
+        headers_to_add_to
+      end
+
+      def add_multipart_form_content_type(headers_to_add_to)
+        headers_to_add_to['Content-Type'] = 'multipart/form-data'
+        headers_to_add_to
       end
     end
   end

data/lib/deepl/requests/document/download.rb

@@ -0,0 +1,44 @@
+# Copyright 2024 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    module Document
+      class Download < Base
+        attr_reader :document_id, :document_key
+
+        def initialize(api, document_id, document_key, output_file)
+          super(api, {})
+          @document_id = document_id
+          @document_key = document_key
+          @output_file = output_file
+        end
+
+        def request
+          payload = { document_key: document_key }
+          extract_file(*execute_request_with_retries(post_request(payload)))
+        end
+
+        def details
+          "HTTP Headers: #{headers}\nPayload #{{ document_key: document_key }}"
+        end
+
+        def to_s
+          "POST #{uri.request_uri}"
+        end
+
+        private
+
+        def extract_file(_request, response)
+          File.write(@output_file, response.body)
+        end
+
+        def path
+          "document/#{document_id}/result"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/document/get_status.rb

@@ -0,0 +1,44 @@
+# Copyright 2024 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    module Document
+      class GetStatus < Base
+        attr_reader :document_id, :document_key
+
+        def initialize(api, document_id, document_key, options = {}, additional_headers = {})
+          super(api, options, additional_headers)
+          @document_id = document_id
+          @document_key = document_key
+        end
+
+        def request
+          payload = { document_key: document_key }
+          build_doc_translation_status(*execute_request_with_retries(post_request(payload)))
+        end
+
+        def details
+          "HTTP Headers: #{headers}\nPayload #{{ document_key: document_key }}"
+        end
+
+        def to_s
+          "POST #{uri.request_uri}"
+        end
+
+        private
+
+        def build_doc_translation_status(request, response)
+          document_translation_status = JSON.parse(response.body)
+          Resources::DocumentTranslationStatus.new(document_translation_status, request, response)
+        end
+
+        def path
+          "document/#{document_id}"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/document/upload.rb

@@ -0,0 +1,64 @@
+# Copyright 2024 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    module Document
+      class Upload < Base
+        attr_reader :input_file_path, :source_lang, :target_lang, :filename
+
+        SUPPORTED_OPTIONS = %w[formality glossary_id output_format].freeze
+
+        def initialize(api, input_file_path, source_lang, target_lang, filename = nil, # rubocop:disable Metrics/ParameterLists
+                       options = {}, additional_headers = {})
+          super(api, options, additional_headers)
+          @input_file_path = input_file_path
+          @source_lang = source_lang
+          @target_lang = target_lang
+          @filename = filename
+        end
+
+        def request # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          input_file = File.open(input_file_path, 'rb')
+          form_data = [
+            ['file', input_file], ['source_lang', source_lang],
+            ['target_lang', target_lang]
+          ]
+          filename_param = filename || File.basename(input_file_path)
+          form_data.push(['filename', filename_param]) unless filename_param.nil?
+          # Manually add options due to multipart/form-data request
+          SUPPORTED_OPTIONS.each do |option|
+            form_data.push([option, options[option]]) unless options[option].nil?
+          end
+          build_doc_handle(*execute_request_with_retries(post_request_with_file(form_data),
+                                                         [input_file]))
+        end
+
+        def details
+          "HTTP Headers: #{headers}\nPayload #{[
+            ['file', "File at #{input_file_path} opened in binary mode"],
+            ['source_lang', source_lang], ['target_lang', target_lang], ['filename', filename]
+          ]}"
+        end
+
+        def to_s
+          "POST #{uri.request_uri}"
+        end
+
+        private
+
+        def build_doc_handle(request, response)
+          parsed_response = JSON.parse(response.body)
+          Resources::DocumentHandle.new(parsed_response['document_id'],
+                                        parsed_response['document_key'], request, response)
+        end
+
+        def path
+          'document'
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/glossary/create.rb

@@ -1,3 +1,6 @@
+# Copyright 2022 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL
@@ -20,7 +23,18 @@ module DeepL
             name: name, source_lang: source_lang, target_lang: target_lang, entries: entries_to_tsv,
             entries_format: entries_format
           }
-          build_glossary(*post(payload))
+          build_glossary(*execute_request_with_retries(post_request(payload)))
+        end
+
+        def details
+          "HTTP Headers: #{headers}\nPayload #{{
+            name: name, source_lang: source_lang, target_lang: target_lang, entries: entries_to_tsv,
+            entries_format: entries_format
+          }}"
+        end
+
+        def to_s
+          "POST #{uri.request_uri}"
         end
 
         private

data/lib/deepl/requests/glossary/destroy.rb

@@ -1,3 +1,6 @@
+# Copyright 2022 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL
@@ -12,7 +15,11 @@ module DeepL
         end
 
         def request
-          build_response(*delete)
+          build_response(*execute_request_with_retries(delete_request))
+        end
+
+        def to_s
+          "DELETE #{uri.request_uri}"
         end
 
         private

data/lib/deepl/requests/glossary/entries.rb

@@ -1,3 +1,6 @@
+# Copyright 2022 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL
@@ -12,7 +15,11 @@ module DeepL
         end
 
         def request
-          build_entries(*get)
+          build_entries(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
         end
 
         private

data/lib/deepl/requests/glossary/find.rb

@@ -1,3 +1,6 @@
+# Copyright 2022 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL
@@ -12,7 +15,11 @@ module DeepL
         end
 
         def request
-          build_glossary(*get)
+          build_glossary(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
         end
 
         private

data/lib/deepl/requests/glossary/language_pairs.rb

@@ -1,3 +1,6 @@
+# Copyright 2022 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL
@@ -5,11 +8,15 @@ module DeepL
     module Glossary
       class LanguagePairs < Base
         def initialize(api, options = {})
-          super(api, options)
+          super
         end
 
         def request
-          build_language_pair_list(*get)
+          build_language_pair_list(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
         end
 
         private

data/lib/deepl/requests/glossary/list.rb

@@ -1,3 +1,6 @@
+# Copyright 2022 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL
@@ -5,11 +8,15 @@ module DeepL
     module Glossary
       class List < Base
         def initialize(api, options = {})
-          super(api, options)
+          super
         end
 
         def request
-          build_glossary_list(*get)
+          build_glossary_list(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
         end
 
         private

data/lib/deepl/requests/languages.rb

@@ -1,14 +1,21 @@
+# Copyright 2021 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL
   module Requests
     class Languages < Base
       def initialize(api, options = {})
-        super(api, options)
+        super
       end
 
       def request
-        build_languages(*get)
+        build_languages(*execute_request_with_retries(get_request))
+      end
+
+      def to_s
+        "GET #{uri.request_uri}"
       end
 
       private

data/lib/deepl/requests/translate.rb

@@ -1,17 +1,29 @@
+# Copyright 2018 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL
   module Requests
     class Translate < Base
-      BOOLEAN_CONVERSION = { true => '1', false => '0' }.freeze
-      ARRAY_CONVERSION = ->(value) { value.is_a?(Array) ? value.join(',') : value }.freeze
+      STRING_TO_BOOLEAN_MAP = { '1' => true, '0' => false }.freeze
+      BOOLEAN_TO_STRING_MAP = { true => '1', false => '0' }.freeze
+      STRING_TO_BOOLEAN_CONVERSION = ->(value) { STRING_TO_BOOLEAN_MAP[value] }
+      BOOLEAN_TO_STRING_CONVERSION = ->(value) { BOOLEAN_TO_STRING_MAP[value] }
+      STRING_TO_ARRAY_CONVERSION = lambda { |value|
+        if value.nil?
+          nil
+        else
+          (value.is_a?(Array) ? value : value.split(','))
+        end
+      }.freeze
       OPTIONS_CONVERSIONS = {
-        split_sentences: BOOLEAN_CONVERSION,
-        preserve_formatting: BOOLEAN_CONVERSION,
-        outline_detection: BOOLEAN_CONVERSION,
-        splitting_tags: ARRAY_CONVERSION,
-        non_splitting_tags: ARRAY_CONVERSION,
-        ignore_tags: ARRAY_CONVERSION
+        split_sentences: BOOLEAN_TO_STRING_CONVERSION,
+        preserve_formatting: STRING_TO_BOOLEAN_CONVERSION,
+        outline_detection: STRING_TO_BOOLEAN_CONVERSION,
+        splitting_tags: STRING_TO_ARRAY_CONVERSION,
+        non_splitting_tags: STRING_TO_ARRAY_CONVERSION,
+        ignore_tags: STRING_TO_ARRAY_CONVERSION
       }.freeze
 
       attr_reader :text, :source_lang, :target_lang, :ignore_tags, :splitting_tags,
@@ -27,15 +39,25 @@ module DeepL
       end
 
       def request
-        payload = { text: text, source_lang: source_lang, target_lang: target_lang }
-        build_texts(*post(payload))
+        text_arrayified = text.is_a?(Array) ? text : [text]
+        payload = { text: text_arrayified, source_lang: source_lang, target_lang: target_lang }
+        build_texts(*execute_request_with_retries(post_request(payload)))
+      end
+
+      def details
+        "HTTP Headers: #{headers}\nPayload #{{ text: text, source_lang: source_lang,
+                                               target_lang: target_lang }}"
+      end
+
+      def to_s
+        "POST #{uri.request_uri}"
       end
 
       private
 
       def tweak_parameters!
         OPTIONS_CONVERSIONS.each do |param, converter|
-          next unless option?(param) && converter[option(param)]
+          next unless option?(param) && !converter[option(param)].nil?
 
           set_option(param, converter[option(param)])
         end

data/lib/deepl/requests/usage.rb

@@ -1,14 +1,21 @@
+# Copyright 2018 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL
   module Requests
     class Usage < Base
       def initialize(api, options = {})
-        super(api, options)
+        super
       end
 
       def request
-        build_usage(*get)
+        build_usage(*execute_request_with_retries(get_request))
+      end
+
+      def to_s
+        "GET #{uri.request_uri}"
       end
 
       private

data/lib/deepl/resources/base.rb

@@ -1,3 +1,6 @@
+# Copyright 2018 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
 # frozen_string_literal: true
 
 module DeepL

data/lib/deepl/resources/document_handle.rb

@@ -0,0 +1,57 @@
+# Copyright 2024 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+# frozen_string_literal: true
+
+module DeepL
+  module Resources
+    class DocumentHandle < Base
+      attr_reader :document_id, :document_key
+
+      def initialize(document_id, document_key, *args)
+        super(*args)
+
+        @document_id = document_id
+        @document_key = document_key
+      end
+
+      def to_s
+        "DocumentHandle: ID: #{document_id} - Key: #{document_key}"
+      end
+
+      ##
+      # For this DocumentHandle, waits until the document translation is finished and returns the
+      # final status of the document.
+      #
+      # @return [DeepL::Resources::DocumentTranslationStatus] Final status of the document
+      #                                                       translation.
+
+      def wait_until_document_translation_finished
+        doc_status = nil
+        max_tries = max_doc_status_queries
+        num_tries = 0
+        loop do
+          num_tries += 1
+          sleep(calculate_waiting_time(doc_status)) unless doc_status.nil?
+          doc_status = DeepL.document.get_status(self)
+          break if doc_status.finished? || num_tries > max_tries
+        end
+        doc_status
+      end
+
+      private
+
+      def calculate_waiting_time(_resp)
+        # ignore _resp.seconds_remaining for now, while it is unreliable
+        5
+      end
+
+      def max_doc_status_queries
+        configured_value = DeepL.configuration.max_doc_status_queries
+        return configured_value unless configured_value.nil?
+
+        10
+      end
+    end
+  end
+end