gapic-generator 0.11.0 → 0.45.1

data/templates/default/service/client/{_client.erb → _client.text.erb}

@@ -9,15 +9,24 @@ require "<%= subclient.require_str %>"
 <%- end -%>
 <%- end -%>
 <%- end -%>
+<%- if service.autogenerates_uuid? -%>
+require "securerandom"
+<%- end -%>
 <% end %>
 ##
 # Client for the <%= service.name %> service.
 #
 <%- if service.doc_description -%>
-<%= indent service.doc_description, "# " %>
+<%= indent service.doc_description(transport: :grpc), "# " %>
 #
 <%- end -%>
 class <%= service.client_name %>
+  # @private
+  API_VERSION = "<%= service.api_version %>".freeze
+
+  # @private
+  DEFAULT_ENDPOINT_TEMPLATE = <%= service.client_endpoint_template.inspect %>
+
 <%- if service.paths? -%>
   include <%= service.paths_name %>
 
@@ -30,11 +39,8 @@ class <%= service.client_name %>
   #
   # See {<%= service.client_name_full %>::Configuration}
   # for a description of the configuration fields.
-<%- if service.is_deprecated? -%>
-  #
-  # @deprecated This service is deprecated and may be removed in the next major version update.
-<%- end -%>
   #
+<%= render partial: "proto_docs/deprecated", locals: { presenter: service, newline: true } -%>
   # @example
   #
   #   # Modify the configuration for all <%= service.name %> clients
@@ -71,6 +77,15 @@ class <%= service.client_name %>
     @config
   end
 
+  ##
+  # The effective universe domain
+  #
+  # @return [String]
+  #
+  def universe_domain
+    @<%= service.stub_name %>.universe_domain
+  end
+
   ##
   # Create a new <%= service.name %> client object.
   #
@@ -105,7 +120,8 @@ class <%= service.client_name %>
     <%- unless service.generic_endpoint? -%>
     # Use self-signed JWT if the endpoint is unchanged from default,
     # but only if the default endpoint does not have a region prefix.
-    enable_self_signed_jwt = @config.endpoint == <%= service.client_name %>.configure.endpoint &&
+    enable_self_signed_jwt = @config.endpoint.nil? ||
+                             @config.endpoint == Configuration::DEFAULT_ENDPOINT &&
                              !@config.endpoint.split(".").first.include?("-")
     credentials ||= Credentials.default scope: @config.scope,
                                         enable_self_signed_jwt: enable_self_signed_jwt
@@ -116,23 +132,46 @@ class <%= service.client_name %>
     @quota_project_id = @config.quota_project
     @quota_project_id ||= credentials.quota_project_id if credentials.respond_to? :quota_project_id
 
-    <%- if service.subclients? -%>
-    <%- service.subclients.each do |subclient| -%>
+    <%- service.lro_subclients.each do |subclient| -%>
     @<%= subclient.client_var_name %> = <%= subclient.client_class_name %>.new do |config|
       config.credentials = credentials
       config.quota_project = @quota_project_id
       config.endpoint = @config.endpoint
+      config.universe_domain = @config.universe_domain
     end
 
-    <%- end -%>
     <%- end -%>
     @<%= service.stub_name %> = ::Gapic::ServiceStub.new(
       <%= service.proto_service_stub_name_full %>,
-      credentials:  credentials,
-      endpoint:     @config.endpoint,
+      credentials: credentials,
+      endpoint: @config.endpoint,
+      endpoint_template: DEFAULT_ENDPOINT_TEMPLATE,
+      universe_domain: @config.universe_domain,
       channel_args: @config.channel_args,
-      interceptors: @config.interceptors
+      interceptors: @config.interceptors,
+      channel_pool_config: @config.channel_pool,
+      logger: @config.logger
     )
