- Avoid *OrDie. Use type-aware functinos.

- Avoid panic style error handling

Author: yuwenma

go/fn/doc.go

@@ -15,17 +15,17 @@
 /*
 Package fn provides the SDK to write KRM functions.
 
-Before you start
+# Before you start
 
 This fn SDK requires some basic KRM function Specification knowledge. To make the best usage of your time, we recommend
 you to be familiar with "ResourceList" before moving forward.
 
-  The KRM Function Specification, or "ResourceList", defines the standards of the inter-process communication between
-  the orchestrator (i.e. kpt CLI) and functions.
+	The KRM Function Specification, or "ResourceList", defines the standards of the inter-process communication between
+	the orchestrator (i.e. kpt CLI) and functions.
 
 See KRM Function Specification reference in https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md
 
-KRM Function
+# KRM Function
 
 A KRM function can mutate and/or validate Kubernetes resources in a ResourceList.
 
@@ -37,21 +37,21 @@ Read more about how to use KRM functions in https://kpt.dev/book/04-using-functi
 Read more about how to develop a KRM function in https://kpt.dev/book/05-developing-functions/
 
 A general workflow is:
-  1. Reads the "ResourceList" object from STDIN.
-  2. Gets the function configs from the "ResourceList.FunctionConfig".
-  3. Mutate or validate the Kubernetes YAML resources from the "ResourceList.Items" field with the function configs.
-  4. Writes the modified "ResourceList" to STDOUT.
-  5. Write function message to "ResourceList.Results" with severity "Info", "Warning" or "Error"
+ 1. Reads the "ResourceList" object from STDIN.
+ 2. Gets the function configs from the "ResourceList.FunctionConfig".
+ 3. Mutate or validate the Kubernetes YAML resources from the "ResourceList.Items" field with the function configs.
+ 4. Writes the modified "ResourceList" to STDOUT.
+ 5. Write function message to "ResourceList.Results" with severity "Info", "Warning" or "Error"
 
-KubeObject
+# KubeObject
 
 The KubeObject is the basic unit to perform operations on KRM resources.
 
 In the "AsMain", both "Items" and "FunctionConfig"
 are converted to the KubeObject(s).
 
 If you are familiar with unstructured.Unstructured, using KubeObject is as simple as using unstructured.Unstructured.
-You can call function like `NestedStringOrDie` `SetNestedStringMap`, etc.
+You can call function like `NestedString` `SetNestedStringMap`, etc.
 
 Except that KubeObject will not have pass-in interface arguments, nor will return an interface.
 Instead, you shall treat each KubeObject field (slice, or non-string map）as SubObject.
@@ -65,14 +65,13 @@ SubObject.NestedInt64("replicas")
 Besides unstructured style, another way to use KubeObject is to purely work on the KubeObject/SubObject by calling
 "GetMap", "GetSlice", "UpsertMap" which expects the return to be SubObject(s) pointer.
 
-AsMain
+# AsMain
 
 "AsMain" is the main entrypoint. In most cases, you only need to provide the mutator or validation logic and have AsMain
 handles the ResourceList parsing, KRM resource field type detection, read from STDIN and write to STDOUT.
 
 "AsMain" accepts a struct that either implement the ResourceListProcessor interface or Runner interface.
 
 See github.com/GoogleContainerTools/kpt-functions-sdk/go/fn/examples for detailed usage.
-
 */
 package fn

go/fn/errors.go

@@ -19,45 +19,15 @@ import (
 	"strings"
 )
 
+const pathDelimitor = "."
+
 // ErrMissingFnConfig raises error if a required functionConfig is missing.
 type ErrMissingFnConfig struct{}
 
 func (ErrMissingFnConfig) Error() string {
 	return "unable to find the functionConfig in the resourceList"
 }
 
