gapic-generator 0.8.0 → 0.10.1

data/templates/default/service/client/_config.erb

@@ -14,22 +14,21 @@
 # on construction.
 #
 <%- unless method_service.methods.empty? -%>
-# # Examples
+# @example
 #
-# To modify the global config, setting the timeout for <%= method_service.methods.first.name %>
-# to 20 seconds, and all remaining timeouts to 10 seconds:
+#   # Modify the global config, setting the timeout for
+#   # <%= method_service.methods.first.name %> to 20 seconds,
+#   # and all remaining timeouts to 10 seconds.
+#   <%= service.client_name_full %>.configure do |config|
+#     config.timeout = 10.0
+#     config.rpcs.<%= method_service.methods.first.name %>.timeout = 20.0
+#   end
 #
-#     <%= service.client_name_full %>.configure do |config|
-#       config.timeout = 10.0
-#       config.rpcs.<%= method_service.methods.first.name %>.timeout = 20.0
-#     end
-#
-# To apply the above configuration only to a new client:
-#
-#     client = <%= service.client_name_full %>.new do |config|
-#       config.timeout = 10.0
-#       config.rpcs.<%= method_service.methods.first.name %>.timeout = 20.0
-#     end
+#   # Apply the above configuration only to a new client.
+#   client = <%= service.client_name_full %>.new do |config|
+#     config.timeout = 10.0
+#     config.rpcs.<%= method_service.methods.first.name %>.timeout = 20.0
+#   end
 #
 <%- end -%>
 # @!attribute [rw] endpoint

data/templates/default/service/client/_credentials.erb

@@ -12,10 +12,12 @@ class <%= service.credentials_name %> < ::Google::Auth::Credentials
   <%- end -%>
   ]
   <%- end -%>
+  <%- if service.gem.env_prefix -%>
   self.env_vars = [
     "<%= service.gem.env_prefix %>_CREDENTIALS",
     "<%= service.gem.env_prefix %>_KEYFILE",
     "<%= service.gem.env_prefix %>_CREDENTIALS_JSON",
     "<%= service.gem.env_prefix %>_KEYFILE_JSON"
   ]
+  <%- end -%>
 end

data/templates/default/service/client/_operations.erb

@@ -61,7 +61,7 @@ class <%= service.operations_name %>
     # Create credentials
     credentials = @config.credentials
     credentials ||= Credentials.default scope: @config.scope
-    if credentials.is_a?(String) || credentials.is_a?(Hash)
+    if credentials.is_a?(::String) || credentials.is_a?(::Hash)
       credentials = Credentials.new credentials, scope: @config.scope
     end
     @quota_project_id = @config.quota_project

data/templates/default/service/client/_paths.erb

@@ -1,7 +1,7 @@
 <%- assert_locals service -%>
 # Path helper methods for the <%= service.name %> API.
 module Paths
-<%- service.references.each do |resource| -%>
+<%- service.deduped_references.each do |resource| -%>
 <%= indent render(partial: "service/client/resource", locals: { resource: resource }), 2 %>
 
 <%- end %>

data/templates/default/service/client/_self_configure_defaults.erb

@@ -6,7 +6,7 @@
     default_config.timeout = <%= format_number service.grpc_service_config.timeout_seconds %>
   <%- end -%>
   <%- if service.grpc_service_config.retry_policy -%>
-    default_config.retry_policy = <%= indent_tail render(partial: "service/client/self_configure_retry_policy", locals: { retry_policy: service.grpc_service_config.retry_policy }), 2 %>
+    default_config.retry_policy = <%= indent_tail service.service_config_presenter.retry_policy_fields, 2 %>
   <%- end -%>
 <%- end -%>
 <%- method_service.methods.each do |method| -%>
@@ -16,7 +16,7 @@
       default_config.rpcs.<%= method.name %>.timeout = <%= format_number method.grpc_service_config.timeout_seconds %>
     <%- end -%>
     <%- if method.grpc_service_config.retry_policy -%>
-      default_config.rpcs.<%= method.name %>.retry_policy =<%= indent_tail render(partial: "service/client/self_configure_retry_policy", locals: { retry_policy: method.grpc_service_config.retry_policy }), 2 %>
+      default_config.rpcs.<%= method.name %>.retry_policy =<%= indent_tail method.service_config_presenter.retry_policy_fields, 2 %>
     <%- end -%>
   <%- end -%>
 <%- end -%>

data/templates/default/service/client/method/_def.erb

@@ -4,12 +4,14 @@
 <%= indent method.doc_description, "# " %>
 #
 <%- end -%>
