feat: implement transitive skipping and deferred dependency gating for conditional resources

Author: Mark Altmann

builtins/builtins.go

@@ -485,18 +485,21 @@ func readyToProto(r resource.Ready) fnv1.Ready {
 }
 
 const (
-	CompositeReadyConditionType = "ComposedResourcesReady"
-	compositeReadyReasonPending = "PendingConditionalResources"
+	CompositeReadyConditionType    = "ComposedResourcesReady"
+	compositeReadyReasonPending    = "PendingConditionalResources"
+	compositeReadyReasonWaitingDep = "WaitingForDependencies"
+	compositeReadyReasonComposite  = "CompositeNotReady"
 )
 
 // ApplyCompositeReady sets rsp.Desired.Composite.Ready. An explicit
-// set_composite_ready() call wins; otherwise any non-optional Resource(when=False)
-// skip flips Ready to False and emits a ComposedResourcesReady=False condition.
-// With neither, Ready is left UNSPECIFIED.
+// set_composite_ready() call wins. Otherwise any non-optional
+// Resource(when=False) skip OR sequencer-deferred resource flips Ready to
+// False and emits a ComposedResourcesReady=False condition. With none of
+// these, Ready is left UNSPECIFIED.
 func ApplyCompositeReady(rsp *fnv1.RunFunctionResponse, collector *Collector, cc *ConditionCollector) {
-	override, skips := collector.compositeReadyState()
+	override, skips, defers := collector.compositeReadyState()
 
-	if !override.Set && len(skips) == 0 {
+	if !override.Set && len(skips) == 0 && len(defers) == 0 {
 		return
 	}
 
@@ -531,6 +534,37 @@ func ApplyCompositeReady(rsp *fnv1.RunFunctionResponse, collector *Collector, cc
 
 	rsp.Desired.Composite.Ready = fnv1.Ready_READY_FALSE
 
+	reason, message := buildGatingConditionFields(skips, defers)
+	cc.AddCondition(CollectedCondition{
+		Type:    CompositeReadyConditionType,
+		Status:  "False",
+		Reason:  reason,
+		Message: message,
+		Target:  "CompositeAndClaim",
+	})
+}
+
+// buildGatingConditionFields composes the reason and message for the
+// auto-emitted ComposedResourcesReady=False condition based on which gating
+// categories are populated.
+func buildGatingConditionFields(skips []GatingSkip, defers []GatingDefer) (string, string) {
+	skipPart := formatGatingSkips(skips)
+	deferPart := formatGatingDefers(defers)
+
+	switch {
+	case len(skips) > 0 && len(defers) > 0:
+		return compositeReadyReasonComposite, skipPart + "; " + deferPart
+	case len(skips) > 0:
+		return compositeReadyReasonPending, skipPart
+	default:
+		return compositeReadyReasonWaitingDep, deferPart
+	}
+}
+
+func formatGatingSkips(skips []GatingSkip) string {
+	if len(skips) == 0 {
+		return ""
+	}
 	parts := make([]string, 0, len(skips))
 	for _, s := range skips {
 		if s.Reason != "" {
@@ -539,11 +573,20 @@ func ApplyCompositeReady(rsp *fnv1.RunFunctionResponse, collector *Collector, cc
 			parts = append(parts, fmt.Sprintf("%q", s.Name))
 		}
 	}
-	cc.AddCondition(CollectedCondition{
-		Type:    CompositeReadyConditionType,
-		Status:  "False",
-		Reason:  compositeReadyReasonPending,
-		Message: fmt.Sprintf("Pending resources: %s", strings.Join(parts, "; ")),
-		Target:  "CompositeAndClaim",
-	})
+	return "Pending resources: " + strings.Join(parts, "; ")
+}
+
+func formatGatingDefers(defers []GatingDefer) string {
+	if len(defers) == 0 {
+		return ""
+	}
+	parts := make([]string, 0, len(defers))
+	for _, d := range defers {
+		if d.Reason != "" {
+			parts = append(parts, fmt.Sprintf("%q (%s)", d.Name, d.Reason))
+		} else {
+			parts = append(parts, fmt.Sprintf("%q", d.Name))
+		}
+	}
+	return "Waiting on dependencies: " + strings.Join(parts, "; ")
 }

builtins/builtins_test.go

@@ -2029,3 +2029,88 @@ func TestApplyCompositeReady_PreservesExistingComposite(t *testing.T) {
 		t.Error("Composite.Resource was clobbered by ApplyCompositeReady")
 	}
 }
+
+func TestApplyCompositeReady_DefersOnly(t *testing.T) {
+	cc := NewConditionCollector()
+	c := NewCollector(cc, "test.star", nil, nil)
+
+	c.AddGatingDefers([]GatingDefer{
+		{Name: "app", Reason: `waiting for "db" to have Ready=True`},
+	})
+
+	rsp := &fnv1.RunFunctionResponse{}
+	ApplyCompositeReady(rsp, c, cc)
+
+	if got := rsp.Desired.Composite.Ready; got != fnv1.Ready_READY_FALSE {
+		t.Errorf("Composite.Ready = %v, want READY_FALSE", got)
+	}
+	conds := cc.Conditions()
+	if len(conds) != 1 {
+		t.Fatalf("expected 1 condition, got %d", len(conds))
+	}
+	if conds[0].Type != CompositeReadyConditionType ||
+		conds[0].Status != "False" ||
+		conds[0].Reason != "WaitingForDependencies" {
+		t.Errorf("condition = %+v, want WaitingForDependencies/False", conds[0])
+	}
+	if !strings.Contains(conds[0].Message, "app") ||
+		!strings.Contains(conds[0].Message, "Waiting on dependencies") {
+		t.Errorf("condition message = %q, want it to mention 'app' under 'Waiting on dependencies'", conds[0].Message)
+	}
+}
+
+func TestApplyCompositeReady_SkipsAndDefers(t *testing.T) {
+	cc := NewConditionCollector()
+	c := NewCollector(cc, "test.star", nil, nil)
+
+	c.recordSkip("backup", "feature pending", true)
+	c.AddGatingDefers([]GatingDefer{
+		{Name: "app", Reason: `waiting for "db" to have Ready=True`},
+	})
+
+	rsp := &fnv1.RunFunctionResponse{}
+	ApplyCompositeReady(rsp, c, cc)
+
+	if got := rsp.Desired.Composite.Ready; got != fnv1.Ready_READY_FALSE {
+		t.Errorf("Composite.Ready = %v, want READY_FALSE", got)
+	}
+	conds := cc.Conditions()
+	if len(conds) != 1 {
+		t.Fatalf("expected 1 aggregated condition, got %d", len(conds))
+	}
+	if conds[0].Reason != "CompositeNotReady" {
+		t.Errorf("Reason = %q, want CompositeNotReady when both skips and defers are present", conds[0].Reason)
+	}
+	msg := conds[0].Message
+	if !strings.Contains(msg, "Pending resources") || !strings.Contains(msg, "backup") {
+		t.Errorf("message = %q, want to include 'Pending resources' and 'backup'", msg)
+	}
+	if !strings.Contains(msg, "Waiting on dependencies") || !strings.Contains(msg, "app") {
+		t.Errorf("message = %q, want to include 'Waiting on dependencies' and 'app'", msg)
+	}
+}
+
+func TestApplyCompositeReady_OverrideStillWinsOverDefers(t *testing.T) {
+	cc := NewConditionCollector()
+	c := NewCollector(cc, "test.star", nil, nil)
+
+	c.AddGatingDefers([]GatingDefer{{Name: "app", Reason: "waiting"}})
+
+	thread := new(starlark.Thread)
+	_, err := starlark.Call(thread, c.SetCompositeReadyBuiltin(), starlark.Tuple{
+		starlark.True,
+	}, nil)
+	if err != nil {
+		t.Fatalf("set_composite_ready() error: %v", err)
+	}
+
+	rsp := &fnv1.RunFunctionResponse{}
+	ApplyCompositeReady(rsp, c, cc)
+
+	if got := rsp.Desired.Composite.Ready; got != fnv1.Ready_READY_TRUE {
+		t.Errorf("Composite.Ready = %v, want READY_TRUE (override wins over defers)", got)
+	}
+	if got := cc.Conditions(); len(got) != 0 {
+		t.Errorf("expected no conditions (override True with no reason), got %+v", got)
+	}
+}