feat: add FieldInfo.referenced_types for generics (#247)

Source-Link: googleapis/synthtool@373d00f
Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:2dc6f67639bee669c33c6277a624ab9857d363e2fd33ac5b02d417b7d25f1ffc

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

.github/.OwlBot.lock.yaml

@@ -13,5 +13,5 @@
 # limitations under the License.
 docker:
   image: gcr.io/cloud-devrel-public-resources/owlbot-python:latest
-  digest: sha256:52210e0e0559f5ea8c52be148b33504022e1faef4e95fbe4b32d68022af2fa7e
-# created: 2024-07-08T19:25:35.862283192Z
+  digest: sha256:2dc6f67639bee669c33c6277a624ab9857d363e2fd33ac5b02d417b7d25f1ffc
+# created: 2024-08-15T17:41:26.438340772Z

.kokoro/docker/docs/Dockerfile

@@ -72,19 +72,18 @@ RUN tar -xvf Python-3.10.14.tgz
 RUN ./Python-3.10.14/configure --enable-optimizations
 RUN make altinstall
 
-RUN python3.10 -m venv /venv
-ENV PATH /venv/bin:$PATH
+ENV PATH /usr/local/bin/python3.10:$PATH
 
 ###################### Install pip
 RUN wget -O /tmp/get-pip.py 'https://bootstrap.pypa.io/get-pip.py' \
-  && python3 /tmp/get-pip.py \
+  && python3.10 /tmp/get-pip.py \
   && rm /tmp/get-pip.py
 
 # Test pip
-RUN python3 -m pip
+RUN python3.10 -m pip
 
 # Install build requirements
 COPY requirements.txt /requirements.txt
-RUN python3 -m pip install --require-hashes -r requirements.txt
+RUN python3.10 -m pip install --require-hashes -r requirements.txt
 
 CMD ["python3.10"]

google/api/client.proto

@@ -349,6 +349,13 @@ message MethodSettings {
 
   // The fully qualified name of the method, for which the options below apply.
   // This is used to find the method to apply the options.
+  //
+  // Example:
+  //
+  //    publishing:
+  //      method_settings:
+  //      - selector: google.storage.control.v2.StorageControl.CreateFolder
+  //        # method settings for CreateFolder...
   string selector = 1;
 
   // Describes settings to use for long-running operations when generating
@@ -357,17 +364,14 @@ message MethodSettings {
   //
   // Example of a YAML configuration::
   //
-  //  publishing:
-  //    method_settings:
+  //    publishing:
+  //      method_settings:
   //      - selector: google.cloud.speech.v2.Speech.BatchRecognize
   //        long_running:
-  //          initial_poll_delay:
-  //            seconds: 60 # 1 minute
+  //          initial_poll_delay: 60s # 1 minute
   //          poll_delay_multiplier: 1.5
-  //          max_poll_delay:
-  //            seconds: 360 # 6 minutes
-  //          total_poll_timeout:
-  //             seconds: 54000 # 90 minutes
+  //          max_poll_delay: 360s # 6 minutes
+  //          total_poll_timeout: 54000s # 90 minutes
   LongRunning long_running = 2;
 
   // List of top-level fields of the request message, that should be
@@ -376,8 +380,8 @@ message MethodSettings {
   //
   // Example of a YAML configuration:
   //
-  //  publishing:
-  //    method_settings:
+  //    publishing:
+  //      method_settings:
   //      - selector: google.example.v1.ExampleService.CreateExample
   //        auto_populated_fields:
   //        - request_id

google/api/context.proto

@@ -74,10 +74,12 @@ message ContextRule {
   // details.
   string selector = 1;
 
-  // A list of full type names of requested contexts.
+  // A list of full type names of requested contexts, only the requested context
+  // will be made available to the backend.
   repeated string requested = 2;
 
-  // A list of full type names of provided contexts.
+  // A list of full type names of provided contexts. It is used to support
+  // propagating HTTP headers and ETags from the response extension.
   repeated string provided = 3;
 
   // A list of full type names or extension IDs of extensions allowed in grpc

google/api/endpoint.proto

@@ -47,14 +47,10 @@ message Endpoint {
   // The canonical name of this endpoint.
   string name = 1;
 
-  // Unimplemented. Dot not use.
-  //
-  // DEPRECATED: This field is no longer supported. Instead of using aliases,
-  // please specify multiple [google.api.Endpoint][google.api.Endpoint] for each
-  // of the intended aliases.
-  //
-  // Additional names that this endpoint will be hosted on.
-  repeated string aliases = 2 [deprecated = true];
+  // Aliases for this endpoint, these will be served by the same UrlMap as the
+  // parent endpoint, and will be provisioned in the GCP stack for the Regional
+  // Endpoints.
+  repeated string aliases = 2;
 
   // The specification of an Internet routable address of API frontend that will
   // handle requests to this [API

google/api/endpoint_pb2.py

@@ -28,7 +28,7 @@
 
 
 DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
-    b'\n\x19google/api/endpoint.proto\x12\ngoogle.api"Q\n\x08\x45ndpoint\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x13\n\x07\x61liases\x18\x02 \x03(\tB\x02\x18\x01\x12\x0e\n\x06target\x18\x65 \x01(\t\x12\x12\n\nallow_cors\x18\x05 \x01(\x08\x42o\n\x0e\x63om.google.apiB\rEndpointProtoP\x01ZEgoogle.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig\xa2\x02\x04GAPIb\x06proto3'
+    b'\n\x19google/api/endpoint.proto\x12\ngoogle.api"M\n\x08\x45ndpoint\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x0f\n\x07\x61liases\x18\x02 \x03(\t\x12\x0e\n\x06target\x18\x65 \x01(\t\x12\x12\n\nallow_cors\x18\x05 \x01(\x08\x42o\n\x0e\x63om.google.apiB\rEndpointProtoP\x01ZEgoogle.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig\xa2\x02\x04GAPIb\x06proto3'
 )
 
 _globals = globals()
@@ -37,8 +37,6 @@
 if _descriptor._USE_C_DESCRIPTORS == False:
     DESCRIPTOR._options = None
     DESCRIPTOR._serialized_options = b"\n\016com.google.apiB\rEndpointProtoP\001ZEgoogle.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig\242\002\004GAPI"
-    _ENDPOINT.fields_by_name["aliases"]._options = None
-    _ENDPOINT.fields_by_name["aliases"]._serialized_options = b"\030\001"
     _globals["_ENDPOINT"]._serialized_start = 41
-    _globals["_ENDPOINT"]._serialized_end = 122
+    _globals["_ENDPOINT"]._serialized_end = 118
 # @@protoc_insertion_point(module_scope)

google/api/field_info.proto

@@ -29,12 +29,19 @@ extend google.protobuf.FieldOptions {
   //
   // Examples:
   //
-  //   string request_id = 1 [(google.api.field_info).format = UUID4];
-  //   string old_ip_address = 2 [(google.api.field_info).format = IPV4];
-  //   string new_ip_address = 3 [(google.api.field_info).format = IPV6];
-  //   string actual_ip_address = 4 [
-  //     (google.api.field_info).format = IPV4_OR_IPV6
-  //   ];
+  //     string request_id = 1 [(google.api.field_info).format = UUID4];
+  //     string old_ip_address = 2 [(google.api.field_info).format = IPV4];
+  //     string new_ip_address = 3 [(google.api.field_info).format = IPV6];
+  //     string actual_ip_address = 4 [
+  //       (google.api.field_info).format = IPV4_OR_IPV6
+  //     ];
+  //     google.protobuf.Any generic_field = 5 [
+  //       (google.api.field_info).referenced_types = {type_name: "ActualType"},
+  //       (google.api.field_info).referenced_types = {type_name: "OtherType"},
+  //     ];
+  //     google.protobuf.Any generic_user_input = 5 [
+  //       (google.api.field_info).referenced_types = {type_name: "*"},
+  //     ];
   google.api.FieldInfo field_info = 291403980;
 }
 
@@ -76,4 +83,24 @@ message FieldInfo {
   // any API consumer, just documents the API's format for the field it is
   // applied to.
   Format format = 1;
+
+  // The type(s) that the annotated, generic field may represent.
+  //
+  // Currently, this must only be used on fields of type `google.protobuf.Any`.
+  // Supporting other generic types may be considered in the future.
+  repeated TypeReference referenced_types = 2;
+}
+
+// A reference to a message type, for use in [FieldInfo][google.api.FieldInfo].
+message TypeReference {
+  // The name of the type that the annotated, generic field may represent.
+  // If the type is in the same protobuf package, the value can be the simple
+  // message name e.g., `"MyMessage"`. Otherwise, the value must be the
+  // fully-qualified message name e.g., `"google.library.v1.Book"`.
+  //
+  // If the type(s) are unknown to the service (e.g. the field accepts generic
+  // user input), use the wildcard `"*"` to denote this behavior.
+  //
+  // See [AIP-202](https://google.aip.dev/202#type-references) for more details.
+  string type_name = 1;
 }

google/api/field_info_pb2.py

@@ -31,7 +31,7 @@
 
 
 DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
-    b'\n\x1bgoogle/api/field_info.proto\x12\ngoogle.api\x1a google/protobuf/descriptor.proto"\x8c\x01\n\tFieldInfo\x12,\n\x06\x66ormat\x18\x01 \x01(\x0e\x32\x1c.google.api.FieldInfo.Format"Q\n\x06\x46ormat\x12\x16\n\x12\x46ORMAT_UNSPECIFIED\x10\x00\x12\t\n\x05UUID4\x10\x01\x12\x08\n\x04IPV4\x10\x02\x12\x08\n\x04IPV6\x10\x03\x12\x10\n\x0cIPV4_OR_IPV6\x10\x04:L\n\nfield_info\x12\x1d.google.protobuf.FieldOptions\x18\xcc\xf1\xf9\x8a\x01 \x01(\x0b\x32\x15.google.api.FieldInfoBl\n\x0e\x63om.google.apiB\x0e\x46ieldInfoProtoP\x01ZAgoogle.golang.org/genproto/googleapis/api/annotations;annotations\xa2\x02\x04GAPIb\x06proto3'
+    b'\n\x1bgoogle/api/field_info.proto\x12\ngoogle.api\x1a google/protobuf/descriptor.proto"\xc1\x01\n\tFieldInfo\x12,\n\x06\x66ormat\x18\x01 \x01(\x0e\x32\x1c.google.api.FieldInfo.Format\x12\x33\n\x10referenced_types\x18\x02 \x03(\x0b\x32\x19.google.api.TypeReference"Q\n\x06\x46ormat\x12\x16\n\x12\x46ORMAT_UNSPECIFIED\x10\x00\x12\t\n\x05UUID4\x10\x01\x12\x08\n\x04IPV4\x10\x02\x12\x08\n\x04IPV6\x10\x03\x12\x10\n\x0cIPV4_OR_IPV6\x10\x04""\n\rTypeReference\x12\x11\n\ttype_name\x18\x01 \x01(\t:L\n\nfield_info\x12\x1d.google.protobuf.FieldOptions\x18\xcc\xf1\xf9\x8a\x01 \x01(\x0b\x32\x15.google.api.FieldInfoBl\n\x0e\x63om.google.apiB\x0e\x46ieldInfoProtoP\x01ZAgoogle.golang.org/genproto/googleapis/api/annotations;annotations\xa2\x02\x04GAPIb\x06proto3'
 )
 
 _globals = globals()
@@ -43,7 +43,9 @@
     DESCRIPTOR._options = None
     DESCRIPTOR._serialized_options = b"\n\016com.google.apiB\016FieldInfoProtoP\001ZAgoogle.golang.org/genproto/googleapis/api/annotations;annotations\242\002\004GAPI"
     _globals["_FIELDINFO"]._serialized_start = 78
-    _globals["_FIELDINFO"]._serialized_end = 218
-    _globals["_FIELDINFO_FORMAT"]._serialized_start = 137
-    _globals["_FIELDINFO_FORMAT"]._serialized_end = 218
+    _globals["_FIELDINFO"]._serialized_end = 271
+    _globals["_FIELDINFO_FORMAT"]._serialized_start = 190
+    _globals["_FIELDINFO_FORMAT"]._serialized_end = 271
+    _globals["_TYPEREFERENCE"]._serialized_start = 273
+    _globals["_TYPEREFERENCE"]._serialized_end = 307
 # @@protoc_insertion_point(module_scope)

google/api/http.proto

@@ -41,7 +41,7 @@ message Http {
   bool fully_decode_reserved_expansion = 2;
 }
 
-// # gRPC Transcoding
+// gRPC Transcoding
 //
 // gRPC Transcoding is a feature for mapping between a gRPC method and one or
 // more HTTP REST endpoints. It allows developers to build a single API service
@@ -82,9 +82,8 @@ message Http {
 //
 // This enables an HTTP REST to gRPC mapping as below:
 //
-// HTTP | gRPC
-// -----|-----
-// `GET /v1/messages/123456`  | `GetMessage(name: "messages/123456")`
+// - HTTP: `GET /v1/messages/123456`
+// - gRPC: `GetMessage(name: "messages/123456")`
 //
 // Any fields in the request message which are not bound by the path template
 // automatically become HTTP query parameters if there is no HTTP request body.
@@ -108,11 +107,9 @@ message Http {
 //
 // This enables a HTTP JSON to RPC mapping as below:
 //
-// HTTP | gRPC
-// -----|-----
-// `GET /v1/messages/123456?revision=2&sub.subfield=foo` |
-// `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:
-// "foo"))`
+// - HTTP: `GET /v1/messages/123456?revision=2&sub.subfield=foo`
+// - gRPC: `GetMessage(message_id: "123456" revision: 2 sub:
+// SubMessage(subfield: "foo"))`
 //
 // Note that fields which are mapped to URL query parameters must have a
 // primitive type or a repeated primitive type or a non-repeated message type.
@@ -142,10 +139,8 @@ message Http {
 // representation of the JSON in the request body is determined by
 // protos JSON encoding:
 //
-// HTTP | gRPC
-// -----|-----
-// `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:
-// "123456" message { text: "Hi!" })`
+// - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }`
+// - gRPC: `UpdateMessage(message_id: "123456" message { text: "Hi!" })`
 //
 // The special name `*` can be used in the body mapping to define that
 // every field not bound by the path template should be mapped to the
@@ -168,10 +163,8 @@ message Http {
 //
 // The following HTTP JSON to RPC mapping is enabled:
 //
-// HTTP | gRPC
-// -----|-----
-// `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:
-// "123456" text: "Hi!")`
+// - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }`
+// - gRPC: `UpdateMessage(message_id: "123456" text: "Hi!")`
 //
 // Note that when using `*` in the body mapping, it is not possible to
 // have HTTP parameters, as all fields not bound by the path end in
@@ -199,13 +192,13 @@ message Http {
 //
 // This enables the following two alternative HTTP JSON to RPC mappings:
 //
-// HTTP | gRPC
-// -----|-----
-// `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`
-// `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:
-// "123456")`
+// - HTTP: `GET /v1/messages/123456`
+// - gRPC: `GetMessage(message_id: "123456")`
 //
-// ## Rules for HTTP mapping
+// - HTTP: `GET /v1/users/me/messages/123456`
+// - gRPC: `GetMessage(user_id: "me" message_id: "123456")`
+//
+// Rules for HTTP mapping
 //
 // 1. Leaf request fields (recursive expansion nested messages in the request
 //    message) are classified into three categories:
@@ -224,7 +217,7 @@ message Http {
 //  request body, all
 //     fields are passed via URL path and URL query parameters.
 //
-// ### Path template syntax
+// Path template syntax
 //
 //     Template = "/" Segments [ Verb ] ;
 //     Segments = Segment { "/" Segment } ;
@@ -263,7 +256,7 @@ message Http {
 // Document](https://developers.google.com/discovery/v1/reference/apis) as
 // `{+var}`.
 //
-// ## Using gRPC API Service Configuration
+// Using gRPC API Service Configuration
 //
 // gRPC API Service Configuration (service config) is a configuration language
 // for configuring a gRPC service to become a user-facing product. The
@@ -278,15 +271,14 @@ message Http {
 // specified in the service config will override any matching transcoding
 // configuration in the proto.
 //
-// Example:
+// The following example selects a gRPC method and applies an `HttpRule` to it:
 //
 //     http:
 //       rules:
-//         # Selects a gRPC method and applies HttpRule to it.
 //         - selector: example.v1.Messaging.GetMessage
 //           get: /v1/messages/{message_id}/{sub.subfield}
 //
-// ## Special notes
+// Special notes
 //
 // When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the
 // proto to JSON conversion must follow the [proto3

google/api/resource.proto

@@ -179,8 +179,13 @@ message ResourceDescriptor {
 
   // The plural name used in the resource name and permission names, such as
   // 'projects' for the resource name of 'projects/{project}' and the permission
-  // name of 'cloudresourcemanager.googleapis.com/projects.get'. It is the same
-  // concept of the `plural` field in k8s CRD spec
+  // name of 'cloudresourcemanager.googleapis.com/projects.get'. One exception
+  // to this is for Nested Collections that have stuttering names, as defined
+  // in [AIP-122](https://google.aip.dev/122#nested-collections), where the
+  // collection ID in the resource name pattern does not necessarily directly
+  // match the `plural` value.
+  //
+  // It is the same concept of the `plural` field in k8s CRD spec
   // https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
   //
   // Note: The plural form is required even for singleton resources. See