gapic-generator 0.11.0 → 0.45.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8baa3144f849b60f36cb51b7c7bed258165e9b3a646816aad586912001e4ddc
-  data.tar.gz: f1dc6fb877e18c0eed6c461bf6937d3756409da0bb259484149c377244953a70
+  metadata.gz: 2f2a5263485263873c059ce342f1cd26c800bab3349b7b191132b57f79d986ea
+  data.tar.gz: eda4ecd48fe183ffd4f98927f80c6500fc7b1d578fd8a45f4d539c5e0cecc9bd
 SHA512:
-  metadata.gz: 90b475c396bcdd3ecdadec8fb27e3e8089e6c8525ad75d2f83142525684b898a38765ebde17d22262e2acaac56b8452e6d77b6a6f2ccc4fab4c21ad3997c9019
-  data.tar.gz: 84b4aab4d800b042c4be22f3159ca77fa1cc3489a903b79844d239202c56ffb0c02db39957afa7c0bee28b168547ff1e5afda93d373450f5f8a0e14feb969147
+  metadata.gz: a49ad3a37ed0d730ef3bed251a2d58f06a4f9686d9fb4d65bcc163e1074ff76d427396798e3e9223a9b2d0d4d82be27c712f9c079f3379f573fe7026bfebbd29
+  data.tar.gz: 84dd1fd882a77ff2c659d3d17e56722bb0f80240dc8a644c282290c321a090352ff315c415d4f0e74172830560868f143b9e48fe0b319ae8a56a36680b0f5089

data/CHANGELOG.md

@@ -1,5 +1,308 @@
 # Release History for gapic-generator
 