+
+    @<%= service.stub_name %>.stub_logger&.info do |entry|
+      entry.set_system_name
+      entry.set_service
+      entry.message = "Created client for #{entry.service}"
+      entry.set_credentials_fields credentials
+      entry.set "customEndpoint", @config.endpoint if @config.endpoint
+      entry.set "defaultTimeout", @config.timeout if @config.timeout
+      entry.set "quotaProject", @quota_project_id if @quota_project_id
+    end
+    <%- service.mixin_presenters.each do |subclient| -%>
+
+    @<%= subclient.client_var_name %> = <%= subclient.client_class_name %>.new do |config|
+      config.credentials = credentials
+      config.quota_project = @quota_project_id
+      config.endpoint = @<%= service.stub_name %>.endpoint
+      config.universe_domain = @<%= service.stub_name %>.universe_domain
+      config.logger = @<%= service.stub_name %>.logger if config.respond_to? :logger=
+    end
+    <%- end -%>
   end
 
   <%- if service.subclients? -%>
@@ -146,6 +185,15 @@ class <%= service.client_name %>
 
   <%- end -%>
   <%- end -%>
+  ##
+  # The logger used for request/response debug logging.
+  #
+  # @return [Logger]
+  #
+  def logger
+    @<%= service.stub_name %>.logger
+  end
+
   # Service calls
   <%- service.methods.each do |method| -%>
 

data/templates/default/service/client/{_config.erb → _config.text.erb}

@@ -32,20 +32,27 @@
 #
 <%- end -%>
 # @!attribute [rw] endpoint
-#   The hostname or hostname:port of the service endpoint.
-#   Defaults to `<%= service.client_endpoint.inspect %>`.
-#   @return [::String]
+#   A custom service endpoint, as a hostname or hostname:port. The default is
+#   nil, indicating to use the default endpoint in the current universe domain.
+#   @return [::String,nil]
 # @!attribute [rw] credentials
 #   Credentials to send with calls. You may provide any of the following types:
 #    *  (`String`) The path to a service account key file in JSON format
 #    *  (`Hash`) A service account key as a Hash
 #    *  (`Google::Auth::Credentials`) A googleauth credentials object
-#       (see the [googleauth docs](https://googleapis.dev/ruby/googleauth/latest/index.html))
+#       (see the [googleauth docs](https://rubydoc.info/gems/googleauth/Google/Auth/Credentials))
 #    *  (`Signet::OAuth2::Client`) A signet oauth2 client object
-#       (see the [signet docs](https://googleapis.dev/ruby/signet/latest/Signet/OAuth2/Client.html))
+#       (see the [signet docs](https://rubydoc.info/gems/signet/Signet/OAuth2/Client))
 #    *  (`GRPC::Core::Channel`) a gRPC channel with included credentials
 #    *  (`GRPC::Core::ChannelCredentials`) a gRPC credentails object
 #    *  (`nil`) indicating no credentials
+#
+#   Warning: If you accept a credential configuration (JSON file or Hash) from an
+#   external source for authentication to Google Cloud, you must validate it before
+#   providing it to a Google API client library. Providing an unvalidated credential
+#   configuration to Google APIs can compromise the security of your systems and data.
+#   For more information, refer to [Validate credential configurations from external
+#   sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
 #   @return [::Object]
 # @!attribute [rw] scope
 #   The OAuth scopes
@@ -80,14 +87,28 @@
 # @!attribute [rw] quota_project
 #   A separate project against which to charge quota.
 #   @return [::String]
+# @!attribute [rw] universe_domain
+#   The universe domain within which to make requests. This determines the
+#   default endpoint URL. The default value of nil uses the environment
+#   universe (usually the default "googleapis.com" universe).
+#   @return [::String,nil]
+# @!attribute [rw] logger
+#   A custom logger to use for request/response debug logging, or the value
+#   `:default` (the default) to construct a default logger, or `nil` to
+#   explicitly disable logging.
+#   @return [::Logger,:default,nil]
 #
 class Configuration
   extend ::Gapic::Config
 
-  config_attr :endpoint,      <%= service.client_endpoint.inspect %>, ::String
+  # @private
+  # The endpoint specific to the default "googleapis.com" universe. Deprecated.
+  DEFAULT_ENDPOINT = <%= service.client_endpoint.inspect %>
+
+  config_attr :endpoint,      nil, ::String, nil
   config_attr :credentials,   nil do |value|
