feat(pubsub): add MakeConnection overloads to support regional and locational endpoints (#15190)

Author: scotthart

generator/generator_config.textproto

@@ -3177,6 +3177,7 @@ service {
     "Publish"
   ]
   omit_repo_metadata: true
+  endpoint_location_style: LOCATION_OPTIONALLY_DEPENDENT
 }
 
 # Cloud Pub/Sub Generated Admin API
@@ -3199,6 +3200,7 @@ service {
   service_name_mapping { key: "Subscriber" value: "SubscriptionAdmin"}
   service_name_to_comment { key: "TopicAdmin" value: " A service to manipulate topics."}
   service_name_to_comment { key: "SubscriptionAdmin" value: " A service to manipulate subscriptions."}
+  endpoint_location_style: LOCATION_OPTIONALLY_DEPENDENT
 }
 
 service {
@@ -3207,6 +3209,7 @@ service {
   initial_copyright_year: "2023"
   retryable_status_codes: ["kUnavailable"]
   emulator_endpoint_env_var: "PUBSUB_EMULATOR_HOST"
+  endpoint_location_style: LOCATION_OPTIONALLY_DEPENDENT
 }
 
 # Pub/Sub Lite

google/cloud/pubsub/admin/internal/subscription_admin_option_defaults.cc

@@ -19,6 +19,7 @@
 #include "google/cloud/pubsub/admin/internal/subscription_admin_option_defaults.h"
 #include "google/cloud/pubsub/admin/subscription_admin_connection.h"
 #include "google/cloud/pubsub/admin/subscription_admin_options.h"
+#include "google/cloud/internal/absl_str_cat_quiet.h"
 #include "google/cloud/internal/populate_common_options.h"
 #include "google/cloud/internal/populate_grpc_options.h"
 #include <memory>
@@ -33,11 +34,14 @@ namespace {
 auto constexpr kBackoffScaling = 2.0;
 }  // namespace
 
-Options SubscriptionAdminDefaultOptions(Options options) {
+Options SubscriptionAdminDefaultOptions(std::string const& location,
+                                        Options options) {
   options = internal::PopulateCommonOptions(
       std::move(options), "GOOGLE_CLOUD_CPP_SUBSCRIBER_ENDPOINT",
       "PUBSUB_EMULATOR_HOST", "GOOGLE_CLOUD_CPP_SUBSCRIBER_AUTHORITY",
-      "pubsub.googleapis.com");
+      // optional location tag for generating docs
+      absl::StrCat(location, location.empty() ? "" : "-",
+                   "pubsub.googleapis.com"));
   options = internal::PopulateGrpcOptions(std::move(options));
   if (!options.has<pubsub_admin::SubscriptionAdminRetryPolicyOption>()) {
     options.set<pubsub_admin::SubscriptionAdminRetryPolicyOption>(

google/cloud/pubsub/admin/internal/subscription_admin_option_defaults.h

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

google/cloud/pubsub/admin/internal/topic_admin_option_defaults.cc

@@ -19,6 +19,7 @@
 #include "google/cloud/pubsub/admin/internal/topic_admin_option_defaults.h"
 #include "google/cloud/pubsub/admin/topic_admin_connection.h"
 #include "google/cloud/pubsub/admin/topic_admin_options.h"
+#include "google/cloud/internal/absl_str_cat_quiet.h"
 #include "google/cloud/internal/populate_common_options.h"
 #include "google/cloud/internal/populate_grpc_options.h"
 #include <memory>
@@ -33,11 +34,13 @@ namespace {
 auto constexpr kBackoffScaling = 2.0;
 }  // namespace
 
-Options TopicAdminDefaultOptions(Options options) {
+Options TopicAdminDefaultOptions(std::string const& location, Options options) {
   options = internal::PopulateCommonOptions(
       std::move(options), "GOOGLE_CLOUD_CPP_PUBLISHER_ENDPOINT",
       "PUBSUB_EMULATOR_HOST", "GOOGLE_CLOUD_CPP_PUBLISHER_AUTHORITY",
-      "pubsub.googleapis.com");
+      // optional location tag for generating docs
+      absl::StrCat(location, location.empty() ? "" : "-",
+                   "pubsub.googleapis.com"));
   options = internal::PopulateGrpcOptions(std::move(options));
   if (!options.has<pubsub_admin::TopicAdminRetryPolicyOption>()) {
     options.set<pubsub_admin::TopicAdminRetryPolicyOption>(

google/cloud/pubsub/admin/internal/topic_admin_option_defaults.h

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

google/cloud/pubsub/admin/samples/subscription_admin_client_samples.cc

@@ -38,6 +38,13 @@ 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 SubscriptionAdminConnection.
+  // For example, to connect to "europe-central2-pubsub.googleapis.com":
+  auto client = google::cloud::pubsub_admin::SubscriptionAdminClient(
+      google::cloud::pubsub_admin::MakeSubscriptionAdminConnection(
+          "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>(

google/cloud/pubsub/admin/samples/topic_admin_client_samples.cc

@@ -38,6 +38,12 @@ 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 TopicAdminConnection.
+  // For example, to connect to "europe-central2-pubsub.googleapis.com":
+  auto client = google::cloud::pubsub_admin::TopicAdminClient(
+      google::cloud::pubsub_admin::MakeTopicAdminConnection("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>(

google/cloud/pubsub/admin/subscription_admin_connection.cc

@@ -126,13 +126,13 @@ SubscriptionAdminConnection::TestIamPermissions(
 }
 
 std::shared_ptr<SubscriptionAdminConnection> MakeSubscriptionAdminConnection(
-    Options options) {
+    std::string const& location, Options options) {
   internal::CheckExpectedOptions<CommonOptionList, GrpcOptionList,
                                  UnifiedCredentialsOptionList,
                                  SubscriptionAdminPolicyOptionList>(options,
                                                                     __func__);
   options = pubsub_admin_internal::SubscriptionAdminDefaultOptions(
-      std::move(options));
+      location, std::move(options));
   auto background = internal::MakeBackgroundThreadsFactory(options)();
   auto auth = internal::CreateAuthenticationStrategy(background->cq(), options);
   auto stub = pubsub_admin_internal::CreateDefaultSubscriptionAdminStub(
@@ -142,6 +142,11 @@ std::shared_ptr<SubscriptionAdminConnection> MakeSubscriptionAdminConnection(
           std::move(background), std::move(stub), std::move(options)));
 }
 
+std::shared_ptr<SubscriptionAdminConnection> MakeSubscriptionAdminConnection(
+    Options options) {
+  return MakeSubscriptionAdminConnection(std::string{}, std::move(options));
+}
+
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace pubsub_admin
 }  // namespace cloud

google/cloud/pubsub/admin/subscription_admin_connection.h

@@ -29,6 +29,7 @@
 #include "google/cloud/version.h"
 #include <google/pubsub/v1/pubsub.pb.h>
 #include <memory>
+#include <string>
 
 namespace google {
 namespace cloud {
@@ -249,9 +250,20 @@ class SubscriptionAdminConnection {
  * @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 `SubscriptionAdminConnection` created
  * by this function.
  */
+std::shared_ptr<SubscriptionAdminConnection> MakeSubscriptionAdminConnection(
+    std::string const& location, Options options = {});
+
+/**
+ * A factory function to construct an object of type
+ * `SubscriptionAdminConnection`.
+ *
+ * This overload of `MakeSubscriptionAdminConnection` does not require a
+ * location argument, creating a connection to the global service endpoint.
+ */
 std::shared_ptr<SubscriptionAdminConnection> MakeSubscriptionAdminConnection(
     Options options = {});
 

google/cloud/pubsub/admin/topic_admin_connection.cc

@@ -102,11 +102,12 @@ TopicAdminConnection::TestIamPermissions(
 }
 
 std::shared_ptr<TopicAdminConnection> MakeTopicAdminConnection(
-    Options options) {
+    std::string const& location, Options options) {
   internal::CheckExpectedOptions<CommonOptionList, GrpcOptionList,
                                  UnifiedCredentialsOptionList,
                                  TopicAdminPolicyOptionList>(options, __func__);
-  options = pubsub_admin_internal::TopicAdminDefaultOptions(std::move(options));
+  options = pubsub_admin_internal::TopicAdminDefaultOptions(location,
+                                                            std::move(options));
   auto background = internal::MakeBackgroundThreadsFactory(options)();
   auto auth = internal::CreateAuthenticationStrategy(background->cq(), options);
   auto stub = pubsub_admin_internal::CreateDefaultTopicAdminStub(
@@ -116,6 +117,11 @@ std::shared_ptr<TopicAdminConnection> MakeTopicAdminConnection(
           std::move(background), std::move(stub), std::move(options)));
 }
 
+std::shared_ptr<TopicAdminConnection> MakeTopicAdminConnection(
+    Options options) {
+  return MakeTopicAdminConnection(std::string{}, std::move(options));
+}
+
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace pubsub_admin
 }  // namespace cloud