+### 0.45.2 / 2025-06-04
+
+* Fix: update Ruby prebuilt binary, version 3.4.3
+
+### 0.45.1 / 2025-05-01
+
+No significant changes
+
+### 0.45.0 / 2025-05-01
+
+* Feature: Updated rails to 8.0
+* Feature: Update protobuf to 4.30
+* Feature: Update common dependencies for generated clients
+* Fix: update Ruby prebuilt binary, version 3.4.3
+
+### 0.44.0 / 2025-04-30
+
+* Feature: Update Ruby for the generator to 3.2.8 including prebuilt binary
+* Feature: Set minumum Ruby version for generated code to 3.1 and use google-style 1.31
+
+### 0.43.0 / 2025-04-24
+
+* Fix: Fixed typo in generated wrapper readmes
+* Fix: Provide a better check for grpc when typechecking credentials
+* Feature: bless "::Google::Auth::BaseClient" as an allowed by default credentials type in Config
+
+### 0.42.1 / 2025-02-04
+
+* Fix: Wrappers load release dependencies if local dependencies do not match
+
+### 0.42.0 / 2025-01-30
+
+* Feature: Change REGAPIC pagination algorithm to the standard algorithm for non-compute clients
+
+### 0.41.0 / 2025-01-24
+
+* Feature: Change minimum Ruby version to 3.0
+
+### 0.40.0 / 2025-01-24
+
+No significant changes
+
+### 0.39.2 / 2025-01-24
+
+* Fix: Add warning regarding external credential sourcing
+
+### 0.39.1 / 2025-01-23
+
+* Fix: Updated minimum gapic-common version to 0.25
+
+### 0.39.0 / 2025-01-22
+
+* Feature: Add clarifying notes to oneof members in proto_docs
+
+### 0.38.3 / 2024-12-10
+
+* Fix: Added logger methods to generated dummy stub classes in generated tests
+
+### 0.38.2 / 2024-12-10
+
+* Fix: Throw the correct result object for REST with nonstandard LRO
+
+### 0.38.1 / 2024-12-09
+
+* Fix: fix wrapper gem tests by stubbing the stub_logger method
+
+### 0.38.0 / 2024-12-06
+
+* Feature: Support request-response debug logging from generated GAPICs
+
+### 0.37.0 / 2024-10-24
+
+* Feature: Remove path tests for clients using REST without gRPC
+
+### 0.36.1 / 2024-09-20
+
+* Fix: Add missing local binding in resource path methods
+
+### 0.36.0 / 2024-08-22
+
+* Feature: Support local binding for variables with keyword collision
+
+### 0.35.0 / 2024-08-15
+
+* Feature: Disable xrefs for README files in wrapper gems
+
+### 0.34.1 / 2024-08-08
+
+No significant changes
+
+### 0.34.0 / 2024-08-07
+
+* Feature: Resolve keyword conflicts with path pattern variable names
+* Feature: Prevent keyword collision with field names as values
+* Feature: Refactor README.md and gemspec files
+
+### 0.33.0 / 2024-07-02
+
+* Fix: Resolve BigDecimal warning
+* Feature: Format path pattern variables to snake case
+
+### 0.32.0 / 2024-05-13
+
+* Feature: Introduce google.api.api_version option to generated clients
+
+### 0.31.0 / 2024-04-25
+
+* Feature: Remove api-common-protos dependency
+* Feature: Use module name to prevent keyword collision with enum values
+
+### 0.30.0 / 2024-04-24
+
+* Feature: support auto populating request fields with explicit presence
+* Feature: avoid keyword collision for enum value names
+* Fix: Start requiring ostruct in generated test helper files
+
+### 0.29.0 / 2024-02-22
+
+* Feature: Update minimum Ruby version of generated libraries to 2.7
+* Fix: update gemfiles and set bundle platforms to x86_64-linux
+
+### 0.28.0 / 2024-02-14
+
+* Feature: introduce auto_populated_fields (uuid4) to generator
+
+### 0.27.4 / 2024-01-12
+
+No significant changes
+
+### 0.27.3 / 2024-01-12
+
+* Fix: Ensure the correct endpoint gets to mixin clients
+
+### 0.27.2 / 2024-01-11
+
+No significant changes
+
+### 0.27.1 / 2024-01-09
+
+* Fix: Update mixin dependencies to versions that support universe domain
+
+### 0.27.0 / 2024-01-08
+
+* Feature: update generated samples docs
+* Feature: Update rubocop autofix to use Rubocop 1.59
+* Feature: add @deprecated tags to document items
+* Feature: Generate toys files
+* Feature: Support universe domain in GAPIC
+
+### 0.26.0 / 2023-12-04
+
+* Feature: Use google-protobuf instead of third-party protobuf library
+* Fix: clean up and update gem dependencies
+
+### 0.25.1 / 2023-09-12
+
+* Fix: Workaround for grpc windows issue during tests
+
+### 0.25.0 / 2023-09-07
+
+* Feature: Add support for channel pool in gapic generator
+* Fix: Fix snippet generation for REGAPIC clients
+
+### 0.24.0 / 2023-07-05
+
+* Feature: Loosen parsing for extra_dependencies
+
+### 0.23.4 / 2023-06-03
+
+* Fix: Updates to the bundle locks
+* Fix: Generated clients depend on gapic-common 0.19.1
+* Fix: Fixes the enable_self_signed_jwt determination when the endpoint in the global configuration object (as opposed to the constructor configuration block) is modified
+
+### 0.23.3 / 2023-05-26
+
+* Fix: Generated clients depend on gapic-common 0.19
+
+### 0.23.2 / 2023-03-08
+
+* Fix: Remove html tags from description text parsed from service yaml
+* Fix: Fail generation if Rubocop autoformatting fails
+* Fix: Replace googleapis.dev links with equivalent cloud.google.com or rubydoc.info links
+* Fix: Fix special case iam API shortname
+
+### 0.23.1 / 2023-02-28
+
+* Fix: update gapic-common version
+* Fix: Handle empty fields in service yaml
+
+### 0.23.0 / 2023-02-27
+
+* Feature: Honor metadata from the service yaml
+
+### 0.22.0 / 2023-02-14
+
+* Feature: Update mixin dependency versions to 0.4
+
+### 0.21.1 / 2023-02-13
+
+* Fix: Get rubocop working in bazel
+
+### 0.21.0 / 2023-02-09
+
+* Feature: Load and interpret snippetgen phase 2 config data
+* Feature: Added SnippetGen phase2 implementation
+* Feature: Reimplemented snippetgen phase 1 using phase 2
+* Feature: Implemented enough of SnippetGen phase 2 to generate the initial test case
+* Feature: add a transport operation class in Rest
+* Fix: yield TransportOperation class instead of Faraday's
+
+### 0.20.0 / 2023-01-19
+
+* Feature: migrate generator bazel (including prebuilts) to 3.1.3
+
+### 0.19.0 / 2023-01-17
+
+* Fix: fail on rest transport and no bindings
+* Feature: Bump mixin minimum version to 0.3
+
+### 0.18.1 / 2022-12-15
+
+* Fix: Don't generate bindings_override.rb unless REST transport is active
+
+### 0.18.0 / 2022-12-15
+
+* Feature: add quota project and misc to REGAPIC templates
+* Feature: use retry policy in regapic templates
+* Fix: avoid creating rest default configuration for non-rest methods
+* Fix: transcoding in regapic tests
+* Fix: Cross-ref links use the REST client class in REST client docs
+* Feature: implements template changes for REST server-streaming.
+* Feature: all fixes for the combined rest+grpc libraries
+* Feature: generate bindings override for REST mixins
+* Fix: handle only regapic errors for REST libraries
+* Feature: Recognize transport argument for bazel jobs
+* Feature: Updated wrapper generator to support multi-transport clients
+
+### 0.17.2 / 2022-10-27
+
+* Fix: Update snippetgen phase 1 to conform to standard sample style
+
+### 0.17.1 / 2022-10-26
+
+* Fix: Fixed typo in rest_numeric_enums bazel field handling
+
+### 0.17.0 / 2022-10-21
+
+* Feature: Recognize rest_numeric_enums argument for bazel jobs
+
+### 0.16.1 / 2022-09-27
+
+No significant changes
+
+### 0.16.0 / 2022-09-16
+
+* Feature: Support numeric enums
+
+### 0.15.3 / 2022-08-18
+
+* Fix: Fix out of date SDK auth documentation
+
+### 0.15.2 / 2022-07-27
+
+* Fix: only do service config http binding override on Operations
+* Fix: Apply both namespace and service overrides to service names in yard links
+
+### 0.15.1 / 2022-07-26
+
+* Fix: mixin proto_docs removal works for iam
+
+### 0.15.0 / 2022-07-25
+
+* Feature: classic (AIP-151) LROs in REST
+* Feature: grpc transcoding with `additional_bindings`
+* Fix: Honor service overrides in yard cross-references
+* Fix: suppress generation of mixin proto_docs and wrapper client factory methods
+
+### 0.14.1 / 2022-06-29
+
+* Fix: fix crash when generating generic endpoints
+
+### 0.14.0 / 2022-06-27
+
+* Feature: generate code using full GRPC transcoding for rest libraries
+* Feature: generating libraries with rest and grpc transports
+* Fix: LRO-wrapped methods of the internal Operations client not working
+* Feature: Update minimum Ruby version to 2.6
+
+### 0.13.0 / 2022-05-11
+
+* Feature: Adjust links and repo metadata based on whether the product is part of gcp/cloud
+* Fix: Loosen mixin dependencies to allow 1.x versions
+* Fix: Disable generation of services that are handled as mixins
+* Fix: Disable mixin generation when common services are configured
+
+### 0.12.0 / 2022-04-29
+
+* Feature: Generate snippet metadata files
+
+### 0.11.1 / 2022-04-06
+
+* Updated generated grpc-google-iam-v1 dependency to ~> 1.1
+
 ### 0.11.0 / 2022-03-01
 
 * New: Added generation of nonstandard LRO wrapper calls (currently used for Compute)

