gapic-generator 0.1.4

data/templates/default/layouts/_ruby.erb

@@ -0,0 +1,20 @@
+<%- assert_locals namespace -%>
+<%= render partial: "shared/header" -%>
+<%- if instance_variable_defined? :@requires -%>
+
+<%= @requires -%>
+<%- end -%>
+<%- # Two newlines here so YARD won't use the header as documentation -%>
+
+
+<%- namespace.split("::").each_with_index do |ns, i| -%>
+<%= indent "module #{ns}", i*2 %>
+<%- end -%>
+<%= indent yield, namespace.split("::").count*2 %>
+<%- namespace.split("::").count.times do |i| -%>
+<%= indent "end", (namespace.split("::").count-1-i)*2 %>
+<%- end -%>
+<%- if instance_variable_defined? :@footer -%>
+
+<%= @footer -%>
+<%- end -%>

data/templates/default/package.erb

@@ -0,0 +1,6 @@
+<%- assert_locals package -%>
+<%= render partial: "shared/header" -%>
+
+<% package.services.each do |service| %>
+require "<%= service.service_require %>"
+<% end %>

data/templates/default/proto_docs/_enum.erb

@@ -0,0 +1,13 @@
+<%- assert_locals enum -%>
+<%- if enum.doc_description -%>
+<%= indent enum.doc_description, "# " %>
+<%- end -%>
+module <%= enum.name %>
+  <%- enum.values.each do |value| -%>
+
+  <%- if value.doc_description -%>
+<%= indent value.doc_description, "  # " %>
+  <%- end -%>
+  <%= value.name %> = <%= value.number %>
+  <%- end -%>
+end

data/templates/default/proto_docs/_message.erb

@@ -0,0 +1,23 @@
+<%- assert_locals message -%>
+<%- if message.doc_description -%>
+<%= indent message.doc_description, "# " %>
+<%- end -%>
+<%- message.fields.each do |field| -%>
+<%= indent field.doc_attribute_type, "# " %>
+#   @return [<%= field.output_doc_types %>]
+<%- if field.doc_description -%>
+<%= indent field.doc_description, "#     " %>
+<%- end -%>
+<%- end -%>
+class <%= message.name %>
+  include Google::Protobuf::MessageExts
+  extend Google::Protobuf::MessageExts::ClassMethods
+  <%- message.nested_messages.each do |submsg| -%>
+
+  <%= indent_tail render(partial: "proto_docs/message", locals: { message: submsg }), 2 %>
+  <%- end -%>
+  <%- message.nested_enums.each do |enum| -%>
+
+  <%= indent_tail render(partial: "proto_docs/enum", locals: { enum: enum }), 2 %>
+  <%- end -%>
+end

data/templates/default/proto_docs/_proto_file.erb

@@ -0,0 +1,9 @@
+<%- assert_locals file -%>
+<%- file.messages.each do |message| -%>
+
+<%= render(partial: "proto_docs/message", locals: { message: message }) -%>
+<%- end -%>
+<%- file.enums.each do |enum| -%>
+
+<%= render(partial: "proto_docs/enum", locals: { enum: enum }) -%>
+<%- end -%>

data/templates/default/proto_docs/proto_file.erb

@@ -0,0 +1,6 @@
+<%- assert_locals file -%>
+<%= render partial: "proto_docs/proto_file",
+           layout: "layouts/ruby",
+           locals: { file: file,
+                     namespace: file.namespace }
+%>

data/templates/default/proto_docs/readme.erb

@@ -0,0 +1,5 @@
+<%- assert_locals gem -%>
+# <%= gem.title %> Protocol Buffer Documentation
+
+These files are for the YARD documentation of the generated protobuf files.
+They are not intended to be required or loaded at runtime.

data/templates/default/service.erb

@@ -0,0 +1,8 @@
+<%- assert_locals service -%>
+<%= render partial: "shared/header" -%>
+
+require "<%= service.client_require %>"
+<%- if service.lro? -%>
+require "<%= service.operations_require %>"
+<%- end -%>
+require "<%= service.credentials_require %>"

data/templates/default/service/client.erb

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

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