-    allowed = [::String, ::Hash, ::Proc, ::Symbol, ::Google::Auth::Credentials, ::Signet::OAuth2::Client, nil]
-    allowed += [::GRPC::Core::Channel, ::GRPC::Core::ChannelCredentials] if defined? ::GRPC
+    allowed = [::String, ::Hash, ::Proc, ::Symbol, ::Google::Auth::Credentials, ::Google::Auth::BaseClient, ::Signet::OAuth2::Client, nil]
+    allowed += [::GRPC::Core::Channel, ::GRPC::Core::ChannelCredentials] if defined? ::GRPC::Core::Channel
     allowed.any? { |klass| klass === value }
   end
   config_attr :scope,         nil, ::String, ::Array, nil
@@ -99,6 +120,8 @@ class Configuration
   config_attr :metadata,      nil, ::Hash, nil
   config_attr :retry_policy,  nil, ::Hash, ::Proc, nil
   config_attr :quota_project, nil, ::String, nil
+  config_attr :universe_domain, nil, ::String, nil
+  config_attr :logger, :default, ::Logger, nil, :default
 
   # @private
   def initialize parent_config = nil
@@ -119,6 +142,14 @@ class Configuration
     end
   end
 
+  ##
+  # Configuration for the channel pool
+  # @return [::Gapic::ServiceStub::ChannelPool::Configuration]
+  #
+  def channel_pool
+    @channel_pool ||= ::Gapic::ServiceStub::ChannelPool::Configuration.new
+  end
+
   ##
   # Configuration RPC class for the <%= service.name %> API.
   #

data/templates/default/service/client/{_operations.erb → _operations.text.erb}

@@ -5,6 +5,12 @@ require "<%= service.lro_service.proto_service_require %>"
 <% end %>
 # Service that implements Longrunning Operations API.
 class <%= service.operations_name %>
+  # @private
+  API_VERSION = "<%= service.api_version %>".freeze
+
+  # @private
+  DEFAULT_ENDPOINT_TEMPLATE = <%= service.client_endpoint_template.inspect %>
+
   # @private
   attr_reader :<%= service.lro_service.stub_name %>
 
@@ -39,6 +45,15 @@ class <%= service.operations_name %>
     @config
   end
 
+  ##
+  # The effective universe domain
+  #
+  # @return [String]
+  #
+  def universe_domain
+    @<%= service.lro_service.stub_name %>.universe_domain
+  end
+
   ##
   # Create a new <%= service.operations_name %> client object.
   #
@@ -69,11 +84,17 @@ class <%= service.operations_name %>
 
     @<%= service.lro_service.stub_name %> = ::Gapic::ServiceStub.new(
       <%= service.lro_service.proto_service_stub_name_full %>,
-      credentials:  credentials,
-      endpoint:     @config.endpoint,
+      credentials: credentials,
+      endpoint: @config.endpoint,
+      endpoint_template: DEFAULT_ENDPOINT_TEMPLATE,
+      universe_domain: @config.universe_domain,
       channel_args: @config.channel_args,
-      interceptors: @config.interceptors
+      interceptors: @config.interceptors,
+      channel_pool_config: @config.channel_pool
     )
+
+    # Used by an LRO wrapper for some methods of this service
+    @operations_client = self
   end
 
   # Service calls

data/templates/default/service/client/method/{_def.erb → _def.text.erb}

@@ -1,10 +1,10 @@
 <%- assert_locals method -%>
 ##
 <%- if method.doc_description -%>
-<%= indent method.doc_description, "# " %>
+<%= indent method.doc_description(transport: :grpc), "# " %>
 #
 <%- end -%>
-<%= render partial: "service/client/method/docs/deprecated", locals: { method: method } -%>
+<%= render partial: "proto_docs/deprecated", locals: { presenter: method , newline: true} -%>
 <%= render partial: "service/client/method/docs/request", locals: { method: method } -%>
 #
 <%= render partial: "service/client/method/docs/response", locals: { method: method } -%>

data/templates/default/service/client/method/def/{_options_defaults.erb → _options_defaults.text.erb}

@@ -5,10 +5,11 @@ options = ::Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h
 # Customize the options with defaults
 metadata = @config.rpcs.<%= method.name %>.metadata.to_h
 
-# Set x-goog-api-client and x-goog-user-project headers
+# Set x-goog-api-client, x-goog-user-project and x-goog-api-version headers
 metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
   lib_name: @config.lib_name, lib_version: @config.lib_version,
   gapic_version: ::<%= method.service.gem.version_name_full %>
