deepl-rb 3.9.0 → 3.10.0

data/spec/offline/http_client_spec.rb

@@ -0,0 +1,319 @@
+# Copyright 2026 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
+
+require 'logger'
+require 'stringio'
+require_relative 'offline_helper'
+
+describe 'DeepL HTTP client' do
+  def stub_usage(*replies)
+    stub_request(:get, url('/v2/usage')).to_return(*replies)
+  end
+
+  describe 'retries' do
+    it 'retries a 429 reply' do
+      stub = stub_usage(reply({}, 429), usage_reply)
+
+      DeepL.usage
+      expect(stub).to have_been_requested.twice
+    end
+
+    it 'retries a 500 reply' do
+      stub = stub_usage(reply({}, 500), usage_reply)
+
+      DeepL.usage
+
+      expect(stub).to have_been_requested.twice
+    end
+
+    it 'retries a 503 reply' do
+      stub = stub_usage(reply({}, 503), usage_reply)
+
+      DeepL.usage
+
+      expect(stub).to have_been_requested.twice
+    end
+
+    it 'retries refused and reset connections, broken pipes and EOF' do
+      [Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE, EOFError].each do |error|
+        WebMock.reset!
+        stub = stub_request(:get, url('/v2/usage')).to_raise(error).then.to_return(usage_reply)
+
+        DeepL.usage
+
+        expect(stub).to have_been_requested.twice
+      end
+    end
+
+    it 'does not retry a TLS failure or a malformed response' do
+      [OpenSSL::SSL::SSLError, Net::HTTPBadResponse].each do |error|
+        WebMock.reset!
+        stub = stub_request(:get, url('/v2/usage')).to_raise(error).then.to_return(usage_reply)
+
+        expect { DeepL.usage }.to raise_error(error)
+        expect(stub).to have_been_requested.once
+      end
+    end
+
+    it 'raises a failed proxy CONNECT without retrying' do
+      error = Net::HTTPClientException.new('407 "Proxy Authentication Required"', nil)
+      stub = stub_request(:get, url('/v2/usage')).to_raise(error).then.to_return(usage_reply)
+
+      expect { DeepL.usage }.to raise_error(Net::HTTPClientException)
+      expect(stub).to have_been_requested.once
+    end
+
+    it 'retries a body shorter than its Content-Length and raises EOFError' do
+      short = { status: 200, body: '{"char', headers: { 'Content-Length' => '46' } }
+      stub = stub_usage(short)
+
+      expect { DeepL.usage }.to raise_error(EOFError)
+      expect(stub).to have_been_requested.times(3)
+    end
+
+    it 'does not let Net::HTTP re-send a request or accept a short body' do # rubocop:disable RSpec/ExampleLength
+      clients = []
+      allow(Net::HTTP).to receive(:new).and_wrap_original do |new, *args|
+        new.call(*args).tap { clients << _1 }
+      end
+      upload_url = 'https://storage.example.test/upload?sig=abc'
+      stub_request(:put, upload_url).to_return(status: 200)
+
+      [nil, DeepL::HTTPClientOptions.new({})].each do |options|
+        client = DeepL::Client.new('abc', http_client_options: options)
+        client.upload_translation_memory_file(upload_url, 'tmx')
+      end
+
+      expect(clients.map(&:max_retries)).to eq([0, 0, 0, 0])
+      # Net::HTTP#ignore_eof= exists from net-http 0.3 (Ruby 3.2).
+      next unless Net::HTTP.method_defined?(:ignore_eof=)
+
+      expect(clients.map(&:ignore_eof)).to eq([false, false, false, false])
+    end
+
+    it 'trims the auth key' do
+      DeepL.configuration.auth_key = " k \n"
+      stub_request(:get, url('/v2/usage')).with(headers: auth_headers).to_return(usage_reply)
+
+      DeepL.usage
+    end
+
+    it 'retries a network error' do
+      stub = stub_request(:get, url('/v2/usage')).to_raise(SocketError).then.to_return(usage_reply)
+
+      DeepL.usage
+
+      expect(stub).to have_been_requested.twice
+    end
+
+    it 'retries a timeout' do
+      stub = stub_request(:get, url('/v2/usage')).to_timeout.then.to_return(usage_reply)
+
+      DeepL.usage
+
+      expect(stub).to have_been_requested.twice
+    end
+
+    it 'raises the network error after max_network_retries retries' do
+      stub = stub_request(:get, url('/v2/usage')).to_timeout
+
+      expect { DeepL.usage }.to raise_error(Net::OpenTimeout)
+      expect(stub).to have_been_requested.times(3)
+    end
+
+    it 'raises LimitExceeded after max_network_retries retries' do
+      stub = stub_usage(reply({}, 429))
+
+      expect { DeepL.usage }.to raise_error(DeepL::Exceptions::LimitExceeded)
+      expect(stub).to have_been_requested.times(3)
+    end
+
+    it 'does not retry when max_network_retries is 0' do
+      DeepL.configuration.max_network_retries = 0
+      stub = stub_usage(reply({}, 429))
+
+      expect { DeepL.usage }.to raise_error(DeepL::Exceptions::LimitExceeded)
+      expect(stub).to have_been_requested.once
+    end
+  end
+
+  describe '.with_session' do
+    it 'runs the block without client options' do
+      stub = stub_usage(usage_reply)
+
+      DeepL.with_session { DeepL.usage }
+
+      expect(stub).to have_been_requested.once
+    end
+
+    it 'raises ArgumentError without a block' do
+      expect { DeepL.with_session }.to raise_error(ArgumentError, /requires a block/)
+    end
+
+    it 'applies the proxy and the timeouts to the client inside the block' do
+      options = DeepL::HTTPClientOptions.new({ 'proxy_addr' => 'proxy.example.test',
+                                               'proxy_port' => 8080 },
+                                             nil, open_timeout: 3, read_timeout: 4)
+      stub_usage(usage_reply)
+
+      client = DeepL.with_session(options) do
+        DeepL.usage
+        DeepL.api.http_client
+      end
+
+      expect([client.proxy_address, client.proxy_port, client.open_timeout, client.read_timeout])
+        .to eq(['proxy.example.test', 8080, 3, 4])
+    end
+
+    it 'enables SSL from the URL scheme and verifies certificates unless disabled' do
+      session_client = lambda do |host, verify|
+        DeepL.configuration.host = host
+        options = DeepL::HTTPClientOptions.new({}, nil, enable_ssl_verification: verify)
+        DeepL.with_session(options) { DeepL.api.http_client }
+      end
+
+      expect(session_client.call('http://localhost:3000', true)).to have_attributes(use_ssl?: false)
+      expect(session_client.call('https://api.deepl.com', false))
+        .to have_attributes(use_ssl?: true, verify_mode: OpenSSL::SSL::VERIFY_NONE)
+    end
+
+    it 'uses no proxy when only the proxy address is given' do
+      options = DeepL::HTTPClientOptions.new({ 'proxy_addr' => 'proxy.example.test' })
+
+      expect(DeepL.with_session(options) { DeepL.api.http_client }.proxy_address).to be_nil
+    end
+
+    it 'raises SocketError when the session cannot connect' do
+      http = Net::HTTP.new('unresolvable.invalid', 443)
+      allow(http).to receive(:start).and_raise(SocketError, 'getaddrinfo: Name not known')
+      allow(DeepL::Utils::HTTPClientBuilder).to receive(:build).and_return(http)
+
+      expect { DeepL.with_session { nil } }.to raise_error(SocketError)
+    end
+
+    it 'opens the session connection with the configured timeout' do
+      DeepL.configuration.timeout = 4
+      options = DeepL::HTTPClientOptions.new({}, nil, read_timeout: 7)
+
+      client = DeepL.with_session(options) { DeepL.api.http_client }
+
+      expect([client.open_timeout, client.read_timeout]).to eq([4, 7])
+    end
+
+    it 'restores the previous client when the block ends' do
+      previous = DeepL.api.http_client
+      options = DeepL::HTTPClientOptions.new({ 'proxy_addr' => 'proxy.example.test',
+                                               'proxy_port' => 8080 })
+      stub_usage(usage_reply)
+
+      DeepL.with_session(options) { DeepL.usage }
+
+      expect(DeepL.api.http_client).to equal(previous)
+      expect(DeepL.api.http_client.proxy_address).to be_nil
+      expect(DeepL.http_client).to be_nil
+    end
+
+    it 'restores the previous client when the block raises' do
+      previous = DeepL.api.http_client
+
+      expect { DeepL.with_session { raise 'boom' } }.to raise_error('boom')
+      expect(DeepL.api.http_client).to equal(previous)
+    end
+  end
+
+  describe 'logging' do
+    let(:log) { StringIO.new }
+
+    it 'logs the request and the retry' do
+      DeepL.configuration.logger = Logger.new(log)
+      stub_usage(reply({}, 429), usage_reply)
+
+      DeepL.usage
+
+      expect(log.string).to include('Request to the DeepL API: GET /v2/usage')
+                        .and include('Starting retry 1 for request GET /v2/usage')
+    end
+
+    context 'with a debug logger' do
+      before do
+        DeepL.configuration.auth_key = 'sdktest-secret-key'
+        DeepL.configuration.logger = Logger.new(log, level: Logger::DEBUG)
+      end
+
+      def expect_key_redacted
+        expect(log.string).not_to include('sdktest-secret-key')
+        expect(log.string).to include('DeepL-Auth-Key [REDACTED]')
+      end
+
+      it 'redacts the auth key in the request details' do
+        stub_usage(usage_reply)
+
+        DeepL.usage
+
+        expect_key_redacted
+      end
+
+      it 'redacts the auth key in the details of a request type that overrides them' do
+        stub_request(:post, url('/v2/translate'))
+          .to_return(reply(translations: [{ text: 'Hallo' }]))
+
+        DeepL.translate('Hello', nil, 'DE')
+
+        expect_key_redacted
+      end
+
+      it 'redacts an Authorization header given with another casing' do
+        stub_request(:post, url('/v2/translate'))
+          .to_return(reply(translations: [{ text: 'Hallo' }]))
+
+        other = { 'authorization' => 'DeepL-Auth-Key sdktest-other-key' }
+        DeepL.translate('Hello', nil, 'DE', {}, other)
+
+        expect(log.string).not_to include('sdktest-other-key')
+      end
+    end
+  end
+
+  describe 'headers' do
+    it 'lets per-call headers replace the Authorization header in any casing' do
+      stub_request(:post, url('/v2/translate'))
+        .with(headers: { 'Authorization' => 'DeepL-Auth-Key other', 'X-Custom' => 'v' })
+        .to_return(reply(translations: [{ text: 'Hallo' }]))
+
+      DeepL.translate('Hello', nil, 'DE', {}, { 'authorization' => 'DeepL-Auth-Key other',
+                                                'X-Custom' => 'v' })
+    end
+
+    it "keeps the SDK's Host and Content-Type over per-call headers" do
+      sdk_host = ->(request) { [nil, 'api.deepl.com'].include?(request.headers['Host']) }
+      stub_request(:post, 'https://api.deepl.com/v2/translate')
+        .with(headers: { 'Content-Type' => 'application/json' }, &sdk_host)
+        .to_return(reply(translations: [{ text: 'Hallo' }]))
+
+      DeepL.translate('Hello', nil, 'DE', {}, { 'host' => 'other.example.test',
+                                                'content-type' => 'text/plain' })
+    end
+
+    it 'sends no caller Content-Type with a request without a body' do
+      DeepL.configuration.headers = { 'content-type' => 'text/plain' }
+      stub_request(:get, url('/v2/usage'))
+        .with { |request| !request.headers.key?('Content-Type') }.to_return(usage_reply)
+
+      DeepL.usage
+    end
+  end
+
+  describe 'HTTPClientBuilder' do
+    it 'uses the proxy only when both address and port are given' do
+      partial = DeepL::HTTPClientOptions.new({ 'proxy_addr' => 'proxy.example.test' })
+      full = DeepL::HTTPClientOptions.new({ 'proxy_addr' => 'proxy.example.test',
+                                            'proxy_port' => 8080 })
+      build = ->(options) { DeepL::Utils::HTTPClientBuilder.build('https://api.deepl.com', options) }
+
+      expect(build.call(partial).proxy_address).to be_nil
+      expect(build.call(full).proxy_address).to eq('proxy.example.test')
+    end
+  end
+end

