impl(generator): add support for services that support both global and location endpoints (#15184)

Author: scotthart

generator/generator_config.proto

@@ -94,6 +94,12 @@ message ServiceConfiguration {
     // but were subsequently acknowledged to be "LOCATION_DEPENDENT".
     // Do not use for new services.
     LOCATION_DEPENDENT_COMPAT = 2;
+
+    // Some services support both global and location specific endpoints.
+    // This directs the generator to emit overloads for both:
+    //   `Make*Connection(Options options = {})`
+    //   `Make*Connection(std::string const& location, Options options = {})`
+    LOCATION_OPTIONALLY_DEPENDENT = 3;
   }
   EndpointLocationStyle endpoint_location_style = 15;
 

generator/integration_tests/golden/v1/golden_rest_only_rest_connection.cc

@@ -35,12 +35,12 @@ namespace golden_v1 {
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 
 std::shared_ptr<GoldenRestOnlyConnection> MakeGoldenRestOnlyConnectionRest(
-    Options options) {
+    std::string const& location, Options options) {
   internal::CheckExpectedOptions<CommonOptionList, RestOptionList,
       UnifiedCredentialsOptionList, rest_internal::TargetApiVersionOption,
       GoldenRestOnlyPolicyOptionList>(options, __func__);
   options = golden_v1_internal::GoldenRestOnlyDefaultOptions(
-      std::move(options));
+      location, std::move(options));
   auto background = std::make_unique<
       rest_internal::AutomaticallyCreatedRestBackgroundThreads>();
   auto stub = golden_v1_internal::CreateDefaultGoldenRestOnlyRestStub(
@@ -51,6 +51,11 @@ std::shared_ptr<GoldenRestOnlyConnection> MakeGoldenRestOnlyConnectionRest(
           std::move(background), std::move(stub), std::move(options)));
 }
 
+std::shared_ptr<GoldenRestOnlyConnection> MakeGoldenRestOnlyConnectionRest(
+    Options options) {
+  return MakeGoldenRestOnlyConnectionRest(std::string{}, std::move(options));
+}
+
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace golden_v1
 }  // namespace cloud

generator/integration_tests/golden/v1/golden_rest_only_rest_connection.h

@@ -23,6 +23,7 @@
 #include "google/cloud/options.h"
 #include "google/cloud/version.h"
 #include <memory>