+<%= render partial: "service/client/method/docs/deprecated", locals: { method: method } -%>
 <%= render partial: "service/client/method/docs/request", locals: { method: method } -%>
 #
 <%= render partial: "service/client/method/docs/response", locals: { method: method } -%>
 #
 <%= render partial: "service/client/method/docs/error", locals: { method: method } -%>
 #
+<%= render partial: "service/client/method/docs/snippets", locals: { method: method } -%>
 <%= render partial: "service/client/method/docs/samples", locals: { method: method } -%>
 def <%= method.name %> request, options = nil
 <%= indent render(partial: "service/client/method/def/request", locals: { method: method }), 2 %>

data/templates/default/service/client/method/def/_options_defaults.erb

@@ -25,5 +25,7 @@ metadata[:"x-goog-request-params"] ||= request_params_header
 options.apply_defaults timeout:      @config.rpcs.<%= method.name %>.timeout,
                        metadata:     metadata,
                        retry_policy: @config.rpcs.<%= method.name %>.retry_policy
-options.apply_defaults metadata:     @config.metadata,
+                       
+options.apply_defaults timeout:      @config.timeout,
+                       metadata:     @config.metadata,
                        retry_policy: @config.retry_policy

data/templates/default/service/client/method/docs/_deprecated.erb

@@ -0,0 +1,5 @@
+<%- assert_locals method -%>
+<%- if method.is_deprecated? -%>
+# @deprecated This method is deprecated and may be removed in the next major version update.
+#
+<%- end -%>

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

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

data/templates/default/service/rest/client/_client.erb

@@ -2,6 +2,7 @@
 <% @requires = capture do %>
   <%= render partial: "service/client/requires", locals: { service: service} -%>
   require "<%= service.proto_service_require %>"
+  require "<%= service.rest.service_stub_require %>"
 <% end %>
 ##
 # REST client for the <%= service.name %> service.
@@ -11,7 +12,6 @@
 #
 <%- end -%>
 class <%= service.rest.client_name %>
-  include <%= service.rest.transcoding_helper_name %>
 <%- if service.paths? -%>
   include <%= service.paths_name %>
 <%- end -%>
@@ -25,13 +25,12 @@ class <%= service.rest.client_name %>
   # See {<%= service.rest.client_name_full %>::Configuration}
   # for a description of the configuration fields.
   #
-  # ## Example
+  # @example
   #
-  # To modify the configuration for all <%= service.name %> clients:
-  #
-  #     <%= service.rest.client_name_full %>.configure do |config|
-  #       config.timeout = 10.0
-  #     end
+  #   # Modify the configuration for all <%= service.name %> clients
+  #   <%= service.rest.client_name_full %>.configure do |config|
+  #     config.timeout = 10.0
+  #   end
   #
   # @yield [config] Configure the <%= service.rest.client_name %> client.
   # @yieldparam config [<%= service.rest.client_name %>::Configuration]
@@ -65,28 +64,20 @@ class <%= service.rest.client_name %>
   ##
   # Create a new <%= service.name %> REST client object.
   #
-  # ## Examples
-  #
-  # To create a new <%= service.name %> REST client with the default
-  # configuration:
+  # @example
   #
-  #     client = <%= service.rest.client_name_full %>.new
+  #   # Create a client using the default configuration
+  #   client = <%= service.rest.client_name_full %>.new
   #
-  # To create a new <%= service.name %> REST client with a custom
-  # configuration:
-  #
-  #     client = <%= service.rest.client_name_full %>.new do |config|
-  #       config.timeout = 10.0
-  #     end
+  #   # Create a client using a custom configuration
+  #   client = <%= service.rest.client_name_full %>.new do |config|
+  #     config.timeout = 10.0
+  #   end
   #
   # @yield [config] Configure the <%= service.name %> client.
   # @yieldparam config [<%= service.rest.client_name %>::Configuration]
   #
   def initialize
-    # These require statements are intentionally placed here to initialize
-    # the REST modules only when it's required.
-    require "gapic/rest"
-
     # Create the configuration object
     @config = Configuration.new <%= service.rest.client_name %>.configure
 
@@ -97,12 +88,12 @@ class <%= service.rest.client_name %>
     credentials = @config.credentials
     <%- unless service.generic_endpoint? -%>
     credentials ||= Credentials.default scope: @config.scope
-    if credentials.is_a?(String) || credentials.is_a?(Hash)
+    if credentials.is_a?(::String) || credentials.is_a?(::Hash)
       credentials = Credentials.new credentials, scope: @config.scope
     end
     <%- end -%>
     
-    @client_stub = ::Gapic::Rest::ClientStub.new endpoint: @config.endpoint, credentials: credentials
+    @<%= service.stub_name %> = <%= service.rest.service_stub_name_full %>.new endpoint: @config.endpoint, credentials: credentials
   end
 
   # Service calls

data/templates/default/service/rest/client/_config.erb

