async-grpc-xds 0.0.1

data/proto/xds/annotations/v3/migrate.proto

@@ -0,0 +1,46 @@
+syntax = "proto3";
+
+package xds.annotations.v3;
+
+import "google/protobuf/descriptor.proto";
+
+option go_package = "github.com/cncf/xds/go/xds/annotations/v3";
+
+// Magic number in this file derived from top 28bit of SHA256 digest of
+// "xds.annotation.v3.migrate".
+extend google.protobuf.MessageOptions {
+  MigrateAnnotation message_migrate = 112948430;
+}
+extend google.protobuf.FieldOptions {
+  FieldMigrateAnnotation field_migrate = 112948430;
+}
+extend google.protobuf.EnumOptions {
+  MigrateAnnotation enum_migrate = 112948430;
+}
+extend google.protobuf.EnumValueOptions {
+  MigrateAnnotation enum_value_migrate = 112948430;
+}
+extend google.protobuf.FileOptions {
+  FileMigrateAnnotation file_migrate = 112948430;
+}
+
+message MigrateAnnotation {
+  // Rename the message/enum/enum value in next version.
+  string rename = 1;
+}
+
+message FieldMigrateAnnotation {
+  // Rename the field in next version.
+  string rename = 1;
+
+  // Add the field to a named oneof in next version. If this already exists, the
+  // field will join its siblings under the oneof, otherwise a new oneof will be
+  // created with the given name.
+  string oneof_promotion = 2;
+}
+
+message FileMigrateAnnotation {
+  // Move all types in the file to another package, this implies changing proto
+  // file path.
+  string move_to_package = 2;
+}

data/proto/xds/annotations/v3/security.proto

@@ -0,0 +1,30 @@
+syntax = "proto3";
+
+package xds.annotations.v3;
+
+import "xds/annotations/v3/status.proto";
+
+import "google/protobuf/descriptor.proto";
+
+option go_package = "github.com/cncf/xds/go/xds/annotations/v3";
+
+// All annotations in this file are experimental and subject to change. Their
+// only consumer today is the Envoy APIs and SecuritAnnotationValidator protoc
+// plugin in this repository.
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+extend google.protobuf.FieldOptions {
+  // Magic number is the 28 most significant bits in the sha256sum of
+  // "xds.annotations.v3.security".
+  FieldSecurityAnnotation security = 99044135;
+}
+
+// These annotations indicate metadata for the purpose of understanding the
+// security significance of fields.
+message FieldSecurityAnnotation {
+  // Field should be set in the presence of untrusted downstreams.
+  bool configure_for_untrusted_downstream = 1;
+
+  // Field should be set in the presence of untrusted upstreams.
+  bool configure_for_untrusted_upstream = 2;
+}

data/proto/xds/annotations/v3/sensitive.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package xds.annotations.v3;
+
+import "google/protobuf/descriptor.proto";
+
+option go_package = "github.com/cncf/xds/go/xds/annotations/v3";
+
+extend google.protobuf.FieldOptions {
+  // Magic number is the 28 most significant bits in the sha256sum of "xds.annotations.v3.sensitive".
+  // When set to true, `sensitive` indicates that this field contains sensitive data, such as
+  // personally identifiable information, passwords, or private keys, and should be redacted for
+  // display by tools aware of this annotation. Note that that this has no effect on standard
+  // Protobuf functions such as `TextFormat::PrintToString`.
+  bool sensitive = 61008053;
+}

data/proto/xds/annotations/v3/status.proto

