feat(rest): add faraday_config option to client configuration

Addresses issue #57 by exposing the internal Faraday::Connection customization hook to the public client layer. This enables advanced HTTP setup, such as mTLS client certificate configuration.

Instead of forwarding blocks through the client constructors (which collides with the existing configuration blocks), we introduced a config.faraday_config attribute.

This approach isolates transport specific details, allows clean automated propagation to internal subclients (LROs and mixins), and uses a standard respond_to? check to preserve perfect backward compatibility with legacy external gems.

```ruby
client = Google::Cloud::Language::V1::LanguageService::Rest::Client.new do |config|
  config.faraday_config = ->(conn) do
    conn.ssl.client_cert = OpenSSL::X509::Certificate.new cert_pem
    conn.ssl.client_key  = OpenSSL::PKey::RSA.new key_pem
  end
end
```

Author: aandreassa

gapic-generator-cloud/Gemfile

@@ -13,6 +13,7 @@ gem "grpc-tools", ">= 1.60.0", "< 1.75.1"
 gem "minitest", "~> 5.16"
 gem "minitest-autotest", "~> 1.0"
 gem "minitest-focus", "~> 1.0"
+gem "ostruct", "~> 0.6.3"
 gem "pry", ">= 0.14"
 gem "redcarpet", "~> 3.0"
 gem "yard", "~> 0.9"

gapic-generator/Gemfile

@@ -11,6 +11,7 @@ gem "grpc-tools", ">= 1.60.0", "< 1.75.1"
 gem "minitest", "~> 5.16"
 gem "minitest-autotest", "~> 1.0"
 gem "minitest-focus", "~> 1.0"
+gem "ostruct", "~> 0.6.3"
 gem "pry", ">= 0.14"
 gem "redcarpet", "~> 3.0"
 gem "yard", "~> 0.9"

gapic-generator/templates/default/service/rest/client/_client.text.erb

@@ -137,6 +137,7 @@ class <%= service.rest.client_name %>
       <%- if subclient.respond_to?(:bindings_override) && !subclient.bindings_override.empty? -%>
       config.bindings_override = @config.bindings_override
       <%- end -%>
+      config.faraday_config = @config.faraday_config if config.respond_to? :faraday_config=
     end
 
     <%- end -%>
@@ -145,7 +146,8 @@ class <%= service.rest.client_name %>
       endpoint_template: DEFAULT_ENDPOINT_TEMPLATE,
       universe_domain: @config.universe_domain,
       credentials: credentials,
-      logger: @config.logger
+      logger: @config.logger,
+      faraday_config: @config.faraday_config
     )
 
     @<%= service.stub_name %>.logger(stub: true)&.info do |entry|
@@ -168,6 +170,7 @@ class <%= service.rest.client_name %>
       config.bindings_override = @config.bindings_override
       <%- end -%>
       config.logger = @<%= service.stub_name %>.logger if config.respond_to? :logger=
+      config.faraday_config = @config.faraday_config if config.respond_to? :faraday_config=
     end
     <%- end -%>
   end

gapic-generator/templates/default/service/rest/client/_config.text.erb

@@ -89,6 +89,9 @@
 #   `:default` (the default) to construct a default logger, or `nil` to
 #   explicitly disable logging.
 #   @return [::Logger,:default,nil]
+# @!attribute [rw] faraday_config
+#   A Proc to configure the underlying Faraday connection object.
+#   @return [::Proc,nil]
 #
 class Configuration
   extend ::Gapic::Config
@@ -120,6 +123,7 @@ class Configuration
   config_attr :bindings_override, {}, ::Hash, nil
   <%- end -%>
   config_attr :logger, :default, ::Logger, nil, :default
+  config_attr :faraday_config, nil, ::Proc, nil
 
   # @private
   def initialize parent_config = nil

gapic-generator/templates/default/service/rest/client/_operations.text.erb

@@ -80,7 +80,8 @@ class <%= service.operations_name %>
       endpoint: @config.endpoint,
       endpoint_template: DEFAULT_ENDPOINT_TEMPLATE,
       universe_domain: @config.universe_domain,