-// errKubeObjectFields raises if the KubeObject operation panics.
-type errKubeObjectFields struct {
-	obj    *KubeObject
-	fields []string
-}
-
-func (e *errKubeObjectFields) Error() string {
-	return fmt.Sprintf("Resource(apiVersion=%v, kind=%v, Name=%v) has unmatched field type: `%v",
-		e.obj.GetAPIVersion(), e.obj.GetKind(), e.obj.GetName(), strings.Join(e.fields, "/"))
-}
-
-// errSubObjectFields raises if the SubObject operation panics.
-type errSubObjectFields struct {
-	fields []string
-}
-
-func (e *errSubObjectFields) Error() string {
-	return fmt.Sprintf("SubObject has unmatched field type: `%v", strings.Join(e.fields, "/"))
-}
-
-type errResultEnd struct {
-	obj     *KubeObject
-	message string
-}
-
-func (e *errResultEnd) Error() string {
-	if e.obj != nil {
-		return fmt.Sprintf("function is terminated by %v: %v", e.obj.ShortString(), e.message)
-	}
-	return fmt.Sprintf("function is terminated: %v", e.message)
-}
-
 type ErrAttemptToTouchUpstreamIdentifier struct{}
 
 func (ErrAttemptToTouchUpstreamIdentifier) Error() string {
@@ -71,3 +41,20 @@ type ErrInternalAnnotation struct {
 func (e *ErrInternalAnnotation) Error() string {
 	return e.Message
 }
+func NewErrUnmatchedField(obj SubObject, fields []string, dt any) *ErrUnmatchedField {
+	relativefields := strings.Join(fields, pathDelimitor)
+	obj.fieldpath += pathDelimitor + relativefields
+	return &ErrUnmatchedField{
+		SubObject: &obj, DataType: fmt.Sprintf("%T", dt),
+	}
+}
+
+type ErrUnmatchedField struct {
+	SubObject *SubObject
+	DataType  string
+}
+
+func (e *ErrUnmatchedField) Error() string {
+	return fmt.Sprintf("Resource(apiVersion=%v, kind=%v) has unmatched field type %q in fieldpath %v",
+		e.SubObject.parentGVK.GroupVersion(), e.SubObject.parentGVK.Kind, e.DataType, e.SubObject.fieldpath)
+}

go/fn/examples/example_filter_GVK_test.go

@@ -34,9 +34,9 @@ func updateReplicas(rl *fn.ResourceList) (bool, error) {
 		return false, fn.ErrMissingFnConfig{}
 	}
 	var replicas int
-	rl.FunctionConfig.GetOrDie(&replicas, "replicas")
+	rl.FunctionConfig.NestedResource(&replicas, "replicas")
 	for i := range rl.Items.Where(fn.IsGVK("apps", "v1", "Deployment")) {
-		rl.Items[i].SetOrDie(replicas, "spec", "replicas")
+		rl.Items[i].SetNestedField(replicas, "spec", "replicas")
 	}
 	return true, nil
 }

go/fn/examples/example_generator_test.go

@@ -41,8 +41,8 @@ func generate(rl *fn.ResourceList) (bool, error) {
 		return false, fn.ErrMissingFnConfig{}
 	}
 
-	revision := rl.FunctionConfig.NestedStringOrDie("data", "revision")
-	id := rl.FunctionConfig.NestedStringOrDie("data", "id")
+	revision, _, _ := rl.FunctionConfig.NestedString("data", "revision")
+	id, _, _ := rl.FunctionConfig.NestedString("data", "id")
 	js, err := fetchDashboard(revision, id)
 	if err != nil {
 		return false, fmt.Errorf("fetch dashboard: %v", err)

go/fn/examples/example_kubeobject_test.go

@@ -29,18 +29,18 @@ func Example_kubeObjectMutatePrimitiveField() {
 	replicas := spec.GetInt("replicas")
 	// mutate the replicas variable
 
-	spec.SetNestedIntOrDie(int(replicas))
+	spec.SetNestedInt(int(replicas))
 }
 
 func Example_kubeObjectMutatePrimitiveSlice() {
-	finalizers := deployment.NestedStringSliceOrDie("metadata", "finalizers")
+	finalizers, _, _ := deployment.NestedStringSlice("metadata", "finalizers")
 	// mutate the finalizers slice
 
-	deployment.SetNestedStringSliceOrDie(finalizers, "metadata", "finalizers")
+	deployment.SetNestedStringSlice(finalizers, "metadata", "finalizers")
 }
 
 func Example_kubeObjectMutatePrimitiveMap() {
-	data := configMap.NestedStringMapOrDie("data")
+	data, _, _ := configMap.NestedStringMap("data")
 	// mutate the data map
 
 	err := deployment.SetNestedStringMap(data, "data")
@@ -52,8 +52,8 @@ func Example_kubeObjectMutateStrongTypedField() {
 	var newPodTemplate corev1.PodTemplate
 	curPodTemplate := configMap.GetMap("spec").GetMap("template")
 	// Assign the current PodTemplate value to newPodTemplate
-	// Use AsOrDie to AsMain handles the errors.
-	curPodTemplate.AsOrDie(&newPodTemplate)
+	// Use As to AsMain handles the errors.
+	curPodTemplate.As(&newPodTemplate)
 	// mutate the newPodTemplate object
 	err := deployment.SetNestedField(newPodTemplate, "spec", "template")
 	if err != nil { /* do something */
@@ -62,7 +62,7 @@ func Example_kubeObjectMutateStrongTypedField() {
 
 func Example_kubeObjectMutateStrongTypedSlice() {
 	var containers []corev1.Container
-	found, err := deployment.Get(&containers, "spec", "template", "spec", "containers")
+	found, err := deployment.NestedResource(&containers, "spec", "template", "spec", "containers")
 	if err != nil { /* do something */
 	}
 	if !found { /* do something */

go/fn/examples/example_logger_injector_test.go

@@ -41,7 +41,7 @@ func injectLogger(rl *fn.ResourceList) (bool, error) {
 	}
 	for i, obj := range rl.Items.Where(hasDesiredGVK) {
 		var containers []corev1.Container
-		obj.GetOrDie(&containers, "spec", "template", "spec", "containers")
+		obj.NestedResource(&containers, "spec", "template", "spec", "containers")
 		foundTargetContainer := false
 		for j, container := range containers {
 			if container.Name == li.ContainerName {
@@ -57,7 +57,7 @@ func injectLogger(rl *fn.ResourceList) (bool, error) {
 			}
 			containers = append(containers, c)
 		}
-		rl.Items[i].SetOrDie(containers, "spec", "template", "spec", "containers")
+		rl.Items[i].SetNestedField(containers, "spec", "template", "spec", "containers")
 	}
 	return true, nil
 }

go/fn/examples/example_read_field_test.go

@@ -31,13 +31,13 @@ func Example_aReadField() {
 func readField(rl *fn.ResourceList) (bool, error) {
 	for _, obj := range rl.Items.Where(fn.IsGVK("apps", "v1", "Deployment")) {
 		// Style 1: like using unstrucuted.Unstructured, get/set the value from field paths*
-		replicas := obj.NestedInt64OrDie("spec", "replicas")
+		replicas, _, _ := obj.NestedInt64("spec", "replicas")
 		fn.Logf("replicas is %v\n", replicas)
-		paused := obj.NestedBoolOrDie("spec", "paused")
+		paused, _, _ := obj.NestedBool("spec", "paused")
 		fn.Logf("paused is %v\n", paused)
 		// Update strategy from Recreate to RollingUpdate.
-		if strategy := obj.NestedStringOrDie("spec", "strategy", "type"); strategy == "Recreate" {
-			obj.SetNestedStringOrDie("RollingUpdate", "spec", "strategy", "type")
+		if strategy, _, _ := obj.NestedString("spec", "strategy", "type"); strategy == "Recreate" {
+			obj.SetNestedString("RollingUpdate", "spec", "strategy", "type")
 		}
 
 		// Style 2: operate each resource layer via `GetMap`
@@ -46,7 +46,7 @@ func readField(rl *fn.ResourceList) (bool, error) {
 		fn.Logf("replicas is %v\n", replicas)
 		nodeSelector := spec.GetMap("template").GetMap("spec").GetMap("nodeSelector")
 		if nodeSelector.GetString("disktype") != "ssd" {
-			nodeSelector.SetNestedStringOrDie("ssd", "disktype")
+			nodeSelector.SetNestedString("ssd", "disktype")
 		}
 	}
 	return true, nil

go/fn/examples/example_read_functionConfig_test.go

@@ -32,7 +32,7 @@ func Example_bReadFunctionConfig() {
 
 func readFunctionConfig(rl *fn.ResourceList) (bool, error) {
 	var sr SetReplicas
-	rl.FunctionConfig.AsOrDie(&sr)
+	rl.FunctionConfig.As(&sr)
 	fn.Logf("desired replicas is %v\n", sr.DesiredReplicas)
 	return true, nil
 }

go/fn/examples/example_set_field_test.go

@@ -32,7 +32,7 @@ func setField(rl *fn.ResourceList) (bool, error) {
 	for _, obj := range rl.Items {
 		if obj.GetAPIVersion() == "apps/v1" && obj.GetKind() == "Deployment" {
 			replicas := 10
-			obj.SetOrDie(&replicas, "spec", "replicas")
+			obj.SetNestedField(&replicas, "spec", "replicas")
 		}
 	}
 	return true, nil

go/fn/examples/example_validator_test.go

@@ -32,7 +32,7 @@ func validator(rl *fn.ResourceList) (bool, error) {
 	var results fn.Results
 	for _, obj := range rl.Items.Where(hasDesiredGVK) {
 		var runAsNonRoot bool
-		obj.GetOrDie(&runAsNonRoot, "spec", "template", "spec", "securityContext", "runAsNonRoot")
+		obj.NestedResource(&runAsNonRoot, "spec", "template", "spec", "securityContext", "runAsNonRoot")
 		if !runAsNonRoot {
 			results = append(results, fn.ConfigObjectResult("`spec.template.spec.securityContext.runAsNonRoot` must be set to true", obj, fn.Error))
 		}

go/fn/internal/maphelpers.go

@@ -16,8 +16,20 @@ package internal
 
 import (
 	"fmt"
+
+	"sigs.k8s.io/kustomize/kyaml/yaml"
 )
 
+func (o *MapVariant) GetRNode(fields ...string) (*yaml.RNode, bool, error) {
+	rn := &yaml.RNode{}
+	val, found, err := o.GetNestedValue(fields...)
+	if err != nil || !found {
+		return nil, found, err
+	}
+	rn.SetYNode(val.Node())
+	return rn, found, err
+}
+
 func (o *MapVariant) GetNestedValue(fields ...string) (variant, bool, error) {
 	current := o
 	n := len(fields)