@@ -0,0 +1,137 @@
+<%- assert_locals service -%>
+<% @requires = capture do %>
+require "gapic/common"
+require "gapic/config"
+require "gapic/config/method"
+
+<%= render partial: "service/client/requires", locals: { service: service} -%>
+require "<%= service.gem.version_require %>"
+require "<%= service.proto_service_require %>"
+require "<%= service.credentials_require %>"
+<%- if service.paths? -%>
+require "<%= service.paths_require %>"
+<%- end -%>
+<%- if service.lro? -%>
+require "<%= service.operations_require %>"
+<%- end -%>
+<% end %>
+# Service that implements <%= service.name %> API.
+class <%= service.client_name %>
+<%- if service.paths? -%>
+  include <%= service.paths_name %>
+
+<%- end -%>
+  # @private
+  attr_reader :<%= service.stub_name %>
+
+  ##
+  # Configure the <%= service.name %> <%= service.client_name %> class.
+  #
+  # See {<%= service.client_name_full %>::Configuration}
+  # for a description of the configuration fields.
+  #
+  # ## Example
+  #
+  # To modify the configuration for all <%= service.name %> clients:
+  #
+  #     <%= service.client_name_full %>.configure do |config|
+  #       config.timeout = 10_000
+  #     end
+  #
+  # @yield [config] Configure the <%= service.client_name %> client.
+  # @yieldparam config [<%= service.client_name %>::Configuration]
+  #
+  # @return [<%= service.client_name %>::Configuration]
+  #
+  def self.configure
+<%= indent render(partial: "service/client/self_configure", locals: { service: service }), 4 %>
+  end
+
+  ##
+  # Configure the <%= service.name %> <%= service.client_name %> instance.
+  #
+  # The configuration is set to the derived mode, meaning that values can be changed,
+  # but structural changes (adding new fields, etc.) are not allowed. Structural changes
+  # should be made on {<%= service.client_name %>.configure}.
+  #
+  # See {<%= service.client_name_full %>::Configuration}
+  # for a description of the configuration fields.
+  #
+  # @yield [config] Configure the <%= service.client_name %> client.
+  # @yieldparam config [<%= service.client_name %>::Configuration]
+  #
+  # @return [<%= service.client_name %>::Configuration]
+  #
+  def configure
+    yield @config if block_given?
+    @config
+  end
+
+  ##
+  # Create a new <%= service.name %> client object.
+  #
+  # ## Examples
+  #
+  # To create a new <%= service.name %> client with the default
+  # configuration:
+  #
+  #     client = <%= service.client_name_full %>.new
+  #
+  # To create a new <%= service.name %> client with a custom
+  # configuration:
+  #
+  #     client = <%= service.client_name_full %>.new do |config|
+  #       config.timeout = 10_000
+  #     end
+  #
+  # @yield [config] Configure the <%= service.name %> client.
+  # @yieldparam config [<%= service.client_name %>::Configuration]
+  #
+  def initialize
+    # These require statements are intentionally placed here to initialize
+    # the gRPC module only when it's required.
+    # See https://github.com/googleapis/toolkit/issues/446
+    require "gapic/grpc"
+    require "<%= service.proto_services_require %>"
+
+    # Create the configuration object
+    @config = Configuration.new <%= service.client_name %>.configure
+
+    # Yield the configuration if needed
+    yield @config if block_given?
+
+    # Create credentials
+    credentials = @config.credentials
+    credentials ||= Credentials.default scope: @config.scope
+    if credentials.is_a?(String) || credentials.is_a?(Hash)
+      credentials = Credentials.new credentials, scope: @config.scope
+    end
+    @quota_project_id = credentials.respond_to?(:quota_project_id) ? credentials.quota_project_id : nil
+
+    <%- if service.lro? -%>
+    <%= service.lro_client_ivar %> = <%= service.operations_name %>.new do |config|
+      config.credentials = credentials
+    end
+
+    <%- end -%>
+    @<%= service.stub_name %> = Gapic::ServiceStub.new(
+      <%= service.proto_service_stub_name_full %>,
+      credentials:  credentials,
+      endpoint:     @config.endpoint,
+      channel_args: @config.channel_args,
+      interceptors: @config.interceptors
+    )
+  end
+
+  # Service calls
+  <%- service.methods.each do |method| -%>
+
+  <%= indent_tail render(partial: "service/client/method/def", locals: { method: method }), 2 %>
+  <%- end %>
+
+  <%= indent_tail render(partial: "service/client/config", locals: { service: service }), 2 %>
+end
+
+<% @footer = capture do %>
+<%= render partial: "service/client/helpers", locals: { service: service} %>
+<% end %>

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