-      credentials: credentials
+      credentials: credentials,
+      faraday_config: @config.faraday_config
     )
 
     # Used by an LRO wrapper for some methods of this service
@@ -102,15 +103,18 @@ end
 # Service stub contains baseline method implementations
 # including transcoding, making the REST call, and deserialing the response.
 class <%= service.operations_stub_name %>
-  def initialize endpoint:, endpoint_template:, universe_domain:, credentials:
+  def initialize endpoint:, endpoint_template:, universe_domain:, credentials:, faraday_config: nil
     # These require statements are intentionally placed here to initialize
     # the REST modules only when it's required.
     require "gapic/rest"
 
-    @client_stub = ::Gapic::Rest::ClientStub.new endpoint: endpoint,
-                                                 endpoint_template: endpoint_template,
-                                                 universe_domain: universe_domain,
-                                                 credentials: credentials
+    @client_stub = ::Gapic::Rest::ClientStub.new(
+      endpoint: endpoint,
+      endpoint_template: endpoint_template,
+      universe_domain: universe_domain,
+      credentials: credentials,
+      &faraday_config
+    )
   end
 
   <%- service.lro_service.rest.methods.each do |method| -%>

gapic-generator/templates/default/service/rest/service_stub/_service_stub.text.erb

@@ -10,19 +10,22 @@ require "<%= service.proto_service_require %>"
 <%= render partial: "proto_docs/deprecated", locals: { presenter: service } -%>
 class <%= service.rest.service_stub_name %>
   # @private
-  def initialize endpoint:, endpoint_template:, universe_domain:, credentials:, logger:
+  def initialize endpoint:, endpoint_template:, universe_domain:, credentials:, logger:, faraday_config: nil
     # These require statements are intentionally placed here to initialize
     # the REST modules only when it's required.
     require "gapic/rest"
 
-    @client_stub = ::Gapic::Rest::ClientStub.new endpoint: endpoint,
-                                                 endpoint_template: endpoint_template,
-                                                 universe_domain: universe_domain,
-                                                 credentials: credentials,
-                                                 numeric_enums: <%= service.rest.numeric_enums? %>,
-                                                 service_name: self.class,
-                                                 raise_faraday_errors: false,
-                                                 logger: logger
+    @client_stub = ::Gapic::Rest::ClientStub.new(
+      endpoint: endpoint,
+      endpoint_template: endpoint_template,
+      universe_domain: universe_domain,
+      credentials: credentials,
+      numeric_enums: <%= service.rest.numeric_enums? %>,
+      service_name: self.class,
+      raise_faraday_errors: false,
+      logger: logger,
+      &faraday_config
+    )
   end
 
   ##

gapic-generator/templates/default/service/rest/test/method/_configure.text.erb

@@ -18,3 +18,28 @@ def test_configure
   assert_same block_config, config
   assert_kind_of <%= full_client_name %>::Configuration, config
 end
+
+def test_faraday_config
+  # Create test objects.
+  credentials_token = :dummy_value
+  captured_blocks = []
+
+  faraday_config_proc = ->(conn) { conn.ssl.client_cert = "cert" }
+
+  stub_proc = ->(**kwargs, &block) do
+    captured_blocks << block
+    ClientStub.new nil
+  end
+
+  # Create client with faraday_config option.
+  Gapic::Rest::ClientStub.stub :new, stub_proc do
+    <%= full_client_name %>.new do |config|
+      config.credentials = credentials_token
+      config.faraday_config = faraday_config_proc
+    end
+  end
+
+  # Verify faraday_config block passthrough.
+  assert_includes captured_blocks, faraday_config_proc
+end
+

shared/output/cloud/compute_small/lib/google/cloud/compute/v1/addresses/rest/client.rb

@@ -150,14 +150,16 @@ def initialize
                   config.quota_project = @quota_project_id
                   config.endpoint = @config.endpoint
                   config.universe_domain = @config.universe_domain