@@ -51,6 +51,9 @@
 # @!attribute [rw] timeout
 #   The call timeout in seconds.
 #   @return [::Numeric]
+# @!attribute [rw] metadata
+#   Additional REST headers to be sent with the call.
+#   @return [::Hash{::Symbol=>::String}]
 #
 class Configuration
   extend ::Gapic::Config
@@ -64,6 +67,7 @@ class Configuration
   config_attr :lib_name,      nil, ::String, nil
   config_attr :lib_version,   nil, ::String, nil
   config_attr :timeout,       nil, ::Numeric, nil
+  config_attr :metadata,      nil, ::Hash, nil
 
   # @private
   def initialize parent_config = nil
@@ -71,4 +75,48 @@ class Configuration
 
     yield self if block_given?
   end
+
+  ##
+  # Configurations for individual RPCs
+  # @return [Rpcs]
+  #
+  def rpcs
+    @rpcs ||= begin
+      parent_rpcs = nil
+      parent_rpcs = @parent_config.rpcs if defined?(@parent_config) && @parent_config.respond_to?(:rpcs)
+      Rpcs.new parent_rpcs
+    end
+  end
+
+  ##
+  # Configuration RPC class for the <%= service.name %> API.
+  #
+  # Includes fields providing the configuration for each RPC in this service.
+  # Each configuration object is of type `Gapic::Config::Method` and includes
+  # the following configuration fields:
+  #
+  #  *  `timeout` (*type:* `Numeric`) - The call timeout in seconds
+  #
+  # there is one other field (`retry_policy`) that can be set
+  # but is currently not supported for REST Gapic libraries.
+  # 
+  class Rpcs
+  <%- method_service.methods.each do |method| -%>
+    ##
+    # RPC-specific configuration for `<%= method.name %>`
+    # @return [::Gapic::Config::Method]
+    #
+    attr_reader :<%= method.name %>
+  <%- end -%>
+
+    # @private
+    def initialize parent_rpcs = nil
+      <%- method_service.methods.each do |method| -%>
+      <%= method.name %>_config = parent_rpcs.<%= method.name %> if parent_rpcs.respond_to? :<%= method.name %>
+      @<%= method.name %> = ::Gapic::Config::Method.new <%= method.name %>_config
+      <%- end -%>
+
+      yield self if block_given?
+    end
+  end
 end

data/templates/default/service/rest/client/method/_def.erb

@@ -13,6 +13,6 @@ def <%= method.name %> request, options = nil
 
 <%= indent render(partial: "service/rest/client/method/def/options_defaults", locals: { method: method }), 2 %>
 
-<%= indent render(partial: "service/rest/client/method/def/response_normal", locals: { method: method }), 2 %>
+<%= indent render(partial: "service/rest/client/method/def/response", locals: { method: method }), 2 %>
 <%= render partial: "service/rest/client/method/def/rescue", locals: { method: method } -%>
 end

data/templates/default/service/rest/client/method/def/_options_defaults.erb

@@ -3,7 +3,7 @@
 options = ::Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h
 
 # Customize the options with defaults
-call_metadata = {}
+call_metadata = @config.rpcs.<%= method.name %>.metadata.to_h
 
 # Set x-goog-api-client header
 call_metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
@@ -11,5 +11,8 @@ call_metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
   gapic_version: ::<%= method.service.gem.version_name_full %>,
   transports_version_send: [:rest]
 
-options.apply_defaults timeout:      @config.timeout,
+options.apply_defaults timeout:      @config.rpcs.<%= method.name %>.timeout,
                        metadata:     call_metadata
+
+options.apply_defaults timeout:      @config.timeout,
+                       metadata:     @config.metadata

data/templates/default/service/rest/client/method/def/_response.erb

@@ -0,0 +1,8 @@
+<%- assert_locals method -%>
+<%- if method.rest.paged? -%>
+<%= render partial: "service/rest/client/method/def/response_paged", locals: { method: method } -%>
+<%- elsif method.rest.lro? -%>
+<%= render partial: "service/rest/client/method/def/response_lro", locals: { method: method } -%>
+<%- else -%>
+<%= render partial: "service/rest/client/method/def/response_normal", locals: { method: method } -%>
+<%- end -%>

data/templates/default/service/rest/client/method/def/_response_lro.erb

@@ -0,0 +1,7 @@
+<%- assert_locals method -%>
+
+@<%= method.service.stub_name %>.<%= method.name %> request, options do |result, response|
+  result = ::Gapic::Rest::BaseOperation.new result
+  yield result, response if block_given?
+  return result
+end

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

@@ -1,17 +1,6 @@
 <%- assert_locals method -%>
 
