github.com/envoyproxy/go-control-plane v0.9.4: v2.Cluster

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify github.com/envoyproxy/go-control-plane/envoy/api/v2.Cluster in pkg:golang/github.com/envoyproxy/go-control-plane@v0.9.4
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/envoyproxy/go-control-plane@v0.9.4
Demonstrate these symbols/APIs:
  - github.com/envoyproxy/go-control-plane/envoy/api/v2.Cluster

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:7831a47a7f7fd880c65df449575993c17586bfba8aec8d0bbb4de4f8578295eb","contract":["v2.Cluster initializes and passes validation with logical DNS discovery and round-robin load balancing","v2.Cluster validation rejects invalid configuration with missing required fields","v2.Cluster serializes to and deserializes from protobuf wire format without data loss","ptypes.MarshalAny packs v2.Cluster with type URL matching type.googleapis.com/envoy.api.v2.Cluster","cache.ClusterType matches v2.Cluster type URL","cache.NewSnapshot successfully indexes v2.Cluster under cache.ClusterType and validates consistency"],"goal":"verify github.com/envoyproxy/go-control-plane/envoy/api/v2.Cluster in pkg:golang/github.com/envoyproxy/go-control-plane@v0.9.4","kind":"HOW","packages":["pkg:golang/github.com/envoyproxy/go-control-plane@v0.9.4"],"schemaVersion":1,"symbols":["github.com/envoyproxy/go-control-plane/envoy/api/v2.Cluster"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/envoyproxy/go-control-plane@v0.9.4"],"schemaVersion":1,"subject":"pkg:golang/github.com/envoyproxy/go-control-plane@v0.9.4","symbols":["github.com/envoyproxy/go-control-plane/envoy/api/v2.Cluster"],"verifierAdapter":"golang@1"}

module sample

go 1.25.0

require (
	github.com/envoyproxy/go-control-plane v0.9.4
	github.com/golang/protobuf v1.5.4
)

require (
	github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f // indirect
	github.com/envoyproxy/protoc-gen-validate v1.3.3 // indirect
	golang.org/x/net v0.55.0 // indirect
	golang.org/x/sys v0.45.0 // indirect
	golang.org/x/text v0.37.0 // indirect
	google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55 // indirect
	google.golang.org/grpc v1.34.0-dev // indirect
	google.golang.org/protobuf v1.36.11 // indirect
)

cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f h1:WBZRG4aNOuI15bLRrCgN8fCq8E5Xuty6jGbmSNEvSsU=
github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
github.com/envoyproxy/go-control-plane v0.9.4 h1:rEvIZUSZ3fx39WIi3JkQqQBitGwpELBIYWeBVh6wn+E=
github.com/envoyproxy/go-control-plane v0.9.4/go.mod h1:6rpuAdCZL397s3pYoYcLgu1mIlRU8Am5FuJP05cCM98=
github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c=
github.com/envoyproxy/protoc-gen-validate v1.3.3 h1:MVQghNeW+LZcmXe7SY1V36Z+WFMDjpqGAGacLe2T0ds=
github.com/envoyproxy/protoc-gen-validate v1.3.3/go.mod h1:TsndJ/ngyIdQRhMcVVGDDHINPLWB7C82oDArY51KfB0=
github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=
github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A=
github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
github.com/golang/protobuf v1.3.3/go.mod h1:vzj43D7+SQXF/4pzW/hwtAqwc6iTitCiVSaWz5lYuqw=
github.com/golang/protobuf v1.5.0 h1:LUVKkCeviFUMKqHa4tXIIij/lbhnMbP7Fn5wKdKkRh4=
github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY=
golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
golang.org/x/tools v0.0.0-20190524140312-2c0ae7006135/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55 h1:gSJIx1SDwno+2ElGhA4+qG2zF97qiUzTM+rQ0klBOcE=
google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55/go.mod h1:DMBHOl98Agz4BDEuKkezgsaosCRResVns1a3J2ZsMNc=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478 h1:RmoJA1ujG+/lRGNfUnOMfhCy5EipVMyvUE+KNbPbTlw=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
google.golang.org/grpc v1.19.0/go.mod h1:mqu4LbDTu4XGKhr4mRzUsmM4RtVoemTSY81AxZiDr8c=
google.golang.org/grpc v1.23.0/go.mod h1:Y5yQAOtifL1yxbo5wqy6BxZv8vAUGQwXBOALyacEbxg=
google.golang.org/grpc v1.25.1/go.mod h1:c3i+UQWmh7LiEpx4sFZnkU36qjEYZ0imhYfXVyQciAY=
google.golang.org/grpc v1.34.0-dev h1:OjzQmuvaz9ErXx7ZVEL3db/pbqD1QFA4GH1lxHMK1cY=
google.golang.org/grpc v1.34.0-dev/go.mod h1:fr5YgcSWrqhRRxogOsw7RzIpsmvOZ6IcH4kBYTpR3n0=
google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

{
  "schemaVersion": 1,
  "goal": "verify github.com/envoyproxy/go-control-plane/envoy/api/v2.Cluster in pkg:golang/github.com/envoyproxy/go-control-plane@v0.9.4",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/envoyproxy/go-control-plane@v0.9.4"
  ],
  "symbols": [
    "github.com/envoyproxy/go-control-plane/envoy/api/v2.Cluster"
  ]
}

