diff --git a/xds/third_party/udpa/import.sh b/xds/third_party/udpa/import.sh index 044df40d9c..b96e4ea6da 100755 --- a/xds/third_party/udpa/import.sh +++ b/xds/third_party/udpa/import.sh @@ -16,7 +16,7 @@ # Update VERSION then in this directory run ./import.sh set -e -BRANCH=master +BRANCH=main # import VERSION from one of the google internal CLs VERSION=5459f2c994033b0afed7e4a70ac7e90c90c1ffee GIT_REPO="https://github.com/cncf/udpa.git" @@ -32,6 +32,7 @@ udpa/annotations/status.proto udpa/annotations/versioning.proto udpa/data/orca/v1/orca_load_report.proto udpa/service/orca/v1/orca.proto +udpa/type/v1/typed_struct.proto xds/core/v3/authority.proto xds/core/v3/collection_entry.proto xds/core/v3/context_params.proto diff --git a/xds/third_party/udpa/src/main/proto/udpa/type/v1/typed_struct.proto b/xds/third_party/udpa/src/main/proto/udpa/type/v1/typed_struct.proto new file mode 100644 index 0000000000..e46a2cb575 --- /dev/null +++ b/xds/third_party/udpa/src/main/proto/udpa/type/v1/typed_struct.proto @@ -0,0 +1,42 @@ +syntax = "proto3"; + +package udpa.type.v1; + +option java_outer_classname = "TypedStructProto"; +option java_multiple_files = true; +option java_package = "com.github.udpa.udpa.type.v1"; + +import "validate/validate.proto"; +import "google/protobuf/struct.proto"; + +// A TypedStruct contains an arbitrary JSON serialized protocol buffer message with a URL that +// describes the type of the serialized message. This is very similar to google.protobuf.Any, +// instead of having protocol buffer binary, this employs google.protobuf.Struct as value. +// +// This message is intended to be embedded inside Any, so it shouldn't be directly referred +// from other UDPA messages. +// +// When packing an opaque extension config, packing the expected type into Any is preferred +// wherever possible for its efficiency. TypedStruct should be used only if a proto descriptor +// is not available, for example if: +// - A control plane sends opaque message that is originally from external source in human readable +// format such as JSON or YAML. +// - The control plane doesn't have the knowledge of the protocol buffer schema hence it cannot +// serialize the message in protocol buffer binary format. +// - The DPLB doesn't have have the knowledge of the protocol buffer schema its plugin or extension +// uses. This has to be indicated in the DPLB capability negotiation. +// +// When a DPLB receives a TypedStruct in Any, it should: +// - Check if the type_url of the TypedStruct matches the type the extension expects. +// - Convert value to the type described in type_url and perform validation. +// TODO(lizan): Figure out how TypeStruct should be used with DPLB extensions that doesn't link +// protobuf descriptor with DPLB itself, (e.g. gRPC LB Plugin, Envoy WASM extensions). +message TypedStruct { + // A URL that uniquely identifies the type of the serialize protocol buffer message. + // This has same semantics and format described in google.protobuf.Any: + // https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto + string type_url = 1; + + // A JSON representation of the above specified type. + google.protobuf.Struct value = 2; +}