// Copyright 2025 CNCF xDS API Working Group (xDS-WG) Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
//     http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

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;
  }
}
