feat!: Replace underlying httpclient library with Faraday (googleapis#23524)

Release-As: 1.0.0

Author: dazuma

google-apis-core/OVERVIEW.md

@@ -4,6 +4,24 @@ This library includes common base classes and dependencies used by legacy REST
 clients for Google APIs. It is used by client libraries, but you should not
 need to install it by itself.
 
+## Usage
+
+In most cases, this library is installed automatically as a dependency of
+another library. For example, if you install the
+[google-apis-drive_v3](https://rubygems.org/gems/google-apis-drive_v3) client
+library, it will bring in the latest `google-apis-core` as a dependency. Thus,
+in most cases, you do not need to add `google-apis-core` to your Gemfile
+directly.
+
+Earlier (0.x) versions of this library utilized the legacy
+[httpclient](https://rubygems.org/gems/httpclient) gem and made some of its
+interfaces available for advanced use cases. Version 1.0 and later of this
+library replaced httpclient with [faraday](https://rubygems.org/gems/faraday).
+If your application makes use of the httpclient interfaces (this is rare), you
+should pin `google-apis-core` to a 0.x version in your Gemfile. For example:
+
+    gem "google-apis-core", "~> 0.18"
+
 ## Documentation
 
 More detailed descriptions of the Google legacy REST clients are available in two documents.

google-apis-core/google-apis-core.gemspec

@@ -21,10 +21,10 @@ Gem::Specification.new do |gem|
 
   gem.required_ruby_version = '>= 3.1'
   gem.add_runtime_dependency "representable", "~> 3.0"
-  gem.add_runtime_dependency "retriable", ">= 2.0", "< 4.a"
-  gem.add_runtime_dependency "addressable", "~> 2.5", ">= 2.5.1"
-  gem.add_runtime_dependency "mini_mime", "~> 1.0"
-  gem.add_runtime_dependency "googleauth", "~> 1.9"
-  gem.add_runtime_dependency "httpclient", ">= 2.8.3", "< 3.a"
-  gem.add_runtime_dependency "mutex_m" # used by httpclient
+  gem.add_runtime_dependency "retriable", "~> 3.1"
+  gem.add_runtime_dependency "addressable", "~> 2.8", ">= 2.8.7"
+  gem.add_runtime_dependency "mini_mime", "~> 1.1"
+  gem.add_runtime_dependency "googleauth", "~> 1.14"
+  gem.add_runtime_dependency "faraday", "~> 2.13"
+  gem.add_runtime_dependency "faraday-follow_redirects", "~> 0.3"
 end

google-apis-core/lib/google/apis/core/base_service.rb

@@ -18,13 +18,13 @@
 require 'google/apis/core/version'
 require 'google/apis/core/api_command'
 require 'google/apis/core/batch'
+require 'google/apis/core/faraday_integration'
 require 'google/apis/core/upload'
 require 'google/apis/core/storage_upload'
 require 'google/apis/core/download'
 require 'google/apis/core/storage_download'
 require 'google/apis/options'
 require 'googleauth'
-require 'httpclient'
 
 module Google
   module Apis
@@ -149,8 +149,8 @@ def root_url= url_or_template
         # @return [Addressable::URI]
         attr_accessor :batch_path
 
-        # HTTP client
-        # @return [HTTPClient]
+        # Faraday HTTP connection
+        # @return [Faraday::Connection]
         attr_writer :client
 
         # General settings
@@ -263,8 +263,8 @@ def batch_upload(options = nil)
           batch_command.execute(client)
         end
 
-        # Get the current HTTP client
-        # @return [HTTPClient]
+        # Get the current HTTP connection
+        # @return [Faraday::Connection]
         def client
           @client ||= new_client
         end
@@ -542,39 +542,22 @@ def end_batch
           Thread.current[:google_api_batch_service] = nil
         end
 
-        # Create a new HTTP client
-        # @return [HTTPClient]
+        # Create a new HTTP connection
+        # @return [Faraday::Connection]
         def new_client
-          client = ::HTTPClient.new
-
-          if client_options.transparent_gzip_decompression
-            client.transparent_gzip_decompression = client_options.transparent_gzip_decompression
-          end
-          
-          client.proxy = client_options.proxy_url if client_options.proxy_url
-
-          if client_options.open_timeout_sec
-            client.connect_timeout = client_options.open_timeout_sec
-          end
-
-          if client_options.read_timeout_sec
-            client.receive_timeout = client_options.read_timeout_sec
+          options = {}
+          request_options = {params_encoder: Faraday::FlatParamsEncoder}
+          options[:proxy] = {uri: client_options.proxy_url} if client_options.proxy_url
+          request_options[:open_timeout] = client_options.open_timeout_sec if client_options.open_timeout_sec
+          request_options[:read_timeout] = client_options.read_timeout_sec if client_options.read_timeout_sec
+          request_options[:write_timeout] = client_options.send_timeout_sec if client_options.send_timeout_sec
+          options[:request] = request_options unless request_options.empty?
+          options[:headers] = { 'User-Agent' => user_agent }
+
+          Faraday.new options do |faraday|
+            faraday.response :logger, Google::Apis.logger if client_options.log_http_requests
+            faraday.response :follow_redirects_google_apis_core, limit: 5
           end
-
-          if client_options.send_timeout_sec
-            client.send_timeout = client_options.send_timeout_sec
-          end
-
-          client.follow_redirect_count = 5
-          client.default_header = { 'User-Agent' => user_agent }
-
-          client.debug_dev = logger if client_options.log_http_requests
-
-          # Make HttpClient use system default root CA path
-          # https://github.com/nahi/httpclient/issues/445
-          client.ssl_config.clear_cert_store
-          client.ssl_config.cert_store.set_default_paths
-          client
         end
 
 

google-apis-core/lib/google/apis/core/batch.rb

@@ -82,7 +82,7 @@ def decode_response_body(content_type, body)
             parts.each_index do |index|
               response = deserializer.to_http_response(parts[index])
               outer_header = response.shift
-              call_id = header_to_id(outer_header['Content-ID'].first) || index
+              call_id = header_to_id(Array(outer_header['Content-ID']).first) || index
               call, callback = @calls[call_id]
               begin
                 result = call.process_response(*response) unless call.nil?
@@ -211,24 +211,24 @@ def to_http_response(call_response)
 
         protected
 
-        # Auxiliary method to split the header from the body in an HTTP response.
+        # Auxiliary method to split the headers from the body in an HTTP response.
         #
         # @param [String] response
         #   the response to parse.
-        # @return [Array<(HTTP::Message::Headers, String)>]
-        #   the header and the body, separately.
+        # @return [Array<(Hash{String=>Array<String>}, String)>]
+        #   the headers and the body, separately.
         def split_header_and_body(response)
-          header = HTTP::Message::Headers.new
+          headers = {}
           payload = response.lstrip
           while payload
             line, payload = payload.split(/\n/, 2)
             line.sub!(/\s+\z/, '')
             break if line.empty?
             match = /\A([^:]+):\s*/.match(line)
             fail BatchError, sprintf('Invalid header line in response: %s', line) if match.nil?
-            header[match[1]] = match.post_match
+            (headers[match[1]] ||= []) << match.post_match
           end
-          [header, payload]
+          [headers, payload]
         end
       end
     end

google-apis-core/lib/google/apis/core/download.rb

@@ -23,6 +23,8 @@ module Core
       # Streaming/resumable media download support
       class DownloadCommand < ApiCommand
         RANGE_HEADER = 'Range'
+
+        # @deprecated No longer used
         OK_STATUS = [200, 201, 206]
 
         # File or IO to write content to
@@ -61,8 +63,7 @@ def release!
         # of file content.
         #
         # @private
-        # @param [HTTPClient] client
-        #   HTTP client
+        # @param [Faraday::Connection] client Faraday connection
         # @yield [result, err] Result or error if block supplied
         # @return [Object]
         # @raise [Google::Apis::ServerError] An error occurred on the server and the request can be retried
@@ -78,39 +79,39 @@ def execute_once(client, &block)
             request_header[RANGE_HEADER] = sprintf('bytes=%d-', @offset)
           end
 
-          http_res = client.get(url.to_s,
-                     query: query,
-                     header: request_header,
-                     follow_redirect: true) do |res, chunk|
-            status = res.http_header.status_code.to_i
-            next unless OK_STATUS.include?(status)
+          http_res = client.get(url.to_s, query, request_header) do |request|
+            request.options.on_data = proc do |chunk, _size, res|
+              status = res.status.to_i
+              next if chunk.nil? || (status >= 300 && status < 400)
 
-            download_offset ||= (status == 206 ? @offset : 0)
-            download_offset  += chunk.bytesize
+              # HTTP 206 is Partial Content
+              download_offset ||= (status == 206 ? @offset : 0)
+              download_offset  += chunk.bytesize
 
-            if download_offset - chunk.bytesize == @offset
-              next_chunk = chunk
-            else
-              # Oh no! Requested a chunk, but received the entire content
-              chunk_index = @offset - (download_offset - chunk.bytesize)
-              next_chunk = chunk.byteslice(chunk_index..-1)
-              next if next_chunk.nil?
-            end
+              if download_offset - chunk.bytesize == @offset
+                next_chunk = chunk
+              else
+                # Oh no! Requested a chunk, but received the entire content
+                chunk_index = @offset - (download_offset - chunk.bytesize)
+                next_chunk = chunk.byteslice(chunk_index..-1)
+                next if next_chunk.nil?
+              end
 
-            # logger.debug { sprintf('Writing chunk (%d bytes, %d total)', chunk.length, bytes_read) }
-            @download_io.write(next_chunk)
+              # logger.debug { sprintf('Writing chunk (%d bytes, %d total)', chunk.length, bytes_read) }
+              @download_io.write(next_chunk)
 
-            @offset += next_chunk.bytesize
+              @offset += next_chunk.bytesize
+            end
           end
 
-         @download_io.flush if @download_io.respond_to?(:flush)
+          @download_io.flush if @download_io.respond_to?(:flush)
 
           if @close_io_on_finish
             result = nil
           else
             result = @download_io
           end
-          check_status(http_res.status.to_i, http_res.header, http_res.body)
+          check_status(http_res.status.to_i, http_res.headers, http_res.body)
           success(result, &block)
         rescue => e
           @download_io.flush if @download_io.respond_to?(:flush)

google-apis-core/lib/google/apis/core/faraday_integration.rb

@@ -0,0 +1,47 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "faraday"
+require "faraday/follow_redirects"
+
+module Google
+  module Apis
+    module Core
+      # Customized version of the FollowRedirects middleware that does not
+      # trigger on 308. HttpCommand wants to handle 308 itself for resumable
+      # uploads.
+      class FollowRedirectsMiddleware < Faraday::FollowRedirects::Middleware
+        def follow_redirect?(env, response)
+          super && response.status != 308
+        end
+      end
+
+      Faraday::Response.register_middleware(follow_redirects_google_apis_core: FollowRedirectsMiddleware)
+
+      # Customized subclass of Faraday::Response with additional capabilities
+      # needed by older versions of some downstream dependencies.
+      class Response < Faraday::Response
+        # Compatibility alias.
+        # Earlier versions based on the old `httpclient` gem used `HTTP::Message`,
+        # which defined the `header` field that some clients, notably
+        # google-cloud-storage, depend on.
+        # Faraday's `headers` isn't an exact replacement because its values are
+        # single strings whereas `HTTP::Message` values are arrays, but
+        # google-cloud-storage already passes the result through `Array()` so this
+        # should work sufficiently.
+        alias header headers
+      end
+    end
+  end
+end