@@ -0,0 +1,59 @@
+syntax = "proto3";
+
+package xds.annotations.v3;
+
+import "google/protobuf/descriptor.proto";
+
+option go_package = "github.com/cncf/xds/go/xds/annotations/v3";
+
+// Magic number in this file derived from top 28bit of SHA256 digest of
+// "xds.annotations.v3.status".
+extend google.protobuf.FileOptions {
+  FileStatusAnnotation file_status = 226829418;
+}
+
+extend google.protobuf.MessageOptions {
+  MessageStatusAnnotation message_status = 226829418;
+}
+
+extend google.protobuf.FieldOptions {
+  FieldStatusAnnotation field_status = 226829418;
+}
+
+message FileStatusAnnotation {
+  // The entity is work-in-progress and subject to breaking changes.
+  bool work_in_progress = 1;
+}
+
+message MessageStatusAnnotation {
+  // The entity is work-in-progress and subject to breaking changes.
+  bool work_in_progress = 1;
+}
+
+message FieldStatusAnnotation {
+  // The entity is work-in-progress and subject to breaking changes.
+  bool work_in_progress = 1;
+}
+
+enum PackageVersionStatus {
+  // Unknown package version status.
+  UNKNOWN = 0;
+
+  // This version of the package is frozen.
+  FROZEN = 1;
+
+  // This version of the package is the active development version.
+  ACTIVE = 2;
+
+  // This version of the package is the candidate for the next major version. It
+  // is typically machine generated from the active development version.
+  NEXT_MAJOR_VERSION_CANDIDATE = 3;
+}
+
+message StatusAnnotation {
+  // The entity is work-in-progress and subject to breaking changes.
+  bool work_in_progress = 1;
+
+  // The entity belongs to a package with the given version status.
+  PackageVersionStatus package_version_status = 2;
+}

data/proto/xds/annotations/v3/versioning.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+package xds.annotations.v3;
+
+import "google/protobuf/descriptor.proto";
+
+option go_package = "github.com/cncf/xds/go/xds/annotations/v3";
+
+extend google.protobuf.MessageOptions {
+  // Magic number is the 28 most significant bits in the sha256sum of
+  // "xds.annotations.v3.versioning".
+  VersioningAnnotation versioning = 92389011;
+}
+
+message VersioningAnnotation {
+  // Track the previous message type. E.g. this message might be
+  // xds.foo.v3alpha.Foo and it was previously xds.bar.v2.Bar. This
+  // information is consumed by UDPA via proto descriptors.
+  string previous_message_type = 1;
+}

data/proto/xds/core/v3/authority.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package xds.core.v3;
+
+import "xds/annotations/v3/status.proto";
+
+import "validate/validate.proto";
+
+option java_outer_classname = "AuthorityProto";
+option java_multiple_files = true;
+option java_package = "com.github.xds.core.v3";
+option go_package = "github.com/cncf/xds/go/xds/core/v3";
+
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// xDS authority information.
+message Authority {
+  string name = 1 [(validate.rules).string = {min_len: 1}];
+
+  // .. space reserved for additional authority addressing information, e.g. for
+  // resource signing, items such as CA trust chain, cert pinning may be added.
+}

data/proto/xds/core/v3/cidr.proto

@@ -0,0 +1,25 @@
+syntax = "proto3";
+
+package xds.core.v3;
+
+import "xds/annotations/v3/status.proto";
+import "google/protobuf/wrappers.proto";
+
+import "validate/validate.proto";
+
+option java_outer_classname = "CidrRangeProto";
+option java_multiple_files = true;
+option java_package = "com.github.xds.core.v3";
+option go_package = "github.com/cncf/xds/go/xds/core/v3";
+
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// CidrRange specifies an IP Address and a prefix length to construct
+// the subnet mask for a `CIDR <https://tools.ietf.org/html/rfc4632>`_ range.
+message CidrRange {
+  // IPv4 or IPv6 address, e.g. ``192.0.0.0`` or ``2001:db8::``.
+  string address_prefix = 1 [(validate.rules).string = {min_len: 1}];
+
+  // Length of prefix, e.g. 0, 32. Defaults to 0 when unset.
+  google.protobuf.UInt32Value prefix_len = 2 [(validate.rules).uint32 = {lte: 128}];
+}

data/proto/xds/core/v3/collection_entry.proto

