feat(generator): support services with location-dependent endpoints (#…

…9625) Add generator support for services with location-dependent default endpoints. A new `MakeServiceConnection()` overload is generated with a required `location` parameter, which is used to build the default `EndpointOption` of `"<location>-<normal-service-endpoint>"` (for example, "us-documentai.googleapis.com" in the Cloud Document AI API). For backwards compatibility in already-released libraries, the old `MakeServiceConnection()` signature is still available, but it, as before, requires setting `EndpointOption` and `AuthorityOption` to get something that works. Fixes #7976 and #8704.
googleapis · Aug 3, 2022 · 7feb6df · 7feb6df
1 parent fe748ba
commit 7feb6df
Showing 306 changed files with 1,990 additions and 1,317 deletions.
diff --git a/ci/cloudbuild/builds/generate-libraries.sh b/ci/cloudbuild/builds/generate-libraries.sh
@@ -64,6 +64,9 @@ for dox in google/cloud/*/doc/main.dox; do
     variable=$(grep -om1 "${variable_re}" "${option_defaults_cc}")
     endpoint_re='"[^"]*?\.googleapis\.com"'
     endpoint=$(grep -Pom1 "${endpoint_re}" "${option_defaults_cc}")
+    if grep -q 'location,' "${option_defaults_cc}"; then
+      endpoint="\"<location>-${endpoint:1:-1}\""
+    fi
     make_connection_re='Make.*?Connection()'
     make_connection=$(grep -Pom1 "${make_connection_re}" "${connection_h}")
     env_vars+=("- \`${variable}=...\` overrides the")

diff --git a/generator/generator_config.proto b/generator/generator_config.proto
@@ -76,6 +76,22 @@ message ServiceConfiguration {
   // decorators, for example, Storage requires a round-robin decorator to get
   // good performance.
   bool omit_stub_factory = 14;
+
+  // Control the overloads generated for `Make*Connection()`.
+  enum EndpointLocationStyle {
+    // Default. `Make*Connection(Options options = {})`.
+    LOCATION_INDEPENDENT = 0;
+
+    // `Make*Connection(std::string const& location, Options options = {})`.
+    LOCATION_DEPENDENT = 1;
+
+    // Both of the above, for services that were initially released as
+    // "LOCATION_INDEPENDENT" (probably with a useless default endpoint),
+    // but were subsequently acknowledged to be "LOCATION_DEPENDENT".
+    // Do not use for new services.
+    LOCATION_DEPENDENT_COMPAT = 2;
+  }
+  EndpointLocationStyle endpoint_location_style = 15;
 }
 
 message GeneratorConfiguration {

diff --git a/generator/generator_config.textproto b/generator/generator_config.textproto
@@ -449,20 +449,23 @@ service {
   initial_copyright_year: "2022"
   service_endpoint_env_var: "GOOGLE_CLOUD_CPP_DIALOGFLOW_ENVIRONMENT_ENDPOINT"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/experiment.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/session_entity_type.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
@@ -472,27 +475,31 @@ service {
   initial_copyright_year: "2022"
   service_endpoint_env_var: "GOOGLE_CLOUD_CPP_DIALOGFLOW_VERSIONS_ENDPOINT"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/page.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/session.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/intent.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
@@ -501,13 +508,15 @@ service {
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/security_settings.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
@@ -516,48 +525,55 @@ service {
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/entity_type.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/transition_route_group.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/webhook.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/changelog.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/test_case.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/cx/v3/deployment.proto"
   product_path: "google/cloud/dialogflow_cx"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 # Dialogflow ES
@@ -566,6 +582,7 @@ service {
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
@@ -574,13 +591,15 @@ service {
   initial_copyright_year: "2022"
   service_endpoint_env_var: "GOOGLE_CLOUD_CPP_DIALOGFLOW_ENVIRONMENTS_ENDPOINT"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/session_entity_type.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
@@ -589,48 +608,55 @@ service {
   initial_copyright_year: "2022"
   service_endpoint_env_var: "GOOGLE_CLOUD_CPP_DIALOGFLOW_VERSIONS_ENDPOINT"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/context.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/conversation_profile.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/answer_record.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/participant.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/session.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/conversation_dataset.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
@@ -639,6 +665,7 @@ service {
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
@@ -647,27 +674,31 @@ service {
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/document.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/conversation_model.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/knowledge_base.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
@@ -676,13 +707,15 @@ service {
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 service {
   service_proto_path: "google/cloud/dialogflow/v2/conversation.proto"
   product_path: "google/cloud/dialogflow_es"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 
@@ -692,6 +725,7 @@ service {
   product_path: "google/cloud/documentai"
   initial_copyright_year: "2022"
   retryable_status_codes: ["kUnavailable"]
+  endpoint_location_style: LOCATION_DEPENDENT_COMPAT
 }
 
 # Eventarc

diff --git a/generator/integration_tests/golden/golden_kitchen_sink_connection.h b/generator/integration_tests/golden/golden_kitchen_sink_connection.h
@@ -101,20 +101,18 @@ class GoldenKitchenSinkConnection {
  * A factory function to construct an object of type `GoldenKitchenSinkConnection`.
  *
  * The returned connection object should not be used directly; instead it
- * should be passed as an argument to the constructor of GoldenKitchenSinkClient,
- * and that class used instead.
+ * should be passed as an argument to the constructor of GoldenKitchenSinkClient.
  *
- * The optional @p opts argument may be used to configure aspects of the
+ * The optional @p options argument may be used to configure aspects of the
  * returned `GoldenKitchenSinkConnection`. Expected options are any of the types in
  * the following option lists:
  *
  * - `google::cloud::CommonOptionList`
  * - `google::cloud::GrpcOptionList`
  * - `google::cloud::golden::GoldenKitchenSinkPolicyOptionList`
  *
- * @note Unrecognized options will be ignored. To debug issues with options set
- *     `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment and unexpected
- *     options will be logged.
+ * @note Unexpected options will be ignored. To log unexpected options instead,
+ *     set `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment.
  *
  * @param options (optional) Configure the `GoldenKitchenSinkConnection` created by
  * this function.

diff --git a/generator/integration_tests/golden/golden_thing_admin_connection.h b/generator/integration_tests/golden/golden_thing_admin_connection.h
@@ -130,20 +130,18 @@ class GoldenThingAdminConnection {
  * A factory function to construct an object of type `GoldenThingAdminConnection`.
  *
  * The returned connection object should not be used directly; instead it
- * should be passed as an argument to the constructor of GoldenThingAdminClient,
- * and that class used instead.
+ * should be passed as an argument to the constructor of GoldenThingAdminClient.
  *
- * The optional @p opts argument may be used to configure aspects of the
+ * The optional @p options argument may be used to configure aspects of the
  * returned `GoldenThingAdminConnection`. Expected options are any of the types in
  * the following option lists:
  *
  * - `google::cloud::CommonOptionList`
  * - `google::cloud::GrpcOptionList`
  * - `google::cloud::golden::GoldenThingAdminPolicyOptionList`
  *
- * @note Unrecognized options will be ignored. To debug issues with options set
- *     `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment and unexpected
- *     options will be logged.
+ * @note Unexpected options will be ignored. To log unexpected options instead,
+ *     set `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment.
  *
  * @param options (optional) Configure the `GoldenThingAdminConnection` created by
  * this function.

diff --git a/generator/internal/codegen_utils.cc b/generator/internal/codegen_utils.cc
@@ -123,6 +123,19 @@ void ProcessArgEmulatorEndpointEnvVar(
   }
 }
 
+void ProcessArgEndpointLocationStyle(
+    std::vector<std::pair<std::string, std::string>>& command_line_args) {
+  auto endpoint_location_style =
+      std::find_if(command_line_args.begin(), command_line_args.end(),
+                   [](std::pair<std::string, std::string> const& p) {
+                     return p.first == "endpoint_location_style";
+                   });
+  if (endpoint_location_style == command_line_args.end()) {
+    command_line_args.emplace_back("endpoint_location_style",
+                                   "LOCATION_INDEPENDENT");
+  }
+}
+
 void ProcessArgGenerateAsyncRpc(
     std::vector<std::pair<std::string, std::string>>& command_line_args) {
   ProcessRepeated("gen_async_rpc", "gen_async_rpcs", command_line_args);
@@ -230,6 +243,7 @@ ProcessCommandLineArgs(std::string const& parameters) {
   ProcessArgOmitRpc(command_line_args);
   ProcessArgServiceEndpointEnvVar(command_line_args);
   ProcessArgEmulatorEndpointEnvVar(command_line_args);
+  ProcessArgEndpointLocationStyle(command_line_args);
   ProcessArgGenerateAsyncRpc(command_line_args);
   ProcessArgRetryGrpcStatusCode(command_line_args);
   ProcessArgAdditionalProtoFiles(command_line_args);

diff --git a/generator/internal/codegen_utils_test.cc b/generator/internal/codegen_utils_test.cc
@@ -312,6 +312,15 @@ TEST(ProcessCommandLineArgs, ProcessOmitStubFactory) {
   EXPECT_THAT(*result, Contains(Pair("omit_stub_factory", "true")));
 }
 
+TEST(ProcessCommandLineArgs, ProcessEndpointLocationStyle) {
+  auto result = ProcessCommandLineArgs(
+      "product_path=google/cloud/spanner/"
+      ",endpoint_location_style=LOCATION_DEPENDENT_COMPAT");
+  ASSERT_THAT(result, IsOk());
+  EXPECT_THAT(*result, Contains(Pair("endpoint_location_style",
+                                     "LOCATION_DEPENDENT_COMPAT")));
+}
+
 }  // namespace
 }  // namespace generator_internal
 }  // namespace cloud