package main

import (
	"fmt"
	"os"
	"time"

	v2 "github.com/envoyproxy/go-control-plane/envoy/api/v2"
	core "github.com/envoyproxy/go-control-plane/envoy/api/v2/core"
	"github.com/envoyproxy/go-control-plane/pkg/cache"
	"github.com/golang/protobuf/proto"
	"github.com/golang/protobuf/ptypes"
)

func main() {
	if err := runContract(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract verification failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("PASS: github.com/envoyproxy/go-control-plane/envoy/api/v2.Cluster contract verified")
}

func runContract() error {
	clusterName := "service_cluster_v2"
	timeout := 5 * time.Second

	// 1. Construct and populate Cluster
	cluster := &v2.Cluster{
		Name:           clusterName,
		ConnectTimeout: ptypes.DurationProto(timeout),
		ClusterDiscoveryType: &v2.Cluster_Type{
			Type: v2.Cluster_LOGICAL_DNS,
		},
		LbPolicy: v2.Cluster_ROUND_ROBIN,
		DnsLookupFamily: v2.Cluster_V4_ONLY,
		DnsResolvers: []*core.Address{
			{
				Address: &core.Address_SocketAddress{
					SocketAddress: &core.SocketAddress{
						Address: "127.0.0.1",
						PortSpecifier: &core.SocketAddress_PortValue{
							PortValue: 8080,
						},
					},
				},
			},
		},
	}

	// 2. Validate valid cluster
	if err := cluster.Validate(); err != nil {
		return fmt.Errorf("valid cluster failed validation: %w", err)
	}

	// 3. Validation failure check (empty cluster name)
	invalidCluster := &v2.Cluster{}
	if err := invalidCluster.Validate(); err == nil {
		return fmt.Errorf("expected validation error for empty cluster, but got nil")
	}

	// 4. Protobuf wire serialization and deserialization
	data, err := proto.Marshal(cluster)
	if err != nil {
		return fmt.Errorf("proto.Marshal failed: %w", err)
	}
	unmarshaled := &v2.Cluster{}
	if err := proto.Unmarshal(data, unmarshaled); err != nil {
		return fmt.Errorf("proto.Unmarshal failed: %w", err)
	}
	if unmarshaled.GetName() != clusterName {
		return fmt.Errorf("unmarshaled cluster name mismatch: got %q, want %q", unmarshaled.GetName(), clusterName)
	}
	if unmarshaled.GetLbPolicy() != v2.Cluster_ROUND_ROBIN {
		return fmt.Errorf("unmarshaled cluster lbPolicy mismatch: got %v, want %v", unmarshaled.GetLbPolicy(), v2.Cluster_ROUND_ROBIN)
	}
	if !proto.Equal(cluster, unmarshaled) {
		return fmt.Errorf("unmarshaled cluster does not equal original cluster")
	}

	// 5. Any packing and type URL verification
	anyMsg, err := ptypes.MarshalAny(cluster)
	if err != nil {
		return fmt.Errorf("ptypes.MarshalAny failed: %w", err)
	}
	expectedTypeURL := "type.googleapis.com/envoy.api.v2.Cluster"
	if anyMsg.GetTypeUrl() != expectedTypeURL {
		return fmt.Errorf("type URL mismatch: got %q, want %q", anyMsg.GetTypeUrl(), expectedTypeURL)
	}
	if !ptypes.Is(anyMsg, cluster) {
		return fmt.Errorf("ptypes.Is returned false for cluster message")
	}
	var unpackedCluster v2.Cluster
	if err := ptypes.UnmarshalAny(anyMsg, &unpackedCluster); err != nil {
		return fmt.Errorf("ptypes.UnmarshalAny failed: %w", err)
	}
	if !proto.Equal(cluster, &unpackedCluster) {
		return fmt.Errorf("unpacked cluster does not equal original cluster")
	}

	// 6. Integration with pkg/cache
	if cache.ClusterType != expectedTypeURL {
		return fmt.Errorf("cache.ClusterType mismatch: got %q, want %q", cache.ClusterType, expectedTypeURL)
	}
	snapshot := cache.NewSnapshot("v1", nil, []cache.Resource{cluster}, nil, nil, nil)
	if err := snapshot.Consistent(); err != nil {
		return fmt.Errorf("snapshot is inconsistent: %w", err)
	}
	clusters := snapshot.GetResources(cache.ClusterType)
	if len(clusters) != 1 {
		return fmt.Errorf("expected 1 cluster in snapshot, got %d", len(clusters))
	}
	retrievedResource, ok := clusters[clusterName]
	if !ok {
		return fmt.Errorf("cluster %q not found in snapshot", clusterName)
	}
	retrievedCluster, ok := retrievedResource.(*v2.Cluster)
	if !ok {
		return fmt.Errorf("retrieved resource is not *v2.Cluster")
	}
	if retrievedCluster.GetName() != clusterName {
		return fmt.Errorf("retrieved cluster name mismatch: got %q, want %q", retrievedCluster.GetName(), clusterName)
	}
	if snapshot.GetVersion(cache.ClusterType) != "v1" {
		return fmt.Errorf("snapshot version mismatch: got %q, want %q", snapshot.GetVersion(cache.ClusterType), "v1")
	}

	return nil
}