@@ -0,0 +1,55 @@
+syntax = "proto3";
+
+package xds.core.v3;
+
+import "google/protobuf/any.proto";
+
+import "xds/annotations/v3/status.proto";
+import "xds/core/v3/resource_locator.proto";
+
+import "validate/validate.proto";
+
+option java_outer_classname = "CollectionEntryProto";
+option java_multiple_files = true;
+option java_package = "com.github.xds.core.v3";
+option go_package = "github.com/cncf/xds/go/xds/core/v3";
+
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// xDS collection resource wrapper. This encapsulates a xDS resource when
+// appearing inside a list collection resource. List collection resources are
+// regular Resource messages of type:
+//
+// .. code-block:: proto
+//
+//   message <T>Collection {
+//     repeated CollectionEntry resources = 1;
+//   }
+//
+message CollectionEntry {
+  // Inlined resource entry.
+  message InlineEntry {
+    // Optional name to describe the inlined resource. Resource names must match
+    // ``[a-zA-Z0-9_-\./]+`` (TODO(htuch): turn this into a PGV constraint once
+    // finalized, probably should be a RFC3986 pchar). This name allows
+    // reference via the #entry directive in ResourceLocator.
+    string name = 1 [(validate.rules).string.pattern = "^[0-9a-zA-Z_\\-\\.~:]+$"];
+
+    // The resource's logical version. It is illegal to have the same named xDS
+    // resource name at a given version with different resource payloads.
+    string version = 2;
+
+    // The resource payload, including type URL.
+    google.protobuf.Any resource = 3;
+  }
+
+  oneof resource_specifier {
+    option (validate.required) = true;
+
+    // A resource locator describing how the member resource is to be located.
+    ResourceLocator locator = 1;
+
+    // The resource is inlined in the list collection.
+    InlineEntry inline_entry = 2;
+  }
+}

data/proto/xds/core/v3/context_params.proto

@@ -0,0 +1,23 @@
+syntax = "proto3";
+
+package xds.core.v3;
+
+import "xds/annotations/v3/status.proto";
+
+option java_outer_classname = "ContextParamsProto";
+option java_multiple_files = true;
+option java_package = "com.github.xds.core.v3";
+option go_package = "github.com/cncf/xds/go/xds/core/v3";
+
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// Additional parameters that can be used to select resource variants. These include any
+// global context parameters, per-resource type client feature capabilities and per-resource
+// type functional attributes. All per-resource type attributes will be `xds.resource.`
+// prefixed and some of these are documented below:
+//
+// `xds.resource.listening_address`: The value is "IP:port" (e.g. "10.1.1.3:8080") which is
+//   the listening address of a Listener. Used in a Listener resource query.
+message ContextParams {
+    map<string, string> params = 1;
+}

data/proto/xds/core/v3/extension.proto

@@ -0,0 +1,26 @@
+syntax = "proto3";
+
+package xds.core.v3;
+
+option java_outer_classname = "ExtensionProto";
+option java_multiple_files = true;
+option java_package = "com.github.xds.core.v3";
+option go_package = "github.com/cncf/xds/go/xds/core/v3";
+
+import "validate/validate.proto";
+import "google/protobuf/any.proto";
+
+// Message type for extension configuration.
+message TypedExtensionConfig {
+  // The name of an extension. This is not used to select the extension, instead
+  // it serves the role of an opaque identifier.
+  string name = 1 [(validate.rules).string = {min_len: 1}];
+
+  // The typed config for the extension. The type URL will be used to identify
+  // the extension. In the case that the type URL is *xds.type.v3.TypedStruct*
+  // (or, for historical reasons, *udpa.type.v1.TypedStruct*), the inner type
+  // URL of *TypedStruct* will be utilized. See the
+  // :ref:`extension configuration overview
+  // <config_overview_extension_configuration>` for further details.
+  google.protobuf.Any typed_config = 2 [(validate.rules).any = {required: true}];
+}

data/proto/xds/core/v3/resource.proto

