@opensoha/contracts 0.1.25 → 0.1.26

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)
+}

package/resource/runtime/relations_test.go

@@ -0,0 +1,100 @@
+package runtime
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	cr "github.com/opensoha/soha-contracts/resource"
+	"k8s.io/client-go/kubernetes"
+	"k8s.io/client-go/rest"
+)
+
+func TestRelationMetadataProjectionAndPartialCoverage(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path == "/apis/widgets.test/v1" {
+			_, _ = w.Write([]byte(`{"resources":[{"name":"widgets","kind":"Widget","namespaced":true}]}`))
+			return
+		}
+		if strings.Contains(r.Header.Get("Accept"), "q=0.9") {
+			t.Error("full JSON fallback must not be negotiated")
+		}
+		if r.URL.Query().Get("limit") != "200" || r.URL.Query().Get("labelSelector") != "app=demo" {
+			t.Errorf("unbounded or different query: %s", r.URL.String())
+		}
+		_, _ = w.Write([]byte(`{"metadata":{"continue":"next"},"items":[{"metadata":{"name":"child","namespace":"team","uid":"child-uid","annotations":{"password":"synthetic-private"},"labels":{"token":"synthetic-private"},"ownerReferences":[{"apiVersion":"widgets.test/v1","kind":"Widget","name":"root","uid":"root-uid"}]},"spec":{"password":"synthetic-private"},"status":{"secret":"synthetic-private"}}]}`))
+	}))
+	defer server.Close()
+	client, err := kubernetes.NewForConfig(&rest.Config{Host: server.URL})
+	if err != nil {
+		t.Fatal(err)
+	}
+	q := cr.RelationQuery{ID: "unknown", Source: cr.RelationSource{APIVersion: "widgets.test/v1", Resource: "widgets", Kind: "Widget", Namespace: "team"}, Selector: map[string]string{"app": "demo"}}
+	view, err := ReadRelationSnapshot(context.Background(), client.CoreV1().RESTClient(), "cluster", cr.RelationSnapshotRequest{Queries: []cr.RelationQuery{q}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(view.Sources) != 1 || view.Sources[0].Coverage.State != "partial" || !view.Sources[0].Coverage.Truncated || len(view.Sources[0].Objects) != 1 {
+		t.Fatalf("incorrect result: %+v", view)
+	}
+	data, _ := json.Marshal(view)
+	if strings.Contains(string(data), "synthetic-private") {
+		t.Fatal("configuration value leaked")
+	}
+	object := view.Sources[0].Objects[0]
+	if object.Resource.UID != "child-uid" || object.Owners[0].UID != "root-uid" {
+		t.Fatal("UID evidence lost")
+	}
+	q.Source.Kind = "DifferentKind"
+	view, err = ReadRelationSnapshot(context.Background(), client.CoreV1().RESTClient(), "cluster", cr.RelationSnapshotRequest{Queries: []cr.RelationQuery{q}})
+	if err != nil || len(view.Sources[0].Objects) != 0 || view.Sources[0].Coverage.State == "available" {
+		t.Fatal("unverified GVR/kind accepted")
+	}
+}
+
+func TestRelationMetadataNegotiationFailsClosed(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path == "/api/v1" {
+			_, _ = w.Write([]byte(`{"resources":[{"name":"secrets","kind":"Secret","namespaced":true}]}`))
+			return
+		}
+		if strings.Contains(r.Header.Get("Accept"), ",application/json") {
+			t.Error("full Secret requested")
+		}
+		w.WriteHeader(http.StatusNotAcceptable)
+	}))
+	defer server.Close()
+	client, err := kubernetes.NewForConfig(&rest.Config{Host: server.URL})
+	if err != nil {
+		t.Fatal(err)
+	}
+	query := cr.RelationQuery{ID: "secrets", Source: cr.RelationSource{APIVersion: "v1", Resource: "secrets", Kind: "Secret", Namespace: "team"}}
+	snapshot, err := ReadRelationSnapshot(context.Background(), client.CoreV1().RESTClient(), "cluster", cr.RelationSnapshotRequest{Queries: []cr.RelationQuery{query}})
+	if err != nil || len(snapshot.Sources[0].Objects) != 0 || snapshot.Sources[0].Coverage.State == "available" {
+		t.Fatalf("metadata refusal not closed: %+v %v", snapshot, err)
+	}
+}
+
+func TestRelationReadErrorsRetainCoverageReasons(t *testing.T) {
+	for _, tc := range []struct {
+		err           error
+		state, reason string
+	}{
+		{fmt.Errorf("request: %w", context.DeadlineExceeded), "error", "timeout"},
+		{context.Canceled, "error", "cancelled"},
+		{errRelationSourceNotServed, "not_installed", "source_not_served"},
+		{errors.New("opaque server response"), "error", "source_unavailable"},
+	} {
+		state, reason := relationReadError(tc.err)
+		if state != tc.state || reason != tc.reason {
+			t.Fatalf("%v became %s/%s", tc.err, state, reason)
+		}
+	}
+}

