gapic-generator 0.7.5 → 0.10.0

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,12 +3,16 @@
 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 \
   lib_name: @config.lib_name, lib_version: @config.lib_version,
-  gapic_version: ::<%= method.service.gem.version_name_full %>
+  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,6 @@
+<%- assert_locals method -%>
+<%- if method.rest.paged? -%>
+<%= render partial: "service/rest/client/method/def/response_paged", 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_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.erb

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

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?

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

@@ -0,0 +1,17 @@
+<%- assert_locals method -%>
+
+uri, <%= method.rest.body_var_name %>, <%= method.rest.query_string_params_var_name %> = <%= method.rest.transcoding_helper_name %> request_pb
+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

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

@@ -0,0 +1,18 @@
+<%- assert_locals service -%>
+<%= render partial: "shared/header" %>
+require "helper"
+require "gapic/rest"
+require "<%= service.proto_service_require %>"
+require "<%= service.service_require %>"
+
+
+class <%= service.client_name_full %>Test < Minitest::Test
+<%= indent render(partial: "service/rest/test/method/setup"), 2 %>
+
+<% service.methods.each do |method| %>
+<%= indent render(partial: "service/rest/test/method/#{method.kind}",
+                  locals: { method: method }), 2 %>
+
+<% end %>
+<%= indent render(partial: "service/rest/test/method/configure", locals: { service: service }), 2 %>
+end

data/templates/default/service/rest/test/method/_assert_response.erb

@@ -0,0 +1,2 @@
+<%- assert_locals method -%>
+assert_equal http_response, response

data/templates/default/service/rest/test/method/_configure.erb

@@ -0,0 +1,19 @@
+<%- assert_locals service -%>
+<%- full_client_name = defined?(client_name_full) ? client_name_full : service.rest.client_name_full -%>
+def test_configure
+  credentials_token = :dummy_value
+
+  client = block_config = config = nil
+  Gapic::Rest::ClientStub.stub :new, nil do
+    client = <%= full_client_name =%>.new do |config|
+      config.credentials = credentials_token
+    end
+  end
+
+  config = client.configure do |c|
+    block_config = c
+  end
+
+  assert_same block_config, config
+  assert_kind_of <%= full_client_name %>::Configuration, config
+end

data/templates/default/service/rest/test/method/_normal.erb

@@ -0,0 +1,71 @@
+<%- assert_locals method -%>
+<%- full_client_name = defined?(client_name_full) ? client_name_full : method.service.rest.client_name_full -%>
+<%- fields = method.fields_with_first_oneof -%>
+def test_<%= method.name %>
+  # Create test objects.
+  client_result = <%= method.return_type %>.new
+  http_response = OpenStruct.new body: client_result.to_json
+
+  call_options = {}
+
+  # Create request parameters for a unary method.
+  <%- fields.each do |field| -%>
+  <%= field.name %> = <%= field.default_value %>
+  <%- end -%>
+
+  <%= method.name %>_client_stub = ClientStub.new http_response do |verb, uri:, body:, params:, options:|
+    assert_equal :<%= method.rest.verb %>, verb
+
+    assert options.metadata.key? :"x-goog-api-client"
+    assert options.metadata[:"x-goog-api-client"].include? "rest"
+    refute options.metadata[:"x-goog-api-client"].include? "grpc"
+
+    <%- if method.rest.query_string_params? -%>
+    <%- method.rest.query_string_params.each do |field| -%>
+    assert params.key? "<%= field.camel_name %>"
+    <%- end -%>
+    <%- end -%>
+    <%- if method.rest.body? %>
+    refute_nil body
+    <%- else -%>
+    assert_nil body
+    <%- end -%>
+  end
+
+  Gapic::Rest::ClientStub.stub :new, <%= method.name %>_client_stub do
+    # Create client
+    client = <%= full_client_name %>.new do  |config|
+      config.credentials = :dummy_value
+    end
+
+    # Use hash object
+    client.<%= method.name %>({ <%= fields.map(&:as_kwarg).join ", " %> }) do |result, response|
+      <%= indent_tail render(partial: "service/rest/test/method/assert_response", locals: { method: method }), 6 %>
+    end
+
+    <%- if fields.any? -%>
+    # Use named arguments
+    client.<%= method.name %> <%= fields.map(&:as_kwarg).join ", " %> do |result, response|
+      <%= indent_tail render(partial: "service/rest/test/method/assert_response", locals: { method: method }), 6 %>
+    end
+
+    <%- end -%>
+    # Use protobuf object
+    client.<%= method.name %> <%= method.request_type %>.new(<%= fields.map(&:as_kwarg).join ", " %>) do |result, response|
+      <%= indent_tail render(partial: "service/rest/test/method/assert_response", locals: { method: method }), 6 %>
+    end
+
+    # Use hash object with options
+    client.<%= method.name %>({ <%= fields.map(&:as_kwarg).join ", " %> }, call_options) do |result, response|
+      <%= indent_tail render(partial: "service/rest/test/method/assert_response", locals: { method: method }), 6 %>
+    end
+
+    # Use protobuf object with options
+    client.<%= method.name %>(<%= method.request_type %>.new(<%= fields.map(&:as_kwarg).join ", " %>), call_options) do |result, response|
+      <%= indent_tail render(partial: "service/rest/test/method/assert_response", locals: { method: method }), 6 %>
+    end
+
+    # Verify method calls
+    assert_equal <%= fields.any? ? 5 : 4 %>, <%= method.name %>_client_stub.call_count
+  end
+end