@@ -0,0 +1,29 @@
+syntax = "proto3";
+
+package xds.core.v3;
+
+import "google/protobuf/any.proto";
+
+import "xds/annotations/v3/status.proto";
+import "xds/core/v3/resource_name.proto";
+
+option java_outer_classname = "ResourceProto";
+option java_multiple_files = true;
+option java_package = "com.github.xds.core.v3";
+option go_package = "github.com/cncf/xds/go/xds/core/v3";
+
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// xDS resource wrapper. This encapsulates a xDS resource when appearing in an
+// xDS transport discovery response or when accessed as a filesystem object.
+message Resource {
+  // Resource name. This may be omitted for filesystem resources.
+  ResourceName name = 1;
+
+  // The resource's logical version. It is illegal to have the same named xDS
+  // resource name at a given version with different resource payloads.
+  string version = 2;
+
+  // The resource payload, including type URL.
+  google.protobuf.Any resource = 3;
+}

data/proto/xds/core/v3/resource_locator.proto

@@ -0,0 +1,118 @@
+syntax = "proto3";
+
+package xds.core.v3;
+
+import "xds/annotations/v3/status.proto";
+import "xds/core/v3/context_params.proto";
+
+import "validate/validate.proto";
+
+option java_outer_classname = "ResourceLocatorProto";
+option java_multiple_files = true;
+option java_package = "com.github.xds.core.v3";
+option go_package = "github.com/cncf/xds/go/xds/core/v3";
+
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// xDS resource locators identify a xDS resource name and instruct the
+// data-plane load balancer on how the resource may be located.
+//
+// Resource locators have a canonical xdstp:// URI representation:
+//
+//   xdstp://{authority}/{type_url}/{id}?{context_params}{#directive,*}
+//
+// where context_params take the form of URI query parameters.
+//
+// Resource locators have a similar canonical http:// URI representation:
+//
+//   http://{authority}/{type_url}/{id}?{context_params}{#directive,*}
+//
+// Resource locators also have a simplified file:// URI representation:
+//
+//   file:///{id}{#directive,*}
+//
+message ResourceLocator {
+  enum Scheme {
+    XDSTP = 0;
+    HTTP = 1;
+    FILE = 2;
+  }
+
+  // URI scheme.
+  Scheme scheme = 1 [(validate.rules).enum = {defined_only: true}];
+
+  // Opaque identifier for the resource. Any '/' will not be escaped during URI
+  // encoding and will form part of the URI path. This may end
+  // with ‘*’ for glob collection references.
+  string id = 2;
+
+  // Logical authority for resource (not necessarily transport network address).
+  // Authorities are opaque in the xDS API, data-plane load balancers will map
+  // them to concrete network transports such as an xDS management server, e.g.
+  // via envoy.config.core.v3.ConfigSource.
+  string authority = 3;
+
+  // Fully qualified resource type (as in type URL without types.googleapis.com/
+  // prefix).
+  string resource_type = 4 [(validate.rules).string = {min_len: 1}];
+
+  oneof context_param_specifier {
+    // Additional parameters that can be used to select resource variants.
+    // Matches must be exact, i.e. all context parameters must match exactly and
+    // there must be no additional context parameters set on the matched
+    // resource.
+    ContextParams exact_context = 5;
+
+    // .. space reserved for future potential matchers, e.g. CEL expressions.
+  }
+
+  // Directives provide information to data-plane load balancers on how xDS
+  // resource names are to be interpreted and potentially further resolved. For
+  // example, they may provide alternative resource locators for when primary
+  // resolution fails. Directives are not part of resource names and do not
+  // appear in a xDS transport discovery request.
+  //
+  // When encoding to URIs, directives take the form:
+  //
+  // <directive name>=<string representation of directive value>
+  //
+  // For example, we can have alt=xdstp://foo/bar or entry=some%20thing. Each
+  // directive value type may have its own string encoding, in the case of
+  // ResourceLocator there is a recursive URI encoding.
+  //
+  // Percent encoding applies to the URI encoding of the directive value.
+  // Multiple directives are comma-separated, so the reserved characters that
+  // require percent encoding in a directive value are [',', '#', '[', ']',
+  // '%']. These are the RFC3986 fragment reserved characters with the addition
+  // of the xDS scheme specific ','. See
+  // https://tools.ietf.org/html/rfc3986#page-49 for further details on URI ABNF
+  // and reserved characters.
+  message Directive {
+    oneof directive {
+      option (validate.required) = true;
+
+      // An alternative resource locator for fallback if the resource is
+      // unavailable. For example, take the resource locator:
+      //
+      //   xdstp://foo/some-type/some-route-table#alt=xdstp://bar/some-type/another-route-table
+      //
+      // If the data-plane load balancer is unable to reach `foo` to fetch the
+      // resource, it will fallback to `bar`. Alternative resources do not need
+      // to have equivalent content, but they should be functional substitutes.
+      ResourceLocator alt = 1;
+
+      // List collections support inlining of resources via the entry field in
+      // Resource. These inlined Resource objects may have an optional name
+      // field specified. When specified, the entry directive allows
+      // ResourceLocator to directly reference these inlined resources, e.g.
+      // xdstp://.../foo#entry=bar.
+      string entry = 2 [(validate.rules).string = {min_len: 1, pattern: "^[0-9a-zA-Z_\\-\\./~:]+$"}];
+    }
+  }
+
+  // A list of directives that appear in the xDS resource locator #fragment.
+  //
+  // When encoding to URI form, directives are percent encoded with comma
+  // separation.
+  repeated Directive directives = 6;
+}