+                  config.faraday_config = @config.faraday_config if config.respond_to? :faraday_config=
                 end
 
                 @addresses_stub = ::Google::Cloud::Compute::V1::Addresses::Rest::ServiceStub.new(
                   endpoint: @config.endpoint,
                   endpoint_template: DEFAULT_ENDPOINT_TEMPLATE,
                   universe_domain: @config.universe_domain,
                   credentials: credentials,
-                  logger: @config.logger
+                  logger: @config.logger,
+                  faraday_config: @config.faraday_config
                 )
 
                 @addresses_stub.logger(stub: true)&.info do |entry|
@@ -758,6 +760,9 @@ def list request, options = nil
               #   `:default` (the default) to construct a default logger, or `nil` to
               #   explicitly disable logging.
               #   @return [::Logger,:default,nil]
+              # @!attribute [rw] faraday_config
+              #   A Proc to configure the underlying Faraday connection object.
+              #   @return [::Proc,nil]
               #
               class Configuration
                 extend ::Gapic::Config
@@ -780,6 +785,7 @@ class Configuration
                 config_attr :quota_project, nil, ::String, nil
                 config_attr :universe_domain, nil, ::String, nil
                 config_attr :logger, :default, ::Logger, nil, :default
+                config_attr :faraday_config, nil, ::Proc, nil
 
                 # @private
                 def initialize parent_config = nil

shared/output/cloud/compute_small/lib/google/cloud/compute/v1/addresses/rest/service_stub.rb

@@ -31,19 +31,22 @@ module Rest
             #
             class ServiceStub
               # @private
-              def initialize endpoint:, endpoint_template:, universe_domain:, credentials:, logger:
+              def initialize endpoint:, endpoint_template:, universe_domain:, credentials:, logger:, faraday_config: nil
                 # These require statements are intentionally placed here to initialize
                 # the REST modules only when it's required.
                 require "gapic/rest"
 
-                @client_stub = ::Gapic::Rest::ClientStub.new endpoint: endpoint,
-                                                             endpoint_template: endpoint_template,
-                                                             universe_domain: universe_domain,
-                                                             credentials: credentials,
-                                                             numeric_enums: false,
-                                                             service_name: self.class,
-                                                             raise_faraday_errors: false,
-                                                             logger: logger
+                @client_stub = ::Gapic::Rest::ClientStub.new(
+                  endpoint: endpoint,
+                  endpoint_template: endpoint_template,
+                  universe_domain: universe_domain,
+                  credentials: credentials,
+                  numeric_enums: false,
+                  service_name: self.class,
+                  raise_faraday_errors: false,
+                  logger: logger,
+                  &faraday_config
+                )
               end
 
               ##

shared/output/cloud/compute_small/lib/google/cloud/compute/v1/global_operations/rest/client.rb

@@ -149,7 +149,8 @@ def initialize
                   endpoint_template: DEFAULT_ENDPOINT_TEMPLATE,
                   universe_domain: @config.universe_domain,
                   credentials: credentials,
-                  logger: @config.logger
+                  logger: @config.logger,
+                  faraday_config: @config.faraday_config
                 )
 
                 @global_operations_stub.logger(stub: true)&.info do |entry|
@@ -421,6 +422,9 @@ def get request, options = nil
               #   `:default` (the default) to construct a default logger, or `nil` to
               #   explicitly disable logging.
               #   @return [::Logger,:default,nil]
+              # @!attribute [rw] faraday_config
+              #   A Proc to configure the underlying Faraday connection object.
+              #   @return [::Proc,nil]
               #
               class Configuration
                 extend ::Gapic::Config
@@ -443,6 +447,7 @@ class Configuration
                 config_attr :quota_project, nil, ::String, nil
                 config_attr :universe_domain, nil, ::String, nil
                 config_attr :logger, :default, ::Logger, nil, :default
+                config_attr :faraday_config, nil, ::Proc, nil
 
                 # @private
                 def initialize parent_config = nil