github.com/cncf/xds/go v0.0.0-20250501225837-2ac532fd4443: v3.ResourceLocator

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/cncf/xds/go/xds/core/v3.ResourceLocator in pkg:golang/github.com/cncf/xds/go@v0.0.0-20250501225837-2ac532fd4443
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/cncf/xds/go@v0.0.0-20250501225837-2ac532fd4443
Demonstrate these symbols/APIs:
  - github.com/cncf/xds/go/xds/core/v3.ResourceLocator

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:f43d7fe1d3802fc63a385003ba6b1002dc996a70cc2c6499561e61af71500ca9","contract":["ResourceLocator initializes with scheme, id, authority, resource type, exact context, and directives","ResourceLocator getters safely return values and handle nil receivers without panic","ResourceLocator validation succeeds for valid instances with non-empty resource type and valid scheme","ResourceLocator validation fails when resource type is empty or scheme is invalid","ResourceLocator serializes to and deserializes from binary Protobuf format satisfying proto.Equal","proto.Clone produces an isolated deep copy of ResourceLocator where mutating fields does not affect the original"],"goal":"verify github.com/cncf/xds/go/xds/core/v3.ResourceLocator in pkg:golang/github.com/cncf/xds/go@v0.0.0-20250501225837-2ac532fd4443","kind":"HOW","packages":["pkg:golang/github.com/cncf/xds/go@v0.0.0-20250501225837-2ac532fd4443"],"schemaVersion":1,"symbols":["github.com/cncf/xds/go/xds/core/v3.ResourceLocator"]},"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/cncf/xds/go@v0.0.0-20250501225837-2ac532fd4443"],"schemaVersion":1,"subject":"pkg:golang/github.com/cncf/xds/go@v0.0.0-20250501225837-2ac532fd4443","symbols":["github.com/cncf/xds/go/xds/core/v3.ResourceLocator"],"verifierAdapter":"golang@1"}

module example.com/resourcelocator

go 1.23.0

require (
	github.com/cncf/xds/go v0.0.0-20250501225837-2ac532fd4443
	google.golang.org/protobuf v1.33.0
)

require github.com/envoyproxy/protoc-gen-validate v1.0.4 // indirect

github.com/cncf/xds/go v0.0.0-20250501225837-2ac532fd4443 h1:aQ3y1lwWyqYPiWZThqv1aFbZMiM9vblcSArJRf2Irls=
github.com/cncf/xds/go v0.0.0-20250501225837-2ac532fd4443/go.mod h1:W+zGtBO5Y1IgJhy4+A9GOqVhqLpfZi+vwmdNXUehLA8=
github.com/envoyproxy/protoc-gen-validate v1.0.4 h1:gVPz/FMfvh57HdSJQyvBtF00j8JU4zdyUgIUNhlgg0A=
github.com/envoyproxy/protoc-gen-validate v1.0.4/go.mod h1:qys6tmnRsYrQqIhm2bvKZH4Blx/1gTIZ2UKVY1M+Yew=
github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
google.golang.org/protobuf v1.33.0 h1:uNO2rsAINq/JlFpSdYEKIZ0uKD/R9cpdv0T+yoGwGmI=
google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=

{
  "schemaVersion": 1,
  "goal": "verify github.com/cncf/xds/go/xds/core/v3.ResourceLocator in pkg:golang/github.com/cncf/xds/go@v0.0.0-20250501225837-2ac532fd4443",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/cncf/xds/go@v0.0.0-20250501225837-2ac532fd4443"
  ],
  "symbols": [
    "github.com/cncf/xds/go/xds/core/v3.ResourceLocator"
  ]
}

package main

import (
	"fmt"
	"os"

	corev3 "github.com/cncf/xds/go/xds/core/v3"
	"google.golang.org/protobuf/proto"
)

func assert(condition bool, message string) {
	if !condition {
		fmt.Fprintf(os.Stderr, "assertion failed: %s\n", message)
		os.Exit(1)
	}
}