data/proto/xds/core/v3/resource_name.proto

@@ -0,0 +1,42 @@
+syntax = "proto3";
+
+package xds.core.v3;
+
+import "xds/annotations/v3/status.proto";
+import "xds/core/v3/context_params.proto";
+
+import "validate/validate.proto";
+
+option java_outer_classname = "ResourceNameProto";
+option java_multiple_files = true;
+option java_package = "com.github.xds.core.v3";
+option go_package = "github.com/cncf/xds/go/xds/core/v3";
+
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// xDS resource name. This has a canonical xdstp:// URI representation:
+//
+//   xdstp://{authority}/{type_url}/{id}?{context_params}
+//
+// where context_params take the form of URI query parameters.
+//
+// A xDS resource name fully identifies a network resource for transport
+// purposes. xDS resource names in this form appear only in discovery
+// request/response messages used with the xDS transport.
+message ResourceName {
+  // Opaque identifier for the resource. Any '/' will not be escaped during URI
+  // encoding and will form part of the URI path.
+  string id = 1;
+
+  // Logical authority for resource (not necessarily transport network address).
+  // Authorities are opaque in the xDS API, data-plane load balancers will map
+  // them to concrete network transports such as an xDS management server.
+  string authority = 2;
+
+  // Fully qualified resource type (as in type URL without types.googleapis.com/
+  // prefix).
+  string resource_type = 3 [(validate.rules).string = {min_len: 1}];
+
+  // Additional parameters that can be used to select resource variants.
+  ContextParams context = 4;
+}

data/proto/xds/type/matcher/v3/cel.proto