data/spec/offline/languages_spec.rb

@@ -0,0 +1,155 @@
+# Copyright 2026 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
+
+require_relative 'offline_helper'
+
+describe 'languages' do
+  describe 'DeepL.languages' do
+    let(:languages_reply) do
+      reply([
+              { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: false },
+              { lang: 'en-gb', name: 'English (British)', usable_as_source: false,
+                usable_as_target: true, features: { formality: { status: 'stable' } } },
+              { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true,
+                features: { formality: { status: 'stable' } } },
+              { lang: 'ja', name: 'Japanese', usable_as_source: true, usable_as_target: true }
+            ])
+    end
+
+    def stub_languages
+      stub_request(:get, url('/v3/languages?resource=translate_text'))
+        .with(headers: json_headers).to_return(languages_reply)
+    end
+
+    it 'lists the source languages with upper-case codes by default' do
+      stub_languages
+      languages = DeepL.languages
+
+      expect(languages.map(&:code)).to eq(%w[EN DE JA])
+    end
+
+    it 'lists the target languages with the formality support of each' do
+      stub_languages
+      languages = DeepL.languages(type: :target)
+
+      expect(languages.map { |l| [l.code, l.supports_formality?] })
+        .to eq([['EN-GB', true], ['DE', true], ['JA', false]])
+    end
+
+    it 'accepts the type as a string' do
+      stub_languages
+      expect(DeepL.languages('type' => 'target').map(&:code)).to eq(%w[EN-GB DE JA])
+    end
+
+    it 'raises NotSupported for the formality support of a source language' do
+      stub_languages
+      expect { DeepL.languages(type: :source).first.supports_formality? }
+        .to raise_error(DeepL::Exceptions::NotSupported, /only available on target languages/)
+    end
+
+    it 'raises ValidationError for an unknown type without sending a request' do
+      expect { DeepL.languages(type: :both) }
+        .to raise_error(DeepL::Exceptions::ValidationError, /Unsupported `type`/)
+    end
+  end
+
+  describe DeepL::Client do
+    let(:client) { described_class.new('client-key', server_url: 'https://client.example.test') }
+    let(:client_headers) do
+      { 'Authorization' => 'DeepL-Auth-Key client-key', 'Content-Type' => 'application/json' }
+    end
+
+    def stub_client_get(path, body)
+      stub_request(:get, "https://client.example.test#{path}")
+        .with(headers: client_headers).to_return(reply(body))
+    end
+
+    def stub_client_languages
+      stub_client_get('/v3/languages?resource=translate_text',
+                      [{ lang: 'en', name: 'English', usable_as_source: true,
+                         usable_as_target: false },
+                       { lang: 'en-gb', name: 'English (British)', usable_as_source: false,
+                         usable_as_target: true, features: { formality: { status: 'stable' } } },
+                       { lang: 'ja', name: 'Japanese', usable_as_source: true,
+                         usable_as_target: true }])
+    end
+
+    it '#get_source_languages returns the source languages without formality support' do
+      stub_client_languages
+
+      languages = client.get_source_languages
+
+      expect(languages.map { |l| [l.code, l.name, l.supports_formality?] })
+        .to eq([['EN', 'English', nil], ['JA', 'Japanese', nil]])
+    end
+
+    it '#get_target_languages returns the target languages with their formality support' do
+      stub_client_languages
+
+      languages = client.get_target_languages
+
+      expect(languages.map { |l| [l.code, l.supports_formality?] })
+        .to eq([['EN-GB', true], ['JA', false]])
+    end
+
+    it '#get_language_resources parses the resource name and its features' do
+      stub_client_get('/v3/languages/resources',
+                      [{ name: 'glossary', features: [{ name: 'formality' }] }])
+
+      resource = client.get_language_resources.first
+
+      expect([resource.name, resource.to_s, resource.supports?(:formality)])
+        .to eq(['glossary', 'glossary', true])
+    end
+
+    it '#get_languages_for_resource sends the resource and returns the codes unchanged' do
+      stub_client_get('/v3/languages?resource=translate_document',
+                      [{ lang: 'en-GB', name: 'English (British)', status: 'stable',
+                         usable_as_source: false, usable_as_target: true }])
+
+      languages = client.get_languages_for_resource(
+        DeepL::Constants::LanguageResourceName::TRANSLATE_DOCUMENT
+      )
+
+      expect(languages.map(&:code)).to eq(['en-GB'])
+    end
+
+    it '#get_languages_for_resource sends one include parameter per value' do
+      # WebMock matches repeated query keys by their last value only, so the path of the sent
+      # request is asserted.
+      stub_client_get('/v3/languages?resource=voice&include=beta&include=external',
+                      [{ lang: 'de', name: 'German' }])
+
+      languages = client.get_languages_for_resource(
+        :voice, include: [DeepL::Constants::LanguageInclude::BETA,
+                          DeepL::Constants::LanguageInclude::EXTERNAL]
+      )
+
+      expect(languages.first.request.path)
+        .to eq('/v3/languages?resource=voice&include=beta&include=external')
+    end
+
+    it '#get_languages_for_resource sends a resource and include value without a constant' do
+      stub_client_get('/v3/languages?resource=new_resource&include=preview', [])
+
+      client.get_languages_for_resource('new_resource', include: 'preview')
+    end
+  end
+
+  describe 'DeepL.glossaries.language_pairs' do
+    it 'requests the glossary languages and pairs every source with every other target' do
+      stub_request(:get,
+                   url('/v3/languages?resource=glossary')).with(headers: json_headers).to_return(
+                     reply([{ lang: 'en', usable_as_source: true, usable_as_target: true },
+                            { lang: 'de', usable_as_source: true, usable_as_target: true },
+                            { lang: 'fr', usable_as_source: false, usable_as_target: true }])
+                   )
+
+      pairs = DeepL.glossaries.language_pairs
+
+      expect(pairs.map(&:to_s)).to eq(['en - de', 'en - fr', 'de - en', 'de - fr'])
+    end
+  end
+end

data/spec/offline/module_methods_spec.rb

@@ -0,0 +1,13 @@
+# Copyright 2026 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
+
+require_relative 'offline_helper'
+
+describe DeepL do
+  it 'has no module-level methods for the operations added after 3.9.0' do
+    expect(%i[correct language_resources languages_for_resource multilingual_glossaries]
+             .map { |name| described_class.respond_to?(name) }).to eq([false] * 4)
+  end
+end