func main() {
	// Assertion 1: ResourceLocator initializes with scheme, id, authority, resource type, exact context, and directives
	{
		locator := &corev3.ResourceLocator{
			Scheme:       corev3.ResourceLocator_XDSTP,
			Id:           "service-config",
			Authority:    "example.com",
			ResourceType: "envoy.config.listener.v3.Listener",
			ContextParamSpecifier: &corev3.ResourceLocator_ExactContext{
				ExactContext: &corev3.ContextParams{
					Params: map[string]string{
						"node": "edge-node-1",
					},
				},
			},
			Directives: []*corev3.ResourceLocator_Directive{
				{
					Directive: &corev3.ResourceLocator_Directive_Entry{
						Entry: "alt-entry",
					},
				},
			},
		}
		assert(locator.GetScheme() == corev3.ResourceLocator_XDSTP, "expected XDSTP scheme")
		assert(locator.GetId() == "service-config", "expected id service-config")
		assert(locator.GetAuthority() == "example.com", "expected authority example.com")
		assert(locator.GetResourceType() == "envoy.config.listener.v3.Listener", "expected resource type")
		assert(locator.GetExactContext() != nil, "expected non-nil exact context")
		assert(locator.GetExactContext().GetParams()["node"] == "edge-node-1", "expected param node=edge-node-1")
		assert(len(locator.GetDirectives()) == 1, "expected 1 directive")
		assert(locator.GetDirectives()[0].GetEntry() == "alt-entry", "expected directive entry alt-entry")
	}

	// Assertion 2: ResourceLocator getters safely return values and handle nil receivers without panic
	{
		var nilLocator *corev3.ResourceLocator
		assert(nilLocator.GetScheme() == corev3.ResourceLocator_XDSTP, "nil ResourceLocator GetScheme must return default enum XDSTP")
		assert(nilLocator.GetId() == "", "nil ResourceLocator GetId must return empty string")
		assert(nilLocator.GetAuthority() == "", "nil ResourceLocator GetAuthority must return empty string")
		assert(nilLocator.GetResourceType() == "", "nil ResourceLocator GetResourceType must return empty string")
		assert(nilLocator.GetExactContext() == nil, "nil ResourceLocator GetExactContext must return nil")
		assert(nilLocator.GetDirectives() == nil, "nil ResourceLocator GetDirectives must return nil")
		assert(nilLocator.Validate() == nil, "nil ResourceLocator Validate must return nil")
		assert(nilLocator.ValidateAll() == nil, "nil ResourceLocator ValidateAll must return nil")

		emptyLocator := &corev3.ResourceLocator{}
		assert(emptyLocator.GetScheme() == corev3.ResourceLocator_XDSTP, "empty ResourceLocator GetScheme must return XDSTP")
		assert(emptyLocator.GetId() == "", "empty ResourceLocator GetId must return empty string")
		assert(emptyLocator.GetAuthority() == "", "empty ResourceLocator GetAuthority must return empty string")
		assert(emptyLocator.GetResourceType() == "", "empty ResourceLocator GetResourceType must return empty string")
		assert(emptyLocator.GetExactContext() == nil, "empty ResourceLocator GetExactContext must return nil")
		assert(emptyLocator.GetDirectives() == nil, "empty ResourceLocator GetDirectives must return nil")
	}

	// Assertion 3: ResourceLocator validation succeeds for valid instances with non-empty resource type and valid scheme
	{
		validLocator := &corev3.ResourceLocator{
			Scheme:       corev3.ResourceLocator_XDSTP,
			ResourceType: "envoy.config.listener.v3.Listener",
		}
		assert(validLocator.Validate() == nil, "expected valid ResourceLocator Validate() to return nil")
		assert(validLocator.ValidateAll() == nil, "expected valid ResourceLocator ValidateAll() to return nil")

		validHttp := &corev3.ResourceLocator{
			Scheme:       corev3.ResourceLocator_HTTP,
			Authority:    "example.com",
			ResourceType: "envoy.config.cluster.v3.Cluster",
			ContextParamSpecifier: &corev3.ResourceLocator_ExactContext{
				ExactContext: &corev3.ContextParams{
					Params: map[string]string{"env": "prod"},
				},
			},
			Directives: []*corev3.ResourceLocator_Directive{
				{
					Directive: &corev3.ResourceLocator_Directive_Alt{
						Alt: &corev3.ResourceLocator{
							Scheme:       corev3.ResourceLocator_FILE,
							ResourceType: "envoy.config.cluster.v3.Cluster",
						},
					},
				},
			},
		}
		assert(validHttp.Validate() == nil, "expected valid HTTP ResourceLocator Validate() to return nil")
		assert(validHttp.ValidateAll() == nil, "expected valid HTTP ResourceLocator ValidateAll() to return nil")
	}

	// Assertion 4: ResourceLocator validation fails when resource type is empty or scheme is invalid
	{
		emptyResourceType := &corev3.ResourceLocator{
			Scheme:       corev3.ResourceLocator_XDSTP,
			ResourceType: "",
		}
		assert(emptyResourceType.Validate() != nil, "expected Validate() error for empty ResourceType")

		invalidScheme := &corev3.ResourceLocator{
			Scheme:       corev3.ResourceLocator_Scheme(999),
			ResourceType: "envoy.config.listener.v3.Listener",
		}
		assert(invalidScheme.Validate() != nil, "expected Validate() error for invalid Scheme")

		invalidBoth := &corev3.ResourceLocator{
			Scheme:       corev3.ResourceLocator_Scheme(999),
			ResourceType: "",
		}
		assert(invalidBoth.ValidateAll() != nil, "expected ValidateAll() error when both fields are invalid")
	}

	// Assertion 5: ResourceLocator serializes to and deserializes from binary Protobuf format satisfying proto.Equal
	{
		orig := &corev3.ResourceLocator{
			Scheme:       corev3.ResourceLocator_XDSTP,
			Id:           "locator-123",
			Authority:    "example.com",
			ResourceType: "envoy.config.route.v3.RouteConfiguration",
			ContextParamSpecifier: &corev3.ResourceLocator_ExactContext{
				ExactContext: &corev3.ContextParams{
					Params: map[string]string{
						"cluster": "internal",
					},
				},
			},
		}
		wire, err := proto.Marshal(orig)
		assert(err == nil, "proto.Marshal failed")
		assert(len(wire) > 0, "marshaled wire length is 0")

		unmarshaled := &corev3.ResourceLocator{}
		err = proto.Unmarshal(wire, unmarshaled)
		assert(err == nil, "proto.Unmarshal failed")
		assert(proto.Equal(orig, unmarshaled), "proto.Equal returned false after unmarshal")
		assert(unmarshaled.GetId() == "locator-123", "unmarshaled Id mismatch")
		assert(unmarshaled.GetAuthority() == "example.com", "unmarshaled Authority mismatch")
		assert(unmarshaled.GetResourceType() == "envoy.config.route.v3.RouteConfiguration", "unmarshaled ResourceType mismatch")
		assert(unmarshaled.GetExactContext().GetParams()["cluster"] == "internal", "unmarshaled exact context mismatch")
	}

	// Assertion 6: proto.Clone produces an isolated deep copy of ResourceLocator where mutating fields does not affect the original
	{
		orig := &corev3.ResourceLocator{
			Scheme:       corev3.ResourceLocator_XDSTP,
			Id:           "orig-id",
			Authority:    "example.com",
			ResourceType: "envoy.config.listener.v3.Listener",
			ContextParamSpecifier: &corev3.ResourceLocator_ExactContext{
				ExactContext: &corev3.ContextParams{
					Params: map[string]string{
						"stage": "canary",
					},
				},
			},
			Directives: []*corev3.ResourceLocator_Directive{
				{
					Directive: &corev3.ResourceLocator_Directive_Entry{
						Entry: "directive-1",
					},
				},
			},
		}
		cloned := proto.Clone(orig).(*corev3.ResourceLocator)
		assert(proto.Equal(orig, cloned), "cloned ResourceLocator must equal original")

		cloned.Id = "mutated-id"
		cloned.Authority = "other.example.com"
		cloned.GetExactContext().GetParams()["stage"] = "production"
		cloned.Directives[0] = &corev3.ResourceLocator_Directive{
			Directive: &corev3.ResourceLocator_Directive_Entry{
				Entry: "mutated-directive",
			},
		}

		assert(orig.GetId() == "orig-id", "original Id was mutated")
		assert(orig.GetAuthority() == "example.com", "original Authority was mutated")
		assert(orig.GetExactContext().GetParams()["stage"] == "canary", "original exact context was mutated")
		assert(orig.GetDirectives()[0].GetEntry() == "directive-1", "original directive was mutated")
	}

	fmt.Println("PASS: all github.com/cncf/xds/go/xds/core/v3.ResourceLocator contract assertions verified")
}