package/resource/runtime/root_cr.go

@@ -0,0 +1,79 @@
+package runtime
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	contractresource "github.com/opensoha/soha-contracts/resource"
+	"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"
+	"k8s.io/client-go/util/retry"
+)
+
+const RootCRAgentCapability = "manifest.root-cr.v1"
+const RootCRAgentProviderPrefix = "manifest_root_cr_v1."
+
+// ApplyRootCR updates only spec after an explicit publication handoff. It reuses
+// the workbench optimistic update semantics and preserves runtime metadata/status.
+// A retry may acknowledge the same desired spec already applied to the same UID.
+func ApplyRootCR(ctx context.Context, client dynamic.ResourceInterface, desired *unstructured.Unstructured, root sohaapi.ManifestRootResource, options metav1.PatchOptions) (*unstructured.Unstructured, error) {
+	if err := contractresource.ValidateRootCRDocument(desired.Object, root); err != nil {
+		return nil, err
+	}
+	if options.Force != nil && *options.Force {
+		return nil, fmt.Errorf("root CR cannot force field ownership")
+	}
+	var applied *unstructured.Unstructured
+	err := retry.RetryOnConflict(retry.DefaultRetry, func() error {
+		live, err := client.Get(ctx, root.Name, metav1.GetOptions{})
+		if err != nil {
+			return err
+		}
+		if string(live.GetUID()) != root.UID {
+			return fmt.Errorf("root CR UID changed; create a new plan")
+		}
+		if err := validateRootCROwner(live); err != nil {
+			return err
+		}
+		sameSpec := rootSpecEqual(live.Object["spec"], desired.Object["spec"])
+		if live.GetGeneration() != root.Generation && !sameSpec {
+			return fmt.Errorf("root CR configuration changed; create a new plan")
+		}
+		if sameSpec {
+			applied = live
+			return nil
+		}
+		write := live.DeepCopy()
+		write.Object["spec"] = desired.DeepCopy().Object["spec"]
+		applied, err = client.Update(ctx, write, metav1.UpdateOptions{FieldManager: options.FieldManager, DryRun: options.DryRun, FieldValidation: options.FieldValidation})
+		return err
+	})
+	return applied, err
+}
+
+func validateRootCROwner(live *unstructured.Unstructured) error {
+	if err := ValidateDirectManifestOwner(live); err != nil {
+		return err
+	}
+	manager := strings.ToLower(live.GetLabels()["app.kubernetes.io/managed-by"])
+	if len(live.GetOwnerReferences()) > 0 || (manager != "" && manager != "soha") {
+		return fmt.Errorf("%w: root CR has an external owner", ErrResourceOwnership)
+	}
+	for key := range live.GetAnnotations() {
+		if strings.HasPrefix(key, "meta.helm.sh/") || strings.HasPrefix(key, "argocd.argoproj.io/") {
+			return fmt.Errorf("%w: root CR has an external publisher", ErrResourceOwnership)
+		}
+	}
+	return nil
+}
+
+func rootSpecEqual(left, right any) bool {
+	a, aErr := json.Marshal(left)
+	b, bErr := json.Marshal(right)
+	return aErr == nil && bErr == nil && bytes.Equal(a, b)
+}

package/resource/runtime/root_cr_test.go