@@ -0,0 +1,155 @@
+<%- assert_locals service -%>
+<%- method_service ||= service  -%>
+##
+# Configuration class for the <%= service.name %> API.
+#
+# This class represents the configuration for <%= service.name %>,
+# providing control over timeouts, retry behavior, logging, transport
+# parameters, and other low-level controls. Certain parameters can also be
+# applied individually to specific RPCs. See
+# {<%= service.client_name_full %>::Configuration::Rpcs}
+# for a list of RPCs that can be configured independently.
+#
+# Configuration can be applied globally to all clients, or to a single client
+# on construction.
+#
+<%- unless method_service.methods.empty? -%>
+# # Examples
+#
+# To 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_000
+#       config.rpcs.<%= method_service.methods.first.name %>.timeout = 20_000
+#     end
+#
+# To apply the above configuration only to a new client:
+#
+#     client = <%= service.client_name_full %>.new do |config|
+#       config.timeout = 10_000
+#       config.rpcs.<%= method_service.methods.first.name %>.timeout = 20_000
+#     end
+#
+<%- end -%>
+# @!attribute [rw] endpoint
+#   The hostname or hostname:port of the service endpoint.
+#   Defaults to `<%= service.client_endpoint.inspect %>`.
+#   @return [String]
+# @!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))
+#    *  (`Signet::OAuth2::Client`) A signet oauth2 client object
+#       (see the [signet docs](https://googleapis.dev/ruby/signet/latest/Signet/OAuth2/Client.html))
+#    *  (`GRPC::Core::Channel`) a gRPC channel with included credentials
+#    *  (`GRPC::Core::ChannelCredentials`) a gRPC credentails object
+#    *  (`nil`) indicating no credentials
+#   @return [Object]
+# @!attribute [rw] scope
+#   The OAuth scopes
+#   @return [Array<String>]
+# @!attribute [rw] lib_name
+#   The library name as recorded in instrumentation and logging
+#   @return [String]
+# @!attribute [rw] lib_version
+#   The library version as recorded in instrumentation and logging
+#   @return [String]
+# @!attribute [rw] channel_args
+#   Extra parameters passed to the gRPC channel. Note: this is ignored if a
+#   `GRPC::Core::Channel` object is provided as the credential.
+#   @return [Hash]
+# @!attribute [rw] interceptors
+#   An array of interceptors that are run before calls are executed.
+#   @return [Array<GRPC::ClientInterceptor>]
+# @!attribute [rw] timeout
+#   The call timeout in milliseconds.
+#   @return [Numeric]
+# @!attribute [rw] metadata
+#   Additional gRPC headers to be sent with the call.
+#   @return [Hash{Symbol=>String}]
+# @!attribute [rw] retry_policy
+#   The retry policy. The value is a hash with the following keys:
+#    *  `:initial_delay` (*type:* `Numeric`) - The initial delay in seconds.
+#    *  `:max_delay` (*type:* `Numeric`) - The max delay in seconds.
+#    *  `:multiplier` (*type:* `Numeric`) - The incremental backoff multiplier.
+#    *  `:retry_codes` (*type:* `Array<String>`) - The error codes that should
+#       trigger a retry.
+#   @return [Hash]
+#
+class Configuration
+  extend Gapic::Config
+
+  config_attr :endpoint,     <%= service.client_endpoint.inspect %>, String
+  config_attr :credentials,  nil do |value|
+    allowed = [::String, ::Hash, ::Proc, ::Google::Auth::Credentials, ::Signet::OAuth2::Client, nil]
+    allowed += [::GRPC::Core::Channel, ::GRPC::Core::ChannelCredentials] if defined? ::GRPC
+    allowed.any? { |klass| klass === value }
+  end
+  config_attr :scope,        nil, String, Array, nil
+  config_attr :lib_name,     nil, String, nil
+  config_attr :lib_version,  nil, String, nil
+  config_attr(:channel_args, <%= service.config_channel_args.inspect %>, Hash, nil)
+  config_attr :interceptors, nil, Array, nil
+  config_attr :timeout,      nil, Numeric, nil
+  config_attr :metadata,     nil, Hash, nil
+  config_attr :retry_policy, nil, Hash, Proc, nil
+
+  # @private
+  def initialize parent_config = nil
+    @parent_config = parent_config unless parent_config.nil?
+
+    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 @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 milliseconds
+  #  *  `metadata` (*type:* `Hash{Symbol=>String}`) - Additional gRPC headers
+  #  *  `retry_policy (*type:* `Hash`) - The retry policy. The policy fields
+  #     include the following keys:
+  #      *  `:initial_delay` (*type:* `Numeric`) - The initial delay in seconds.
+  #      *  `:max_delay` (*type:* `Numeric`) - The max delay in seconds.
+  #      *  `:multiplier` (*type:* `Numeric`) - The incremental backoff multiplier.
+  #      *  `:retry_codes` (*type:* `Array<String>`) - The error codes that should
+  #         trigger a retry.
+  # 
+  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/client/_credentials.erb