+#include <string>
 
 namespace google {
 namespace cloud {
@@ -50,9 +51,19 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
  * @note Unexpected options will be ignored. To log unexpected options instead,
  *     set `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment.
  *
+ * @param location Sets the prefix for the default `EndpointOption` value.
  * @param options (optional) Configure the `GoldenRestOnlyConnection` created by
  * this function.
  */
+std::shared_ptr<GoldenRestOnlyConnection> MakeGoldenRestOnlyConnectionRest(
+    std::string const& location, Options options = {});
+
+/**
+ * A factory function to construct an object of type `GoldenRestOnlyConnection`.
+ *
+ * This overload of `MakeGoldenRestOnlyConnectionRest` does not require a location
+ * argument, creating a connection to the global service endpoint.
+ */
 std::shared_ptr<GoldenRestOnlyConnection> MakeGoldenRestOnlyConnectionRest(
     Options options = {});
 

generator/integration_tests/golden/v1/internal/golden_rest_only_option_defaults.cc

@@ -21,6 +21,7 @@
 #include "generator/integration_tests/golden/v1/golden_rest_only_options.h"
 #include "google/cloud/internal/populate_common_options.h"
 #include "google/cloud/internal/populate_grpc_options.h"
+#include "google/cloud/internal/absl_str_cat_quiet.h"
 #include <memory>
 #include <utility>
 
@@ -33,11 +34,11 @@ namespace {
 auto constexpr kBackoffScaling = 2.0;
 }  // namespace
 
-Options GoldenRestOnlyDefaultOptions(Options options) {
+Options GoldenRestOnlyDefaultOptions(std::string const& location, Options options) {
   options = internal::PopulateCommonOptions(
       std::move(options), "GOOGLE_CLOUD_CPP_GOLDEN_REST_ONLY_ENDPOINT",
       "", "GOOGLE_CLOUD_CPP_GOLDEN_REST_ONLY_AUTHORITY",
-      "goldenrestonly.googleapis.com");
+      absl::StrCat(location, location.empty() ? "" : "-", "goldenrestonly.googleapis.com"));
   options = internal::PopulateGrpcOptions(std::move(options));
   if (!options.has<golden_v1::GoldenRestOnlyRetryPolicyOption>()) {
     options.set<golden_v1::GoldenRestOnlyRetryPolicyOption>(

generator/integration_tests/golden/v1/internal/golden_rest_only_option_defaults.h

@@ -21,13 +21,14 @@
 
 #include "google/cloud/options.h"
 #include "google/cloud/version.h"
+#include <string>
 
 namespace google {
 namespace cloud {
 namespace golden_v1_internal {
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 
-Options GoldenRestOnlyDefaultOptions(Options options);
+Options GoldenRestOnlyDefaultOptions(std::string const& location, Options options);
 
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace golden_v1_internal

generator/integration_tests/golden/v1/samples/deprecated_client_samples.cc

@@ -42,7 +42,7 @@ void SetClientEndpoint(std::vector<std::string> const& argv) {
   //     https://cloud.google.com/vpc/docs/private-google-access
   auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
       "private.googleapis.com");
-  auto client = google::cloud::golden_v1::DeprecatedServiceClient(
+  auto vpc_client = google::cloud::golden_v1::DeprecatedServiceClient(
       google::cloud::golden_v1::MakeDeprecatedServiceConnection(options));
   //! [set-client-endpoint]
 }

generator/integration_tests/golden/v1/samples/golden_kitchen_sink_client_samples.cc

@@ -42,7 +42,7 @@ void SetClientEndpoint(std::vector<std::string> const& argv) {
   //     https://cloud.google.com/vpc/docs/private-google-access
   auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
       "private.googleapis.com");
-  auto client = google::cloud::golden_v1::GoldenKitchenSinkClient(
+  auto vpc_client = google::cloud::golden_v1::GoldenKitchenSinkClient(
       google::cloud::golden_v1::MakeGoldenKitchenSinkConnection(options));
   //! [set-client-endpoint]
 }

generator/integration_tests/golden/v1/samples/golden_rest_only_client_samples.cc

@@ -38,11 +38,17 @@ void SetClientEndpoint(std::vector<std::string> const& argv) {
     throw google::cloud::testing_util::Usage{"set-client-endpoint"};
   }
   //! [set-client-endpoint]
+  // This service supports specifying a regional or locational endpoint prefix
+  // when creating the GoldenRestOnlyConnectionRest.
+  // For example, to connect to "europe-central2-goldenrestonly.googleapis.com":
+  auto client = google::cloud::golden_v1::GoldenRestOnlyClient(
+      google::cloud::golden_v1::MakeGoldenRestOnlyConnectionRest("europe-central2"));
+
   // This configuration is common with Private Google Access:
   //     https://cloud.google.com/vpc/docs/private-google-access
   auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
       "private.googleapis.com");
-  auto client = google::cloud::golden_v1::GoldenRestOnlyClient(
+  auto vpc_client = google::cloud::golden_v1::GoldenRestOnlyClient(
       google::cloud::golden_v1::MakeGoldenRestOnlyConnectionRest(options));
   //! [set-client-endpoint]
 }

generator/integration_tests/golden/v1/samples/golden_thing_admin_client_samples.cc

@@ -44,7 +44,7 @@ void SetClientEndpoint(std::vector<std::string> const& argv) {
   //     https://cloud.google.com/vpc/docs/private-google-access
   auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
       "private.googleapis.com");
-  auto client = google::cloud::golden_v1::GoldenThingAdminClient(
+  auto vpc_client = google::cloud::golden_v1::GoldenThingAdminClient(
       google::cloud::golden_v1::MakeGoldenThingAdminConnection(options));
   //! [set-client-endpoint]
 }

generator/integration_tests/golden/v1/samples/request_id_client_samples.cc

@@ -44,7 +44,7 @@ void SetClientEndpoint(std::vector<std::string> const& argv) {
   //     https://cloud.google.com/vpc/docs/private-google-access
   auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
       "private.googleapis.com");
-  auto client = google::cloud::golden_v1::RequestIdServiceClient(
+  auto vpc_client = google::cloud::golden_v1::RequestIdServiceClient(
       google::cloud::golden_v1::MakeRequestIdServiceConnection(options));
   //! [set-client-endpoint]
 }