-uri, <%= method.rest.body_var_name %>, <%= method.rest.query_string_params_var_name %> = <%= method.rest.transcoding_helper_name %> request
-response = @client_stub.make_<%= method.rest.verb %>_request(
-  uri:     uri,
-<%- if method.rest.body? -%>
-  body:    body,
-<%- end -%>
-<%- if method.rest.query_string_params? -%>
-  params:  query_string_params,
-<%- end -%>
-  options: options
-)
-result = <%= method.return_type %>.decode_json response.body, ignore_unknown_fields: true
-
-yield result, response if block_given?
-result
+@<%= method.service.stub_name %>.<%= method.name %> request, options do |result, response|
+  yield result, response if block_given?
+  return result
+end

data/templates/default/service/rest/client/method/def/_response_paged.erb

@@ -0,0 +1,7 @@
+<%- assert_locals method -%>
+
+@<%= method.service.stub_name %>.<%= method.name %> request, options do |result, response|
+  result = ::Gapic::Rest::PagedEnumerable.new @<%= method.service.stub_name %>, :<%= method.name %>, "<%= method.rest.pagination.response_repeated_field_name %>", request, result, options
+  yield result, response if block_given?
+  return result
+end

data/templates/default/service/rest/client/method/docs/_result.erb

@@ -1,6 +1,6 @@
 <%- assert_locals method -%>
-# @yield [result, env] Access the result along with the Faraday environment object
-# @yieldparam result [<%= method.doc_response_type %>]
+# @yield [result, response] Access the result along with the Faraday response object
+# @yieldparam result [<%= method.rest.doc_response_type %>]
 # @yieldparam response [::Faraday::Response]
 #
-# @return [<%= method.doc_response_type %>]
+# @return [<%= method.rest.doc_response_type %>]

data/templates/default/service/rest/service_stub/_service_stub.erb

@@ -0,0 +1,25 @@
+<%- assert_locals service -%>
+<% @requires = capture do %>
+  require "<%= service.proto_service_require %>"
+<% end %>
+##
+# REST service stub for the <%= service.name %> service.
+# service stub contains baseline method implementations
+# including transcoding, making the REST call and deserialing the response
+#
+class <%= service.rest.service_stub_name %>
+  def initialize endpoint:, credentials:
+    # 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, credentials: credentials
+  end
+
+  <%- service.methods.each do |method| -%>
+
+  <%= indent_tail render(partial: "service/rest/service_stub/method/def", locals: { method: method }), 2 %>
+
+  <%= indent_tail render(partial: "service/rest/service_stub/grpc_transcoding_method/def", locals: { method: method }), 2 %>
+  <%- end %>
+end

data/templates/default/service/rest/{grpc_transcoding/method → service_stub/grpc_transcoding_method}/_def.erb

@@ -1,4 +1,7 @@
 <%- assert_locals method -%>
+##
+# GRPC transcoding helper method for the <%= method.name %> REST call
+#
 # @param request_pb [<%= method.request_type %>]
 #   A request object representing the call parameters. Required.
 # @return [Array(String, [String, nil], Hash{String => String})] 
@@ -13,7 +16,7 @@ def <%= method.rest.transcoding_helper_name %> request_pb
   query_string_params = {}
   <%- if method.rest.query_string_params? -%>
   <%- method.rest.query_string_params.each do |field| -%>
-  <%= render partial: "service/rest/grpc_transcoding/method/def/query_string_param", locals: { field: field } -%>
+  <%= render partial: "service/rest/service_stub/grpc_transcoding_method/def/query_string_param", locals: { field: field } -%>
   <%- end -%>
   <%- end -%>
 

data/templates/default/service/rest/service_stub/method/_def.erb

@@ -0,0 +1,20 @@
+<%- assert_locals method -%>
+##
+# Baseline implementation for the <%= method.name %> REST call
+#
+# @param request_pb [<%= method.rest.request_type %>]
+#   A request object representing the call parameters. Required.
+# @param options [::Gapic::CallOptions]
+#   Overrides the default settings for this call, e.g, timeout, retries etc. Optional.
+#
+# @yield [result, response] Access the result along with the Faraday response object
+# @yieldparam result [<%= method.rest.return_type %>]
+# @yieldparam response [::Faraday::Response]
+#
+# @return [<%= method.rest.return_type %>]
+#   A result object deserialized from the server's reply
+def <%= method.name %> request_pb, options = nil
+<%= indent render(partial: "service/rest/service_stub/method/def/request", locals: { method: method }), 2 %>
+
+<%= indent render(partial: "service/rest/service_stub/method/def/response", locals: { method: method }), 2 %>
+end

data/templates/default/service/rest/service_stub/method/def/_request.erb

@@ -0,0 +1,2 @@
+<%- assert_locals method -%>
+raise ::ArgumentError, "request must be provided" if request_pb.nil?