+metadata[:"x-goog-api-version"] = API_VERSION unless API_VERSION.empty?
 metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 <%- if method.routing_params? && !method.client_streaming? -%>
 

data/templates/default/service/client/method/def/_request_normal.text.erb

@@ -0,0 +1,18 @@
+<%- assert_locals method -%>
+raise ::ArgumentError, "request must be provided" if request.nil?
+<% method.auto_populated_fields.each do |field| %>
+<% name = field.name %>
+
+# Auto populate request field `<%= name %>`.
+if request.is_a? Hash
+  request[:<%= name %>] = SecureRandom.uuid unless request.key?(:<%= name %>) || request.key?("<%= name %>")
+else
+<%- if field.proto3_optional? -%>
+  request.<%= name %> = SecureRandom.uuid unless request.has_<%= name %>?
+<%- else -%>
+  request.<%= name %> = SecureRandom.uuid if request.respond_to?(:<%= name %>) && request.<%= name %>.empty?
+<%- end -%>
+end
+<% end %>
+
+request = ::Gapic::Protobuf.coerce request, to: <%= method.request_type %>

data/templates/default/service/client/method/def/_request_streaming.text.erb

@@ -0,0 +1,23 @@
+<%- assert_locals method -%>
+unless request.is_a? ::Enumerable
+  raise ::ArgumentError, "request must be an Enumerable" unless request.respond_to? :to_enum
+  request = request.to_enum
+end
+<% method.auto_populated_fields.each do |field| %>
+<% name = field.name %>
+
+# Auto populate request field `<%= name %>`.
+if request.is_a? Hash
+  request[:<%= name %>] = SecureRandom.uuid unless request.key?(:<%= name %>) || request.key?("<%= name %>")
+else
+<%- if field.proto3_optional? -%>
+  request.<%= name %> = SecureRandom.uuid unless request.has_<%= name %>?
+<%- else -%>
+  request.<%= name %> = SecureRandom.uuid if request.respond_to?(:<%= name %>) && request.<%= name %>.empty?
+<%- end -%>
+end
+<% end %>
+
+request = request.lazy.map do |req|
+  ::Gapic::Protobuf.coerce req, to: <%= method.request_type %>
+end

data/templates/default/service/client/method/def/{_response.erb → _response.text.erb}

@@ -3,6 +3,8 @@
 <%= render partial: "service/client/method/def/response_paged", locals: { method: method } -%>
 <%- elsif method.rest.nonstandard_lro? -%>
 <%= render partial: "service/client/method/def/response_nonstandard_lro", locals: { method: method } -%>
+<%- elsif method.lro? -%>
+<%= render partial: "service/client/method/def/response_normal_lro", locals: { method: method } -%>
 <%- else -%>
 <%= render partial: "service/client/method/def/response_normal", locals: { method: method } -%>
 <%- end -%>

data/templates/default/service/client/method/def/{_response_nonstandard_lro.erb → _response_nonstandard_lro.text.erb}

@@ -19,5 +19,5 @@
     options: options
   )
   yield result, response if block_given?
-  return result
+  throw :response, result
 end

data/templates/default/service/client/method/def/_response_normal.text.erb

@@ -0,0 +1,4 @@
+<%- assert_locals method -%>
+@<%= method.service.stub_name %>.call_rpc :<%= method.name %>, request, options: options do |response, operation|
+  yield response, operation if block_given?
+end

data/templates/default/service/client/method/def/{_response_normal.erb → _response_normal_lro.text.erb}

@@ -1,8 +1,6 @@
 <%- assert_locals method -%>
 @<%= method.service.stub_name %>.call_rpc :<%= method.name %>, request, options: options do |response, operation|
-  <%- if method.lro? -%>
   response = ::Gapic::Operation.new response, <%= method.service.lro_client_ivar %>, options: options
-  <%- end -%>
   yield response, operation if block_given?
-  return response
+  throw :response, response
 end

data/templates/default/service/client/method/def/{_response_paged.erb → _response_paged.text.erb}

@@ -5,5 +5,5 @@
   <%- end -%>
   response = ::Gapic::PagedEnumerable.new @<%= method.service.stub_name %>, :<%= method.name %>, request, response, operation, options<%- if method.lro? -%>, format_resource: wrap_lro_operation<%- end -%>
   yield response, operation if block_given?
