@opensoha/contracts 0.1.25 → 0.1.27

package/resource/relations.go

@@ -0,0 +1,225 @@
+package resource
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+const RelationSnapshotFeature = "resource-relations.metadata.v1"
+const RelationMaxQueries = 32
+const RelationMaxItems = 200
+const RelationMaxNodes = 500
+const RelationMaxDepth = 8
+
+var ErrRelationSnapshotUnsupported = errors.New("resource relation metadata snapshot unsupported")
+
+func DefaultRelationSources(namespace string) []RelationSource {
+	return []RelationSource{
+		{APIVersion: "v1", Resource: "pods", Kind: "Pod", Namespace: namespace},
+		{APIVersion: "apps/v1", Resource: "deployments", Kind: "Deployment", Namespace: namespace},
+		{APIVersion: "apps/v1", Resource: "replicasets", Kind: "ReplicaSet", Namespace: namespace},
+		{APIVersion: "apps/v1", Resource: "statefulsets", Kind: "StatefulSet", Namespace: namespace},
+		{APIVersion: "apps/v1", Resource: "daemonsets", Kind: "DaemonSet", Namespace: namespace},
+		{APIVersion: "batch/v1", Resource: "jobs", Kind: "Job", Namespace: namespace},
+		{APIVersion: "batch/v1", Resource: "cronjobs", Kind: "CronJob", Namespace: namespace},
+		{APIVersion: "v1", Resource: "services", Kind: "Service", Namespace: namespace},
+		{APIVersion: "v1", Resource: "persistentvolumeclaims", Kind: "PersistentVolumeClaim", Namespace: namespace},
+		{APIVersion: "v1", Resource: "configmaps", Kind: "ConfigMap", Namespace: namespace},
+		{APIVersion: "v1", Resource: "secrets", Kind: "Secret", Namespace: namespace},
+		{APIVersion: "networking.k8s.io/v1", Resource: "ingresses", Kind: "Ingress", Namespace: namespace},
+	}
+}
+
+func IsBuiltinRelationSource(source RelationSource) bool {
+	for _, builtin := range DefaultRelationSources(source.Namespace) {
+		if builtin == source {
+			return true
+		}
+	}
+	return false
+}
+
+// RelationSource always names an explicit namespaced API collection. Discovery
+// must verify the resource/kind pair before reading it.
+type RelationSource struct {
+	APIVersion string `json:"apiVersion"`
+	Resource   string `json:"resource"`
+	Kind       string `json:"kind"`
+	Namespace  string `json:"namespace"`
+}
+
+type RelationRule struct {
+	ID       string            `json:"id"`
+	Type     string            `json:"type"`
+	Target   RelationSource    `json:"target"`
+	Name     string            `json:"name,omitempty"`
+	UID      string            `json:"uid,omitempty"`
+	Selector map[string]string `json:"selector,omitempty"`
+}
+
+type RelationConfig struct {
+	Version string           `json:"version"`
+	RootUID string           `json:"rootUid"`
+	Sources []RelationSource `json:"sources"`
+	Rules   []RelationRule   `json:"rules"`
+}
+
+type RelationQuery struct {
+	ID       string            `json:"id"`
+	Source   RelationSource    `json:"source"`
+	Name     string            `json:"name,omitempty"`
+	Selector map[string]string `json:"selector,omitempty"`
+}
+
+type RelationSnapshotRequest struct {
+	Queries []RelationQuery `json:"queries"`
+}
+type RelationOwner struct {
+	APIVersion string `json:"apiVersion"`
+	Kind       string `json:"kind"`
+	Name       string `json:"name"`
+	UID        string `json:"uid"`
+	Controller bool   `json:"controller"`
+}
+
+type RelationObject struct {
+	Resource ResourceRef     `json:"resource"`
+	Owners   []RelationOwner `json:"owners,omitempty"`
+}
+type RelationCoverage struct {
+	QueryID    string `json:"queryId"`
+	State      string `json:"state"`
+	ReasonCode string `json:"reasonCode,omitempty"`
+	Truncated  bool   `json:"truncated"`
+}
+type RelationSourceResult struct {
+	Coverage RelationCoverage `json:"coverage"`
+	Objects  []RelationObject `json:"objects"`
+}
+type RelationSnapshot struct {
+	Version string                 `json:"version"`
+	Sources []RelationSourceResult `json:"sources"`
+}
+type RelationNode struct {
+	Resource ResourceRef `json:"resource"`
+	Role     string      `json:"role"`
+	Depth    int         `json:"depth"`
+}
+type RelationEdge struct {
+	FromUID string `json:"fromUid"`
+	ToUID   string `json:"toUid"`
+	Type    string `json:"type"`
+	RuleID  string `json:"ruleId,omitempty"`
+}
+type ResourceRelationsView struct {
+	Root       ResourceRef        `json:"root"`
+	Config     RelationConfig     `json:"config"`
+	Nodes      []RelationNode     `json:"nodes"`
+	Edges      []RelationEdge     `json:"edges"`
+	Coverage   []RelationCoverage `json:"coverage"`
+	Partial    bool               `json:"partial"`
+	ObservedAt string             `json:"observedAt"`
+}
+
+var relationDNS = regexp.MustCompile(`^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$`)
+var relationKind = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9]*$`)
+var relationToken = regexp.MustCompile(`^[a-zA-Z0-9_.-]+$`)
+var relationLabelKey = regexp.MustCompile(`^[a-zA-Z0-9_.-]+(/[a-zA-Z0-9_.-]+)?$`)
+
+func ValidateRelationSource(s RelationSource) error {
+	parts := strings.Split(s.APIVersion, "/")
+	if len(parts) > 2 || len(parts) == 0 || len(s.APIVersion) > 320 {
+		return fmt.Errorf("invalid resource API version")
+	}
+	for _, part := range parts {
+		if !relationDNS.MatchString(part) {
+			return fmt.Errorf("invalid resource API version")
+		}
+	}
+	if !relationDNS.MatchString(s.Resource) || len(s.Resource) > 63 || strings.Contains(s.Resource, ".") || !relationKind.MatchString(s.Kind) || len(s.Kind) > 128 {
+		return fmt.Errorf("invalid resource definition")
+	}
+	if !relationDNS.MatchString(s.Namespace) || strings.Contains(s.Namespace, ".") || len(s.Namespace) > 63 {
+		return fmt.Errorf("an explicit namespace is required")
+	}
+	return nil
+}
+
+func validateRelationSelector(selector map[string]string) error {
+	if len(selector) > 16 {
+		return fmt.Errorf("too many label terms")
+	}
+	for key, value := range selector {
+		if len(key) > 317 || !relationLabelKey.MatchString(key) || len(value) > 63 || (value != "" && !relationToken.MatchString(value)) {
+			return fmt.Errorf("invalid label selector")
+		}
+	}
+	return nil
+}
+
+func ValidateRelationConfig(config RelationConfig) error {
+	if config.Sources == nil || config.Rules == nil {
+		return fmt.Errorf("sources and rules must be arrays")
+	}
+	data, err := json.Marshal(config)
+	if err != nil || len(data) > 16<<10 || config.Version != "v1" || strings.TrimSpace(config.RootUID) == "" || len(config.RootUID) > 128 || len(config.Sources) > 8 || len(config.Rules) > 8 {
+		return fmt.Errorf("invalid relation configuration or budget")
+	}
+	for _, source := range config.Sources {
+		if err := ValidateRelationSource(source); err != nil {
+			return err
+		}
+	}
+	seen := map[string]bool{}
+	for _, rule := range config.Rules {
+		if !relationToken.MatchString(rule.ID) || len(rule.ID) > 64 || seen[rule.ID] {
+			return fmt.Errorf("invalid or duplicate rule ID")
+		}
+		seen[rule.ID] = true
+		if err := ValidateRelationSource(rule.Target); err != nil {
+			return err
+		}
+		switch rule.Type {
+		case "reference", "manual":
+			if !relationDNS.MatchString(rule.Name) || len(rule.Name) > 253 || len(rule.Selector) != 0 || len(rule.UID) > 128 || (rule.Type == "manual" && strings.TrimSpace(rule.UID) == "") {
+				return fmt.Errorf("named manual relations require a fixed UID")
+			}
+		case "selector":
+			if rule.Name != "" || rule.UID != "" || len(rule.Selector) == 0 {
+				return fmt.Errorf("selector rules must declare labels only")
+			}
+		default:
+			return fmt.Errorf("unknown relation rule type")
+		}
+		if err := validateRelationSelector(rule.Selector); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func ValidateRelationSnapshotRequest(input RelationSnapshotRequest) error {
+	if len(input.Queries) == 0 || len(input.Queries) > RelationMaxQueries {
+		return fmt.Errorf("invalid relation query budget")
+	}
+	seen := map[string]bool{}
+	for _, q := range input.Queries {
+		if q.ID == "" || len(q.ID) > 80 || !relationToken.MatchString(q.ID) || seen[q.ID] {
+			return fmt.Errorf("invalid query identity")
+		}
+		seen[q.ID] = true
+		if err := ValidateRelationSource(q.Source); err != nil {
+			return err
+		}
+		if q.Name != "" && (!relationDNS.MatchString(q.Name) || len(q.Name) > 253 || len(q.Selector) != 0) {
+			return fmt.Errorf("invalid named query")
+		}
+		if err := validateRelationSelector(q.Selector); err != nil {
+			return err
+		}
+	}
+	return nil
+}

package/resource/relations_test.go

@@ -0,0 +1,47 @@
+package resource
+
+import "testing"
+
+func TestRelationConfigSupportsUnknownKindsWithoutCodeRegistration(t *testing.T) {
+	source := RelationSource{APIVersion: "widgets.example.test/v1", Resource: "widgets", Kind: "Widget", Namespace: "team"}
+	config := RelationConfig{Version: "v1", RootUID: "root", Sources: []RelationSource{source}, Rules: []RelationRule{{ID: "shared", Type: "reference", Target: source, Name: "runtime"}}}
+	if err := ValidateRelationConfig(config); err != nil {
+		t.Fatal(err)
+	}
+	config.Rules[0].Type = "manual"
+	if ValidateRelationConfig(config) == nil {
+		t.Fatal("manual association accepted without UID")
+	}
+	config.Rules[0].UID = "fixed-runtime"
+	if err := ValidateRelationConfig(config); err != nil {
+		t.Fatal(err)
+	}
+	config.Rules[0].Target.Resource = "widgets/../../secrets"
+	if ValidateRelationConfig(config) == nil {
+		t.Fatal("path traversal accepted")
+	}
+}
+
+func TestRelationQueryBoundsAndSelectors(t *testing.T) {
+	q := RelationQuery{ID: "pods", Source: RelationSource{APIVersion: "v1", Resource: "pods", Kind: "Pod", Namespace: "team"}, Selector: map[string]string{"app": "demo"}}
+	for _, test := range []struct {
+		name   string
+		change func(*RelationQuery)
+	}{
+		{"all namespaces", func(q *RelationQuery) { q.Source.Namespace = "" }},
+		{"selector injection", func(q *RelationQuery) { q.Selector["app"] = "demo,secret=yes" }},
+		{"named selector", func(q *RelationQuery) { q.Name = "pod" }},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			copy := q
+			copy.Selector = map[string]string{"app": "demo"}
+			test.change(&copy)
+			if ValidateRelationSnapshotRequest(RelationSnapshotRequest{Queries: []RelationQuery{copy}}) == nil {
+				t.Fatal("invalid query accepted")
+			}
+		})
+	}
+	if ValidateRelationSnapshotRequest(RelationSnapshotRequest{Queries: []RelationQuery{q, q}}) == nil {
+		t.Fatal("duplicate query accepted")
+	}
+}

package/resource/root_cr.go

@@ -0,0 +1,38 @@
+package resource
+
+import (
+	"fmt"
+	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	"strings"
+)
+
+// ValidateRootCRDocument prevents a root publication from changing runtime metadata
+// or writing generated children. Operator reconciliation remains independent.
+func ValidateRootCRDocument(object map[string]any, root sohaapi.ManifestRootResource) error {
+	metadata, ok := object["metadata"].(map[string]any)
+	if !ok {
+		return fmt.Errorf("root CR metadata is required")
+	}
+	if root.UID == "" || root.Generation < 1 || root.CrdName == "" || !strings.Contains(root.APIVersion, "/") || root.Namespace == "" {
+		return fmt.Errorf("root CR requires a frozen namespaced identity")
+	}
+	if object["apiVersion"] != root.APIVersion || object["kind"] != root.Kind || metadata["namespace"] != root.Namespace || metadata["name"] != root.Name {
+		return fmt.Errorf("root CR identity differs from the approved resource")
+	}
+	for key := range object {
+		switch key {
+		case "apiVersion", "kind", "metadata", "spec":
+		default:
+			return fmt.Errorf("root CR updates only support spec")
+		}
+	}
+	for key := range metadata {
+		if key != "name" && key != "namespace" {
+			return fmt.Errorf("root CR runtime metadata cannot be published")
+		}
+	}
+	if _, ok := object["spec"].(map[string]any); !ok {
+		return fmt.Errorf("root CR spec must be an object")
+	}
+	return nil
+}

package/resource/runtime/argocd_integration_test.go

@@ -37,7 +37,7 @@ func TestArgoCDWithKubernetes(t *testing.T) {
 	operatorRequire(t, err)
 	kube, err := kubernetes.NewForConfig(config)
 	operatorRequire(t, err)
-	data, err := os.ReadFile(os.Getenv("SOHA_ARGOCD_TEST_STATE"))
+	data, err := os.ReadFile(os.Getenv("SOHA_ARGOCD_TEST_STATE")) // #nosec G703 -- Opt-in integration test reads the operator-selected local fixture path; no server request controls it.
 	operatorRequire(t, err)
 	var state map[string]json.RawMessage
 	operatorRequire(t, json.Unmarshal(data, &state))

package/resource/runtime/initialization.go

@@ -0,0 +1,66 @@
+package runtime
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+	"k8s.io/client-go/dynamic"
+)
+
+const ManifestInitializationCapability = "manifest.initialize.v1"
+const ManifestInitializationProviderPrefix = "manifest_initialize_v1."
+
+// ValidateManifestInitialization fences the new mode from legacy/controller writes.
+// Callers still own current authorization, immutable Plan validation and admission.
+func ValidateManifestInitialization(p sohaapi.ManifestExecutionTaskPayload) error {
+	if p.InitializationPlanID == "" {
+		return nil
+	}
+	if strings.TrimSpace(p.InitializationPlanID) != p.InitializationPlanID || len(p.InitializationPlanID) > 128 || p.ForceConflicts || p.RootResource != nil || p.RolloutControl != nil || len(p.GitOpsDocuments) != 0 {
+		return fmt.Errorf("%w: invalid initialization boundary", ErrResourceOwnership)
+	}
+	if p.Action != sohaapi.ManifestTaskActionPreflight && p.Action != sohaapi.ManifestTaskActionApply && p.Action != sohaapi.ManifestTaskActionObserve {
+		return fmt.Errorf("%w: initialization requires preflight, apply or observation", ErrResourceOwnership)
+	}
+	if IsRolloutTask(p) {
+		return fmt.Errorf("%w: controller delivery cannot guarantee create-only initialization", ErrResourceOwnership)
+	}
+	for _, document := range p.Documents {
+		if initializationController(document.APIVersion, document.Kind) {
+			return fmt.Errorf("%w: controller delivery cannot guarantee create-only initialization", ErrResourceOwnership)
+		}
+	}
+	return nil
+}
+
+func initializationController(apiVersion, kind string) bool {
+	return strings.HasPrefix(apiVersion, "kustomize.toolkit.fluxcd.io/") || strings.HasPrefix(apiVersion, "helm.toolkit.fluxcd.io/") || strings.HasPrefix(apiVersion, "argoproj.io/") && (kind == "Application" || kind == "Rollout")
+}
+
+// CreateManifest never falls back to SSA or adopts a concurrent object. Kubernetes
+// validates non-existence atomically for both dry-run and the actual POST.
+func CreateManifest(ctx context.Context, client dynamic.ResourceInterface, desired *unstructured.Unstructured, options metav1.CreateOptions) (*unstructured.Unstructured, error) {
+	if desired.GetUID() != "" || desired.GetResourceVersion() != "" || desired.GetGenerateName() != "" {
+		return nil, fmt.Errorf("%w: initialization requires a new named resource", ErrResourceOwnership)
+	}
+	if initializationController(desired.GetAPIVersion(), desired.GetKind()) {
+		return nil, fmt.Errorf("%w: controller delivery requires its existing publication path", ErrResourceOwnership)
+	}
+	if err := ValidateDirectManifestOwner(desired); err != nil {
+		return nil, err
+	}
+	return client.Create(ctx, desired, options)
+}
+
+// ValidateInitializedUID prevents a healthy same-name replacement from confirming
+// the baseline of a different object created by the approved initialization.
+func ValidateInitializedUID(live metav1.Object, expectedUID string) error {
+	if live == nil || expectedUID == "" || live.GetUID() == "" || string(live.GetUID()) != expectedUID {
+		return fmt.Errorf("%w: initialized resource identity is missing or changed", ErrResourceOwnership)
+	}
+	return nil
+}

package/resource/runtime/initialization_test.go

@@ -0,0 +1,80 @@
+package runtime
+
+import (
+	"context"
+	"testing"
+
+	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"k8s.io/client-go/dynamic/fake"
+	ktesting "k8s.io/client-go/testing"
+)
+
+func TestManifestInitializationCreatesWithoutAdoption(t *testing.T) {
+	object := &unstructured.Unstructured{Object: map[string]any{"apiVersion": "v1", "kind": "ConfigMap", "metadata": map[string]any{"name": "settings", "namespace": "test"}}}
+	gvr := schema.GroupVersionResource{Version: "v1", Resource: "configmaps"}
+	for _, existing := range []bool{false, true} {
+		t.Run(map[bool]string{false: "new", true: "concurrently-created"}[existing], func(t *testing.T) {
+			client := fake.NewSimpleDynamicClient(runtime.NewScheme())
+			if existing {
+				if err := client.Tracker().Create(gvr, object.DeepCopy(), "test"); err != nil {
+					t.Fatal(err)
+				}
+			}
+			_, err := CreateManifest(t.Context(), client.Resource(gvr).Namespace("test"), object.DeepCopy(), metav1.CreateOptions{})
+			if existing && !apierrors.IsAlreadyExists(err) || !existing && err != nil {
+				t.Fatalf("create existing=%v: %v", existing, err)
+			}
+			for _, action := range client.Actions() {
+				if action.GetVerb() != "create" {
+					t.Fatalf("initialization used %s instead of atomic create", action.GetVerb())
+				}
+			}
+		})
+	}
+	client := fake.NewSimpleDynamicClient(runtime.NewScheme())
+	client.PrependReactor("create", "configmaps", func(action ktesting.Action) (bool, runtime.Object, error) {
+		typed, ok := action.(interface{ GetCreateOptions() metav1.CreateOptions })
+		if !ok {
+			t.Fatalf("missing create options: %T", action)
+		}
+		if options := typed.GetCreateOptions(); len(options.DryRun) != 1 || options.DryRun[0] != metav1.DryRunAll {
+			t.Fatal("preflight lost server dry-run")
+		}
+		return true, object.DeepCopy(), nil
+	})
+	if _, err := CreateManifest(context.Background(), client.Resource(gvr).Namespace("test"), object, metav1.CreateOptions{DryRun: []string{metav1.DryRunAll}}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestManifestInitializationRejectsUnsafeModesAndReplacedUID(t *testing.T) {
+	p := sohaapi.ManifestExecutionTaskPayload{InitializationPlanID: "plan", Action: sohaapi.ManifestTaskActionApply}
+	if err := ValidateManifestInitialization(p); err != nil {
+		t.Fatal(err)
+	}
+	for _, action := range []sohaapi.ManifestTaskAction{sohaapi.ManifestTaskActionRepair, sohaapi.ManifestTaskActionRollback, sohaapi.ManifestTaskActionAdopt} {
+		p.Action = action
+		if err := ValidateManifestInitialization(p); err == nil {
+			t.Fatalf("accepted initialization %s", action)
+		}
+	}
+	p.Action, p.ForceConflicts = sohaapi.ManifestTaskActionApply, true
+	if ValidateManifestInitialization(p) == nil {
+		t.Fatal("initialization accepted forced conflicts")
+	}
+	live := &unstructured.Unstructured{}
+	live.SetUID("created-uid")
+	if err := ValidateInitializedUID(live, "created-uid"); err != nil {
+		t.Fatal(err)
+	}
+	for _, expected := range []string{"", "replaced-uid"} {
+		if ValidateInitializedUID(live, expected) == nil {
+			t.Fatal("unproven initialization UID was accepted")
+		}
+	}
+}

package/resource/runtime/relations.go

@@ -0,0 +1,161 @@
+package runtime
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+	"time"
+
+	resource "github.com/opensoha/soha-contracts/resource"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/client-go/rest"
+)
+
+// ReadRelationSnapshot reads metadata only. Its caller must authorize every
+// collection and namespace; Kubernetes RBAC still applies to the actual reads.
+func ReadRelationSnapshot(ctx context.Context, client rest.Interface, clusterID string, input resource.RelationSnapshotRequest) (resource.RelationSnapshot, error) {
+	if err := resource.ValidateRelationSnapshotRequest(input); err != nil {
+		return resource.RelationSnapshot{}, err
+	}
+	if client == nil {
+		return resource.RelationSnapshot{}, fmt.Errorf("resource metadata client unavailable")
+	}
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	out := resource.RelationSnapshot{Version: resource.RelationSnapshotFeature, Sources: []resource.RelationSourceResult{}}
+	budget := &topologyReadBudget{remaining: 8 << 20}
+	for _, query := range input.Queries {
+		out.Sources = append(out.Sources, readRelationSource(ctx, client, clusterID, query, budget))
+	}
+	return out, nil
+}
+
+func readRelationSource(ctx context.Context, client rest.Interface, clusterID string, q resource.RelationQuery, budget *topologyReadBudget) resource.RelationSourceResult {
+	out := resource.RelationSourceResult{Coverage: resource.RelationCoverage{QueryID: q.ID, State: "available"}, Objects: []resource.RelationObject{}}
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	group, version := relationGroupVersion(q.Source.APIVersion)
+	base := topologyAPIBase(group, version)
+	data, err := boundedTopologyGET(ctx, client, base, false, budget)
+	if err == nil {
+		err = validateRelationDiscovery(data, q.Source)
+	}
+	if err != nil {
+		out.Coverage.State, out.Coverage.ReasonCode = relationReadError(err)
+		return out
+	}
+	path := base + "/namespaces/" + q.Source.Namespace + "/" + q.Source.Resource
+	if q.Name != "" {
+		path += "/" + q.Name
+	}
+	request := client.Get().AbsPath(path)
+	if q.Name == "" {
+		request = request.Param("limit", "200").SetHeader("Accept", "application/json;as=PartialObjectMetadataList;g=meta.k8s.io;v=v1")
+	} else {
+		request = request.SetHeader("Accept", "application/json;as=PartialObjectMetadata;g=meta.k8s.io;v=v1")
+	}
+	if len(q.Selector) > 0 {
+		terms := []string{}
+		for k, v := range q.Selector {
+			terms = append(terms, k+"="+v)
+		}
+		sort.Strings(terms)
+		request = request.Param("labelSelector", strings.Join(terms, ","))
+	}
+	stream, err := request.Stream(ctx)
+	if err != nil {
+		out.Coverage.State, out.Coverage.ReasonCode = relationReadError(err)
+		return out
+	}
+	defer func() { _ = stream.Close() }()
+	data, err = io.ReadAll(io.LimitReader(&topologyBudgetReader{reader: stream, budget: budget}, (512<<10)+1))
+	if err != nil || len(data) > 512<<10 {
+		out.Coverage.State = "partial"
+		out.Coverage.ReasonCode = "byte_budget"
+		out.Coverage.Truncated = true
+		return out
+	}
+	return relationMetadataResult(out, clusterID, q, data)
+}
+
+func relationMetadataResult(out resource.RelationSourceResult, clusterID string, q resource.RelationQuery, data []byte) resource.RelationSourceResult {
+	var objects []metav1.PartialObjectMetadata
+	if q.Name != "" {
+		var object metav1.PartialObjectMetadata
+		if json.Unmarshal(data, &object) != nil {
+			out.Coverage.State = "error"
+			out.Coverage.ReasonCode = "invalid_response"
+			return out
+		}
+		objects = append(objects, object)
+	} else {
+		var list metav1.PartialObjectMetadataList
+		if json.Unmarshal(data, &list) != nil {
+			out.Coverage.State = "error"
+			out.Coverage.ReasonCode = "invalid_response"
+			return out
+		}
+		objects = list.Items
+		if list.Continue != "" || len(objects) > resource.RelationMaxItems {
+			out.Coverage.State = "partial"
+			out.Coverage.ReasonCode = "item_budget"
+			out.Coverage.Truncated = true
+		}
+	}
+	for i, object := range objects {
+		if i >= resource.RelationMaxItems {
+			break
+		}
+		if object.Name == "" || object.UID == "" || object.Namespace != q.Source.Namespace || (q.Name != "" && q.Name != object.Name) || len(object.OwnerReferences) > 32 {
+			out.Coverage.State = "partial"
+			out.Coverage.ReasonCode = "invalid_identity"
+			continue
+		}
+		item := resource.RelationObject{Resource: resource.ResourceRef{ClusterID: clusterID, APIVersion: q.Source.APIVersion, Kind: q.Source.Kind, Namespace: object.Namespace, Name: object.Name, UID: string(object.UID), ResourceVersion: object.ResourceVersion, ScopeMode: resource.ResourceScopeModeNamespace}}
+		for _, owner := range object.OwnerReferences {
+			item.Owners = append(item.Owners, resource.RelationOwner{APIVersion: owner.APIVersion, Kind: owner.Kind, Name: owner.Name, UID: string(owner.UID), Controller: owner.Controller != nil && *owner.Controller})
+		}
+		out.Objects = append(out.Objects, item)
+	}
+	return out
+}
+
+func relationGroupVersion(apiVersion string) (string, string) {
+	parts := strings.SplitN(apiVersion, "/", 2)
+	if len(parts) == 1 {
+		return "", parts[0]
+	}
+	return parts[0], parts[1]
+}
+
+func validateRelationDiscovery(data []byte, source resource.RelationSource) error {
+	var list metav1.APIResourceList
+	if json.Unmarshal(data, &list) != nil {
+		return fmt.Errorf("invalid discovery response")
+	}
+	for _, item := range list.APIResources {
+		if item.Name == source.Resource && item.Kind == source.Kind && item.Namespaced {
+			return nil
+		}
+	}
+	return errRelationSourceNotServed
+}
+
+var errRelationSourceNotServed = errors.New("resource definition not served")
+
+func relationReadError(err error) (string, string) {
+	if errors.Is(err, context.DeadlineExceeded) {
+		return "error", "timeout"
+	}
+	if errors.Is(err, context.Canceled) {
+		return "error", "cancelled"
+	}
+	if errors.Is(err, errRelationSourceNotServed) {
+		return "not_installed", "source_not_served"
+	}
+	return topologyReadError(err)
+}