@@ -0,0 +1,21 @@
+<%- assert_locals service -%>
+<% @requires = capture do %>
+require "googleauth"
+<% end %>
+# Credentials for the <%= service.name %> API.
+class <%= service.credentials_name %> < Google::Auth::Credentials
+  <%- if service.client_scopes.any? -%>
+  self.scope = [
+  <%- service.client_scopes.each_with_index do |client_scope, index| -%>
+    <%- comma = index == service.client_scopes.count - 1 ? "" : "," -%>
+    <%= client_scope.inspect %><%= comma %>
+  <%- end -%>
+  ]
+  <%- end -%>
+  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

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

@@ -0,0 +1,9 @@
+# rubocop:disable Lint/HandleExceptions
+
+# Once client is loaded, load helpers.rb if it exists.
+begin
+  require "<%= service.helpers_require %>"
+rescue LoadError
+end
+
+# rubocop:enable Lint/HandleExceptions

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

@@ -0,0 +1,88 @@
+<%- assert_locals service -%>
+<% @requires = capture do %>
+require "gapic/common"
+require "gapic/operation"
+
+require "<%= service.gem.version_require %>"
+require "<%= service.client_require %>"
+require "<%= service.lro_service.proto_service_require %>"
+<% end %>
+# Service that implements Longrunning Operations API.
+class <%= service.operations_name %>
+  # @private
+  attr_reader :<%= service.lro_service.stub_name %>
+
+  ##
+  # Configuration for the <%= service.name %> Operations API.
+  #
+  # @yield [config] Configure the <%= service.operations_name %> client.
+  # @yieldparam config [<%= service.operations_name %>::Configuration]
+  #
+  # @return [<%= service.operations_name %>::Configuration]
+  #
+  def self.configure
+    @configure ||= <%= service.operations_name %>::Configuration.new
+    yield @configure if block_given?
+    @configure
+  end
+
+  ##
+  # Configure the <%= service.name %> <%= service.operations_name %> instance.
+  #
+  # The configuration is set to the derived mode, meaning that values can be changed,
+  # but structural changes (adding new fields, etc.) are not allowed. Structural changes
+  # should be made on {<%= service.operations_name %>.configure}.
+  #
+  # @yield [config] Configure the <%= service.operations_name %> client.
+  # @yieldparam config [<%= service.operations_name %>::Configuration]
+  #
+  # @return [<%= service.operations_name %>::Configuration]
+  #
+  def configure
+    yield @config if block_given?
+    @config
+  end
+
+  ##
+  # Create a new <%= service.operations_name %> client object.
+  #
+  # @yield [config] Configure the <%= service.client_name %> client.
+  # @yieldparam config [<%= service.operations_name %>::Configuration]
+  #
+  def initialize
+    # These require statements are intentionally placed here to initialize
+    # the gRPC module only when it's required.
+    # See https://github.com/googleapis/toolkit/issues/446
+    require "gapic/grpc"
+    require "<%= service.lro_service.proto_services_require %>"
+
+    # Create the configuration object
+    @config = Configuration.new <%= service.operations_name %>.configure
+
+    # Yield the configuration if needed
+    yield @config if block_given?
+
+    # Create credentials
+    credentials = @config.credentials
+    credentials ||= Credentials.default scope: @config.scope
+    if credentials.is_a?(String) || credentials.is_a?(Hash)
+      credentials = Credentials.new credentials, scope: @config.scope
+    end
+
+    @<%= service.lro_service.stub_name %> = Gapic::ServiceStub.new(
+      <%= service.lro_service.proto_service_stub_name_full %>,
+      credentials:  credentials,
+      endpoint:     @config.endpoint,
+      channel_args: @config.channel_args,
+      interceptors: @config.interceptors
+    )
+  end
+
+  # Service calls
+  <%- service.lro_service.methods.each do |method| -%>
+
+  <%= indent_tail render(partial: "service/client/method/def", locals: { method: method }), 2 %>
+  <%- end %>
+
+  <%= indent_tail render(partial: "service/client/config", locals: { service: service.lro_service }), 2 %>
+end