-  return response
+  throw :response, response
 end

data/templates/default/service/client/method/docs/{_request_normal.erb → _request_normal.text.erb}

@@ -19,7 +19,7 @@
 <%- method.arguments.each do |arg| -%>
 #   @param <%= arg.name %> [<%= arg.doc_types %>]
 <%- if arg.doc_description -%>
-<%= indent arg.doc_description, "#     " %>
+<%= indent arg.doc_description(transport: :grpc), "#     " %>
 <%- end -%>
 <%- end -%>
 <%- end -%>

data/templates/default/service/client/method/docs/_snippets.text.erb

@@ -0,0 +1,6 @@
+<%- assert_locals method -%>
+<%- if method.generate_yardoc_snippets? -%>
+# @example Basic example
+<%= indent render(partial: "snippets/snippet/inline", locals: { snippet: method.snippet(transport: :grpc) }), "#   " %>
+#
+<%- end -%>

data/templates/default/service/client/resource/_def.text.erb

@@ -0,0 +1,7 @@
+<%- assert_locals pattern -%>
+<%- pattern.arguments[0...-1].each do |arg| -%>
+<% escaped_argument = pattern.escape_argument arg %>
+raise ::ArgumentError, "<%= arg %> cannot contain /" if <%= escaped_argument %>.to_s.include? "/"
+<%- end -%>
+
+"<%= pattern.path_string %>"

data/templates/default/service/nonstandard_lro.text.erb

@@ -0,0 +1,6 @@
+<%- assert_locals service -%>
+<%= render partial: "service/client/nonstandard_lro",
+           layout: "layouts/ruby",
+           locals: { service: service,
+                     namespace: service.service_name_full }
+%>

data/templates/default/service/rest/client/{_client.erb → _client.text.erb}

@@ -3,22 +3,31 @@
 <%= render partial: "service/client/requires", locals: { service: service} -%>
 require "<%= service.proto_service_require %>"
 require "<%= service.rest.service_stub_require %>"
-<%- if service.subclients? -%>
-<%- service.subclients.each do |subclient| -%>
+<%- if service.rest.subclients? -%>
+<%- service.rest.subclients.each do |subclient| -%>
 <%- unless subclient.client_class_name == "Operations" -%>
 require "<%= subclient.require_str %>"
 <%- end -%>
 <%- end -%>
 <%- end -%>
+<%- if service.autogenerates_uuid? -%>
+require "securerandom"
+<%- end -%>
 <% end %>
 ##
 # REST client for the <%= service.name %> service.
 #
 <%- if service.doc_description -%>
-<%= indent service.doc_description, "# " %>
+<%= indent service.doc_description(transport: :rest), "# " %>
 #
 <%- end -%>
 class <%= service.rest.client_name %>
+  # @private
+  API_VERSION = "<%= service.api_version %>".freeze
+
+  # @private
+  DEFAULT_ENDPOINT_TEMPLATE = <%= service.client_endpoint_template.inspect %>
+
 <%- if service.paths? -%>
   include <%= service.paths_name %>
 
@@ -31,6 +40,7 @@ class <%= service.rest.client_name %>
   #
   # See {<%= service.rest.client_name_full %>::Configuration}
   # for a description of the configuration fields.
+<%= render partial: "proto_docs/deprecated", locals: { presenter: service } -%>
   #
   # @example
   #
@@ -45,7 +55,7 @@ class <%= service.rest.client_name %>
   # @return [<%= service.rest.client_name %>::Configuration]
   #
   def self.configure
-<%= indent render(partial: "service/client/self_configure", locals: { service: service }), 4 %>
+<%= indent render(partial: "service/client/self_configure", locals: { service: service.rest }), 4 %>
   end
 
   ##
@@ -68,6 +78,15 @@ class <%= service.rest.client_name %>
     @config
   end
 
+  ##
+  # The effective universe domain
+  #
+  # @return [String]
+  #
+  def universe_domain
+    @<%= service.stub_name %>.universe_domain
+  end
+
   ##
   # Create a new <%= service.name %> REST client object.
   #
