refactor(controller): rework annotation mechanics

api/v1alpha1/annotations.go

@@ -1,13 +1,27 @@
 package v1alpha1
 
-const (
-	AnnotationKeyDescription = "kargo.akuity.io/description"
+import "encoding/json"
 
+const (
+	// AnnotationKeyRefresh is an annotation key that can be set on a resource
+	// to trigger a refresh of the resource by the controller. The value of the
+	// annotation is interpreted as a token, and any change to the value of the
+	// annotation should trigger a reconciliation of the resource.
 	AnnotationKeyRefresh = "kargo.akuity.io/refresh"
 
-	AnnotationKeyReverify      = "kargo.akuity.io/reverify"
-	AnnotationKeyReverifyActor = "kargo.akuity.io/reverify-actor"
-	AnnotationKeyAbort         = "kargo.akuity.io/abort"
+	// AnnotationKeyReverify is an annotation key that can be set on a Stage
+	// resource to trigger the re-verification of its Freight. The value of the
+	// annotation should either be the ID of the verification to be reverified,
+	// or a JSON object with the structure of the VerificationRequest.
+	AnnotationKeyReverify = "kargo.akuity.io/reverify"
+
+	// AnnotationKeyAbort is an annotation key that can be set on a Stage
+	// resource to abort the verification of its Freight. The value of the
+	// annotation must be set to the identifier of the verification to be
+	// aborted.
+	AnnotationKeyAbort = "kargo.akuity.io/abort"
+
+	AnnotationKeyDescription = "kargo.akuity.io/description"
 
 	AnnotationKeyOIDCEmails   = "rbac.kargo.akuity.io/email"
 	AnnotationKeyOIDCGroups   = "rbac.kargo.akuity.io/groups"
@@ -29,3 +43,66 @@
 	AnnotationKeyEventVerificationStartTime  = "event.kargo.akuity.io/verification-start-time"
 	AnnotationKeyEventVerificationFinishTime = "event.kargo.akuity.io/verification-finish-time"
 )
+
+// RefreshAnnotationValue returns the value of the AnnotationKeyRefresh
+// annotation which can be used to detect changes, and a boolean indicating
+// whether the annotation was present.
+func RefreshAnnotationValue(annotations map[string]string) (string, bool) {
+	requested, ok := annotations[AnnotationKeyRefresh]
+	return requested, ok
+}
+
+// ReverifyAnnotationValue returns the value of the AnnotationKeyReverify
+// annotation, which can be used to determine whether the verification of a
+// Freight should be rerun, and a boolean indicating whether the annotation was
+// present.
+//
+// If the value of the annotation is a valid JSON object, it is unmarshalled
+// into a VerificationRequest struct. Otherwise, the value is treated as the ID
+// of the verification to be reverified and set as the ID field of the returned
+// VerificationRequest.
+func ReverifyAnnotationValue(annotations map[string]string) (*VerificationRequest, bool) {
+	requested, ok := annotations[AnnotationKeyReverify]
+	if !ok {
+		return nil, ok
+	}
+	var vr VerificationRequest
+	if b := []byte(requested); json.Valid(b) {
+		if err := json.Unmarshal(b, &vr); err != nil {
+			return nil, false
+		}
+	} else {
+		vr.ID = requested
+	}
+	if !vr.HasID() {
+		return nil, false
+	}
+	return &vr, ok
+}
+
+// AbortAnnotationValue returns the value of the AnnotationKeyAbort annotation
+// which can be used to abort the verification of a Freight, and a boolean
+// indicating whether the annotation was present.
+//
+// If the value of the annotation is a valid JSON object, it is unmarshalled
+// into a VerificationRequest struct. Otherwise, the value is treated as the ID
+// of the verification to be aborted and set as the ID field of the returned
+// VerificationRequest.
+func AbortAnnotationValue(annotations map[string]string) (*VerificationRequest, bool) {
+	requested, ok := annotations[AnnotationKeyAbort]
+	if !ok {
+		return nil, ok
+	}
+	var vr VerificationRequest
+	if b := []byte(requested); json.Valid(b) {
+		if err := json.Unmarshal(b, &vr); err != nil {
+			return nil, false
+		}
+	} else {
+		vr.ID = requested
+	}
+	if !vr.HasID() {
+		return nil, false
+	}
+	return &vr, ok
+}

api/v1alpha1/annotations_test.go

@@ -0,0 +1,95 @@
+package v1alpha1
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestRefreshAnnotationValue(t *testing.T) {
+	t.Run("has refresh annotation", func(t *testing.T) {
+		result, ok := RefreshAnnotationValue(map[string]string{
+			AnnotationKeyRefresh: "foo",
+		})
+		require.True(t, ok)
+		require.Equal(t, "foo", result)
+	})
+
+	t.Run("does not have refresh annotation", func(t *testing.T) {
+		result, ok := RefreshAnnotationValue(nil)
+		require.False(t, ok)
+		require.Empty(t, result)
+	})
+
+	t.Run("has refresh annotation with empty value", func(t *testing.T) {
+		result, ok := RefreshAnnotationValue(map[string]string{
+			AnnotationKeyRefresh: "",
+		})
+		require.True(t, ok)
+		require.Empty(t, result)
+	})
+}
+
+func TestReverifyAnnotationValue(t *testing.T) {
+	t.Run("has reverify annotation with valid JSON", func(t *testing.T) {
+		result, ok := ReverifyAnnotationValue(map[string]string{
+			AnnotationKeyReverify: `{"id":"foo"}`,
+		})
+		require.True(t, ok)
+		require.Equal(t, "foo", result.ID)
+	})
+
+	t.Run("has reverify annotation with ID string", func(t *testing.T) {
+		result, ok := ReverifyAnnotationValue(map[string]string{
+			AnnotationKeyReverify: "foo",
+		})
+		require.True(t, ok)
+		require.Equal(t, "foo", result.ID)
+	})
+
+	t.Run("does not have reverify annotation", func(t *testing.T) {
+		result, ok := ReverifyAnnotationValue(nil)
+		require.False(t, ok)
+		require.Nil(t, result)
+	})
+
+	t.Run("has reverify annotation with empty ID", func(t *testing.T) {
+		result, ok := ReverifyAnnotationValue(map[string]string{
+			AnnotationKeyAbort: "",
+		})
+		require.False(t, ok)
+		require.Nil(t, result)
+	})
+}
+
+func TestAbortAnnotationValue(t *testing.T) {
+	t.Run("has abort annotation with valid JSON", func(t *testing.T) {
+		result, ok := AbortAnnotationValue(map[string]string{
+			AnnotationKeyAbort: `{"id":"foo"}`,
+		})
+		require.True(t, ok)
+		require.Equal(t, "foo", result.ID)
+	})
+
+	t.Run("has abort annotation with ID string", func(t *testing.T) {
+		result, ok := AbortAnnotationValue(map[string]string{
+			AnnotationKeyAbort: "foo",
+		})
+		require.True(t, ok)
+		require.Equal(t, "foo", result.ID)
+	})
+
+	t.Run("does not have abort annotation", func(t *testing.T) {
+		result, ok := AbortAnnotationValue(nil)
+		require.False(t, ok)
+		require.Nil(t, result)
+	})
+
+	t.Run("has abort annotation with empty ID", func(t *testing.T) {
+		result, ok := AbortAnnotationValue(map[string]string{
+			AnnotationKeyAbort: "",
+		})
+		require.False(t, ok)
+		require.Nil(t, result)
+	})
+}