data/CONTRIBUTING.md

@@ -11,7 +11,7 @@ this simply gives us permission to use and redistribute your contributions as
 part of the project. Head over to <https://cla.developers.google.com/> to see
 your current agreements on file or to sign a new one.
 
-You generally only need to submit a CLA once, so if you've already submitted one
+You generally need to submit a CLA only once, so if you've already submitted one
 (even if it was for a different project), you probably don't need to do it
 again.
 

data/README.md

@@ -2,24 +2,59 @@
 
 Create Ruby clients from a protocol buffer description of an API.
 
-**Note** This project is a preview. Please try it out and let us know what you think,
-but there are currently no guarantees of stability or support.
-
-## Usage
+This code is used to generate client libraries for many Google APIs including
+Cloud and Ads services. The `gapic-generator` gem itself includes the main
+generator, whereas the `gapic-generator-cloud` and `gapic-generator-ads` gems
+provide modifications specific to Google Cloud and Google Ads APIs.
+
+These gems can also be used to create clients for any other API, for Google or
+non-Google services, that use protocol buffers as the description language. The
+generators will work best for APIs that follow the design guidance documented
+in the [Google AIPs](https://aip.dev/). An API that is not AIP-compliant should
+still yield a usable client library, but it may be missing features such as
+idiomatic naming, pagination, or retry configuration.
+
+**Important:** This is not an official Google project. While it is being used
+internally to generate official Google API client libraries, there is no
+guarantee of support or stability for any other use.
+
+## Using the Ruby gem
+
+This section provides a brief getting started guide for the Ruby gem. However,
+we do not release the Ruby gems often, and they may be substantially behind the
+current generator code. In most cases, we recommend generating from the
+GitHub repository directly. See the main README for
+https://github.com/googleapis/gapic-generator-ruby for more information.
 
 ### Install the Generator
 
-This tool is in pre-alpha so it is not yet released to RubyGems.
+The generator is a plugin for **protoc**, the protocol buffers compiler, so
+you'll need to install it first, along with the standard protobuf and grpc
+plugins for Ruby. The easiest way to do this is to install the `grpc-tools` gem
+which will provide all three. You can also follow the
+[official install instructions](https://github.com/protocolbuffers/protobuf#protobuf-compiler-installation).
+Note that if you installed protoc using `grpc-tools`, the compiler binary name
+will be named `grpc_tools_ruby_protoc`; otherwise it will likely be `protoc`.
+
+Install the `gapic-generator` gem to get access to the gapic generator plugin.
+
+Optionally install either `gapic-generator-cloud` or `gapic-generator-ads` if
+you want access to cloud-specific or ads-specific output.
+
+Alternatively, add all the above to a Gemfile:
+
+```ruby
+# Gemfile
+source "https://rubygems.org/"
+
+gem "grpc-tools"
+gem "gapic-generator"
+```
+
+And install using bundler:
 
 ```sh
-$ git clone https://github.com/googleapis/gapic-generator-ruby.git
-$ cd gapic-generator-ruby
-$ git submodule update --init
-$ cd gapic-generator
 $ bundle install
-$ bundle exec rake install
-$ which protoc-gen-ruby_gapic
-> {Non-empty path}
 ```
 
 ### Generate an API
@@ -28,45 +63,44 @@ Installing this generator exposes `protoc-gen-ruby_gapic` on the PATH. By doing
 so, it gives the protobuf compiler the CLI option `--ruby_gapic_out` on which
 you can specify an output path for this generator.
 
-If you want to experiment with an already-existing API, one example is available.
+In most cases, in order to generate a functional client library, you must also
+include the Ruby proto and grpc plugins, using the CLI options `--ruby_out` and
+`--grpc_out`.
+
+If you want to experiment with an already-existing API, you can use one of the
+existing Google APIs from https://github.com/googleapis/googleapis.
 First you should get the protos and dependencies:
 
 ```sh
-$ git clone git@github.com:googleapis/api-common-protos.git
 $ git clone git@github.com:googleapis/googleapis.git
 ```
 
-Now you're ready to compile the API:
+Now you're ready to compile the API. For example, to compile the Vision V1 API:
 
 ```sh
-$ protoc google/cloud/vision/v1/*.proto \
-    --proto_path=api-common-protos/ \
-    --proto_path=googleapis/ \
-    --ruby_gapic_out=/dest/
-```
-
-Or, if you don't have `protoc` installed, you can use `grpc_tools_ruby_protoc`
-from the `grpc-tools` gem:
-
-```sh
-$ gem install grpc-tools
 $ grpc_tools_ruby_protoc google/cloud/vision/v1/*.proto \
-    --proto_path=api-common-protos/ \
     --proto_path=googleapis/ \
-    --ruby_gapic_out=/dest/
+    --ruby_out=/path/to/dest/ \
+    --grpc_out=/path/to/dest/ \
+    --ruby_gapic_out=/path/to/dest/ \
 ```
 
-## Contributing
-
-Contributions to this library are always welcome and highly encouraged.
+Note: most real-world client libraries require additional options to be passed
+to the generator, via the `--ruby_gapic_opt` flag. Those options are not
+covered in this document.
 
-See the [CONTRIBUTING](CONTRIBUTING.md) documentation for more information on how to get started.
+If you want to use `gapic-generator-cloud` or `gapic-generator-ads`, see the
+README for that gem for specific information.
 
-## Versioning
+## Support
 
-This library is currently a **preview** with no guarantees of stability or support. Please get
-involved and let us know if you find it useful and we'll work towards a stable version.
+This is not an official Google project. While it is being used internally to
+generate official Google API client libraries, there is no guarantee of support
+or stability for any other use.
 
-## Disclaimer
+As of January 2024, this generator can be run on Ruby 3.0 or later. In general,
+we will make an effort to ensure it is supported on non-end-of-life versions of
+Ruby.
 
-This is not an official Google product.
+Issues can be filed on GitHub at
+https://github.com/googleapis/gapic-generator-ruby/issues.

data/bin/protoc-gen-ruby_gapic

@@ -17,7 +17,7 @@
 
 $LOAD_PATH.unshift ::File.expand_path("../lib", __dir__)
 require "gapic/runner"
-require "google/protobuf/compiler/plugin.pb"
+require "google/protobuf/compiler/plugin_pb"
 
 # Ensure that no encoding conversions are done on STDIN and STDOUT
 # since we are passing binary data back and forth. Otherwise these
@@ -30,4 +30,4 @@ request = Google::Protobuf::Compiler::CodeGeneratorRequest.decode $stdin.read
 # Run the request
 response = Gapic::Runner.run request
 
-$stdout.print response.serialize
+$stdout.print Google::Protobuf::Compiler::CodeGeneratorResponse.encode response

data/lib/gapic/file_formatter.rb

@@ -16,6 +16,7 @@
 
 require "tmpdir"
 require "fileutils"
+require "English"
 
 module Gapic
   ##
@@ -29,34 +30,37 @@ module Gapic
     #
     def initialize configuration, files
       @configuration = configuration
-      @files = format! configuration, files
+      @files = format! files
     end
 
     protected
 
-    def format! configuration, files
+    def format! files
       Dir.mktmpdir do |dir|
-        files.each do |file|
-          write_file dir, file
-        end
+        Dir.chdir dir do
+          files.each do |file|
+            FileUtils.mkdir_p File.dirname file.name
+            File.write file.name, file.content
+          end
 
-        system "rubocop --cache false -x #{dir} -o #{dir}/rubocop.out -c #{configuration}"
+          # Use the current Ruby binary path and invoke the CLI class directly
+          # rather than the normal rubocop executable, since the latter uses
+          # "/usr/bin/env ruby" which doesn't seem to work in the current bazel
+          # environment.
+          script = 'require "rubocop"; begin; RuboCop::CLI.new.run; rescue => e; p e; exit 1; end'
+          rubocop_cmd = "#{RbConfig.ruby} -e '#{script}' -- --cache false -a -o rubocop.out -c #{configuration}"
+          output = `#{rubocop_cmd}`.strip
+          unless output.empty?
+            warn "**** Rubocop output:"
+            warn output
+          end
+          raise "Rubocop failed" unless $CHILD_STATUS.success?
 
-        files.each do |file|
-          read_file dir, file
+          files.each do |file|
+            file.content = File.read file.name
+          end
         end
       end
     end
-
-    def write_file dir, file
-      tmp_file = File.join dir, file.name
-      FileUtils.mkdir_p File.dirname tmp_file
-      File.write tmp_file, file.content
-    end
-
-    def read_file dir, file
-      tmp_file = File.join dir, file.name
-      file.content = File.read tmp_file
-    end
   end
 end

data/lib/gapic/formatting_utils.rb

@@ -39,9 +39,12 @@ module Gapic
       # @param disable_xrefs [Boolean] (default is `false`) Disable linking to
       #   cross-references, and render them simply as text. This can be used if
       #   it is known that the targets are not present in the current library.
+      # @param transport [:grpc,:rest] Whether xref links should go to REST or
+      #   gRPC client classes. Uses the default transport if not provided.
       # @return [Enumerable<String>]
       #
-      def format_doc_lines api, lines, disable_xrefs: false
+      def format_doc_lines api, lines, disable_xrefs: false, transport: nil
+        transport ||= api&.default_transport || :grpc
         # To detect preformatted blocks, this tracks the "expected" base indent
         # according to Markdown. Specifically, this is the effective indent of
         # previous block, which is normally 0 except if we're in a list item.
@@ -58,7 +61,7 @@ module Gapic
             in_block, base_indent = update_indent_state in_block, base_indent, line, indent
             if in_block == false
               line = escape_line_braces line
-              line = format_line_xrefs api, line, disable_xrefs
+              line = format_line_xrefs api, line, disable_xrefs, transport
             end
           end
           line
@@ -99,7 +102,8 @@ module Gapic
 
       def line_indent line
         m = /^( *)\S/.match line
-        m.nil? ? nil : m[1].length
+        return nil unless m
+        m[1].length
       end
 
       def escape_line_braces line
@@ -109,12 +113,12 @@ module Gapic
         line
       end
 
-      def format_line_xrefs api, line, disable_xrefs
+      def format_line_xrefs api, line, disable_xrefs, transport
         while (m = @xref_detector.match line)
           entity = api.lookup m[:addr]
           return line if entity.nil?
           text = m[:text]
-          yard_link = disable_xrefs ? text : yard_link_for_entity(entity, text)
+          yard_link = disable_xrefs ? text : yard_link_for_entity(entity, text, transport)
           return line if yard_link.nil?
           line = "#{m[:pre]}#{yard_link}#{m[:post]}"
         end
@@ -126,9 +130,10 @@ module Gapic
       #
       # @param entity [Gapic::Schema::Proto] the entity to link to
       # @param text [String] the text for the link
+      # @param transport [:rest,:grpc] The transport for client classes
       # @return [String] YARD cross-reference syntax
       #
-      def yard_link_for_entity entity, text
+      def yard_link_for_entity entity, text, transport
         # As a special case, omit the service "google.longrunning.Operations"
         # and its methods. This is because the generator creates
         # service-specific copies of the operations client, rather than a
@@ -136,11 +141,14 @@ module Gapic
         # general no way to tell what the actual service-specific namespace is.
         return text if entity.address[0, 3] == ["google", "longrunning", "Operations"]
 
+        client_class = transport == :grpc ? "Client" : "Rest::Client"
         case entity
         when Gapic::Schema::Service
-          "{::#{convert_address_to_ruby entity}::Client #{text}}"
+          "{::#{convert_address_to_ruby entity, service: true}::#{client_class} #{text}}"
         when Gapic::Schema::Method
-          "{::#{convert_address_to_ruby entity.parent}::Client##{entity.name.underscore} #{text}}"
+          namespace = convert_address_to_ruby entity.parent, service: true
+          method_name = entity.name.underscore
+          "{::#{namespace}::#{client_class}##{method_name} #{text}}"
         when Gapic::Schema::Message, Gapic::Schema::Enum
           "{::#{convert_address_to_ruby entity} #{text}}"
         when Gapic::Schema::EnumValue
@@ -150,13 +158,19 @@ module Gapic
         end
       end
 
-      def convert_address_to_ruby entity
+      def convert_address_to_ruby entity, service: false
         file = entity.containing_file
         api = file.containing_api
         address = entity.address
         address = address.join "." if address.is_a? Array
         address = address.sub file.package, file.ruby_package if file.ruby_package&.present?
-        address.split(/\.|::/).reject(&:empty?).map(&:camelize).map { |node| api.fix_namespace node }.join("::")
+        address = address.split(/\.|::/).reject(&:empty?)
+        last_index = address.size - 1 if service
+        address.each_with_index.map do |node, index|
+          node = node.camelize
+          node = api.fix_service_name node if index == last_index
+          api.fix_namespace node
+        end.join "::"
       end
     end
   end