@@ -0,0 +1,37 @@
+syntax = "proto3";
+
+package xds.type.matcher.v3;
+
+import "xds/type/v3/cel.proto";
+import "validate/validate.proto";
+
+option java_package = "com.github.xds.type.matcher.v3";
+option java_outer_classname = "CelProto";
+option java_multiple_files = true;
+option go_package = "github.com/cncf/xds/go/xds/type/matcher/v3";
+
+// [#protodoc-title: Common Expression Language (CEL) matchers]
+
+// Performs a match by evaluating a `Common Expression Language
+// <https://github.com/google/cel-spec>`_ (CEL) expression against the standardized set of
+// :ref:`HTTP attributes <arch_overview_attributes>` specified via ``HttpAttributesCelMatchInput``.
+//
+// .. attention::
+//
+//   The match is ``true``, iff the result of the evaluation is a bool AND true.
+//   In all other cases, the match is ``false``, including but not limited to: non-bool types,
+//   ``false``, ``null``, ``int(1)``, etc.
+//   In case CEL expression raises an error, the result of the evaluation is interpreted "no match".
+//
+// Refer to :ref:`Unified Matcher API <envoy_v3_api_msg_.xds.type.matcher.v3.Matcher>` documentation
+// for usage details.
+//
+// [#comment: envoy.matching.matchers.cel_matcher]
+message CelMatcher {
+  // Either parsed or checked representation of the CEL program.
+  type.v3.CelExpression expr_match = 1 [(validate.rules).message = {required: true}];
+
+  // Free-form description of the CEL AST, e.g. the original expression text, to be
+  // used for debugging assistance.
+  string description = 2;
+}

data/proto/xds/type/matcher/v3/domain.proto

@@ -0,0 +1,46 @@
+syntax = "proto3";
+
+package xds.type.matcher.v3;
+
+import "xds/annotations/v3/status.proto";
+import "xds/type/matcher/v3/matcher.proto";
+
+import "validate/validate.proto";
+
+option java_package = "com.github.xds.type.matcher.v3";
+option java_outer_classname = "ServerNameMatcherProto";
+option java_multiple_files = true;
+option go_package = "github.com/cncf/xds/go/xds/type/matcher/v3";
+
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// [#protodoc-title: Server name matcher]
+
+// Matches a fully qualified server name against a set of domain
+// names with optional wildcards.
+message ServerNameMatcher {
+  // Specifies a set of exact and wildcard domains and a match action. The
+  // wildcard symbol ``*`` must appear at most once as the left-most part of
+  // the domain on a dot border. The wildcard matches one or more non-empty
+  // domain parts.
+  message DomainMatcher {
+    // A non-empty set of domain names with optional wildcards, e.g.
+    // ``www.example.com``, ``*.com``, or ``*``.
+    repeated string domains = 1 [ (validate.rules).repeated = {min_items : 1} ];
+
+    // Match action to apply when the server name matches any of the domain
+    // names in the matcher.
+    Matcher.OnMatch on_match = 2;
+  }
+
+  // Match a server name by multiple domain matchers. Each domain, exact or
+  // wildcard, must appear at most once across all the domain matchers.
+  //
+  // The server name will be matched against all wildcard domains starting from
+  // the longest suffix, i.e. ``www.example.com`` input will be first matched
+  // against ``www.example.com``, then ``*.example.com``, then ``*.com``, then
+  // ``*``, until the associated matcher action accepts the input. Note that
+  // wildcards must be on a dot border, and values like ``*w.example.com`` are
+  // invalid.
+  repeated DomainMatcher domain_matchers = 1;
+}

data/proto/xds/type/matcher/v3/http_inputs.proto

@@ -0,0 +1,23 @@
+syntax = "proto3";
+
+package xds.type.matcher.v3;
+
+option java_package = "com.github.xds.type.matcher.v3";
+option java_outer_classname = "HttpInputsProto";
+option java_multiple_files = true;
+option go_package = "github.com/cncf/xds/go/xds/type/matcher/v3";
+
+// [#protodoc-title: Common HTTP Inputs]
+
+// Specifies that matching should be performed on the set of :ref:`HTTP attributes
+// <arch_overview_attributes>`.
+//
+// The attributes will be exposed via `Common Expression Language
+// <https://github.com/google/cel-spec>`_ runtime to associated CEL matcher.
+//
+// Refer to :ref:`Unified Matcher API <envoy_v3_api_msg_.xds.type.matcher.v3.Matcher>` documentation
+// for usage details.
+//
+// [#comment: envoy.matching.inputs.cel_data_input]
+message HttpAttributesCelMatchInput {
+}