@@ -0,0 +1,118 @@
+package runtime
+
+import (
+	"context"
+	"reflect"
+	"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 TestRootCRPublicationFences(t *testing.T) {
+	for _, mode := range []string{"apply", "dry-run", "retry", "replaced", "changed", "deleted", "deleting", "helm", "git", "controller", "status", "finalizer", "force", "conflict-replaced"} {
+		t.Run(mode, func(t *testing.T) {
+			root, live, desired, options := rootPublicationFixture(mode)
+			client := fake.NewSimpleDynamicClient(runtime.NewScheme(), live)
+			gvr := schema.GroupVersionResource{Group: "unknown.example", Version: "v1", Resource: "databases"}
+			resources := client.Resource(gvr).Namespace("team")
+			if mode == "deleted" {
+				if err := resources.Delete(context.Background(), root.Name, metav1.DeleteOptions{}); err != nil {
+					t.Fatal(err)
+				}
+				client.ClearActions()
+			}
+			writes := rootPublicationUpdates(t, client, root, live, mode, gvr)
+			_, err := ApplyRootCR(context.Background(), resources, desired, root, options)
+			valid := mode == "apply" || mode == "dry-run" || mode == "retry"
+			if valid && err != nil || !valid && err == nil {
+				t.Fatalf("error=%v valid=%v", err, valid)
+			}
+			expected := 0
+			if mode == "apply" || mode == "dry-run" || mode == "conflict-replaced" {
+				expected = 1
+			}
+			if *writes != expected {
+				t.Fatalf("writes=%d want=%d", *writes, expected)
+			}
+			for _, action := range client.Actions() {
+				if action.GetVerb() != "get" && action.GetVerb() != "update" {
+					t.Fatalf("unexpected mutation: %s", action.GetVerb())
+				}
+			}
+		})
+	}
+}
+
+func rootPublicationFixture(mode string) (sohaapi.ManifestRootResource, *unstructured.Unstructured, *unstructured.Unstructured, metav1.PatchOptions) {
+	root := sohaapi.ManifestRootResource{APIVersion: "unknown.example/v1", Kind: "Database", Namespace: "team", Name: "db", UID: "uid-1", Generation: 2, CrdName: "databases.unknown.example"}
+	live := &unstructured.Unstructured{Object: map[string]any{"apiVersion": root.APIVersion, "kind": root.Kind, "metadata": map[string]any{"namespace": root.Namespace, "name": root.Name, "uid": root.UID, "resourceVersion": "12", "generation": int64(2)}, "spec": map[string]any{"size": int64(1)}}}
+	desired := &unstructured.Unstructured{Object: map[string]any{"apiVersion": root.APIVersion, "kind": root.Kind, "metadata": map[string]any{"namespace": root.Namespace, "name": root.Name}, "spec": map[string]any{"size": int64(2)}}}
+	force := mode == "force"
+	options := metav1.PatchOptions{FieldManager: "opensoha-manifest/binding", Force: &force}
+	switch mode {
+	case "dry-run":
+		options.DryRun = []string{metav1.DryRunAll}
+	case "retry":
+		live.Object["spec"] = desired.Object["spec"]
+		live.SetGeneration(3)
+	case "replaced":
+		live.SetUID("uid-2")
+	case "changed":
+		live.SetGeneration(3)
+	case "deleting":
+		now := metav1.Now()
+		live.SetDeletionTimestamp(&now)
+	case "helm":
+		live.SetLabels(map[string]string{"app.kubernetes.io/managed-by": "Helm"})
+	case "git":
+		live.SetManagedFields([]metav1.ManagedFieldsEntry{{Manager: "argocd-controller"}})
+	case "controller":
+		yes := true
+		live.SetOwnerReferences([]metav1.OwnerReference{{UID: "parent", Controller: &yes}})
+	case "status":
+		desired.Object["status"] = map[string]any{"ready": true}
+	case "finalizer":
+		desired.SetFinalizers([]string{"operator/hold"})
+	}
+	return root, live, desired, options
+}
+
+func rootPublicationUpdates(t *testing.T, client *fake.FakeDynamicClient, root sohaapi.ManifestRootResource, live *unstructured.Unstructured, mode string, gvr schema.GroupVersionResource) *int {
+	t.Helper()
+	writes := new(int)
+	client.PrependReactor("update", "databases", func(action ktesting.Action) (bool, runtime.Object, error) {
+		*writes++
+		update, ok := action.(ktesting.UpdateActionImpl)
+		if !ok {
+			t.Fatalf("expected update action, got %T", action)
+		}
+		object, ok := update.GetObject().(*unstructured.Unstructured)
+		if !ok {
+			t.Fatalf("expected unstructured root, got %T", update.GetObject())
+		}
+		if mode == "dry-run" && len(update.GetUpdateOptions().DryRun) != 1 {
+			t.Fatal("preflight performed a real update")
+		}
+		body := object.Object
+		if string(object.GetUID()) != root.UID || object.GetResourceVersion() != "12" || !reflect.DeepEqual(object.Object["status"], live.Object["status"]) {
+			t.Fatalf("unsafe patch: %v", body)
+		}
+		if mode == "conflict-replaced" {
+			replaced := live.DeepCopy()
+			replaced.SetUID("uid-2")
+			if err := client.Tracker().Update(gvr, replaced, "team"); err != nil {
+				t.Fatal(err)
+			}
+			return true, nil, apierrors.NewConflict(gvr.GroupResource(), root.Name, nil)
+		}
+		return true, object, nil
+	})
+	return writes
+}