@@ -94,26 +113,67 @@ class <%= service.rest.client_name %>
     # Create credentials
     credentials = @config.credentials
     <%- unless service.generic_endpoint? -%>
-    credentials ||= Credentials.default scope: @config.scope
+    # Use self-signed JWT if the endpoint is unchanged from default,
+    # but only if the default endpoint does not have a region prefix.
+    enable_self_signed_jwt = @config.endpoint.nil? ||
+                             @config.endpoint == Configuration::DEFAULT_ENDPOINT &&
+                             !@config.endpoint.split(".").first.include?("-")
+    credentials ||= Credentials.default scope: @config.scope,
+                                        enable_self_signed_jwt: enable_self_signed_jwt
     if credentials.is_a?(::String) || credentials.is_a?(::Hash)
       credentials = Credentials.new credentials, scope: @config.scope
     end
     <%- end -%>
-    
-    <%- if service.subclients? -%>
-    <%- service.subclients.each do |subclient| -%>
-    @<%= subclient.client_var_name %> = <%= subclient.client_class_name %>.new do |config|
+
+    @quota_project_id = @config.quota_project
+    @quota_project_id ||= credentials.quota_project_id if credentials.respond_to? :quota_project_id
+
+    <%- service.rest.lro_subclients.each do |subclient| -%>
+    @<%= subclient.client_var_name %> = <%= subclient.client_class_docname %>.new do |config|
       config.credentials = credentials
+      config.quota_project = @quota_project_id
       config.endpoint = @config.endpoint
+      config.universe_domain = @config.universe_domain
+      <%- if subclient.respond_to?(:bindings_override) && !subclient.bindings_override.empty? -%>
+      config.bindings_override = @config.bindings_override
+      <%- end -%>
     end
 
     <%- end -%>
+    @<%= service.stub_name %> = <%= service.rest.service_stub_name_full %>.new(
+      endpoint: @config.endpoint,
+      endpoint_template: DEFAULT_ENDPOINT_TEMPLATE,
+      universe_domain: @config.universe_domain,
+      credentials: credentials,
+      logger: @config.logger
+    )
+
+    @<%= service.stub_name %>.logger(stub: true)&.info do |entry|
+      entry.set_system_name
+      entry.set_service
+      entry.message = "Created client for #{entry.service}"
+      entry.set_credentials_fields credentials
+      entry.set "customEndpoint", @config.endpoint if @config.endpoint
+      entry.set "defaultTimeout", @config.timeout if @config.timeout
+      entry.set "quotaProject", @quota_project_id if @quota_project_id
+    end
+    <%- service.rest.mixin_presenters.each do |subclient| -%>
+
+    @<%= subclient.client_var_name %> = <%= subclient.client_class_docname %>.new do |config|
+      config.credentials = credentials
+      config.quota_project = @quota_project_id
+      config.endpoint = @<%= service.stub_name %>.endpoint
+      config.universe_domain = @<%= service.stub_name %>.universe_domain
+      <%- if subclient.respond_to?(:bindings_override) && !subclient.bindings_override.empty? -%>
+      config.bindings_override = @config.bindings_override
+      <%- end -%>
+      config.logger = @<%= service.stub_name %>.logger if config.respond_to? :logger=
+    end
     <%- end -%>
-    @<%= service.stub_name %> = <%= service.rest.service_stub_name_full %>.new endpoint: @config.endpoint, credentials: credentials
   end
 
-  <%- if service.subclients? -%>
-  <%- service.subclients.each do |subclient| -%>
+  <%- if service.rest.subclients? -%>
+  <%- service.rest.subclients.each do |subclient| -%>
   ##
   # Get the associated client for <%= subclient.service_description %>.
   #
@@ -123,8 +183,17 @@ class <%= service.rest.client_name %>
 
   <%- end -%>
   <%- end -%>
+  ##
+  # The logger used for request/response debug logging.
+  #
+  # @return [Logger]
+  #
+  def logger
+    @<%= service.stub_name %>.logger
+  end
+
   # Service calls
-  <%- service.methods.each do |method| -%>
+  <%- service.rest.methods.each do |method| -%>
 
   <%= indent_tail render(partial: "service/rest/client/method/def", locals: { method: method }), 2 %>
   <%- end -%>