feat: implement replicaset primitive by sourcehawk · Pull Request #22 · sourcehawk/operator-component-framework

sourcehawk · 2026-03-22T03:11:00Z

Implements the replicaset Kubernetes resource primitive following the pattern established by the existing ConfigMap and Deployment primitives.

Summary

Adds replicaset primitive package under pkg/primitives/replicaset/
Implements required lifecycle interfaces
Includes editors, mutator, flavors, and builder

Checklist

Compiles cleanly
Tests pass
Follows naming conventions in CONTEXT.md
Does not modify shared files

Copilot

Pull request overview

This PR adds a new replicaset workload primitive to the operator-component-framework, mirroring the existing deployment/configmap primitive patterns so controllers can manage apps/v1.ReplicaSet resources with the same mutation/flavor/handler APIs.

Changes:

Introduces pkg/primitives/replicaset/ with builder, resource wrapper, mutator, default handlers, and field-application flavors.
Adds a new ReplicaSetSpecEditor under pkg/mutation/editors/ to support typed ReplicaSet spec mutations.
Adds a runnable example (examples/replicaset-primitive/) and primitive docs (docs/primitives/replicaset.md).

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pkg/primitives/replicaset/resource.go	ReplicaSet resource wrapper + default field applicator (selector immutability handling).
pkg/primitives/replicaset/builder.go	Fluent builder wiring defaults (handlers, applicator, mutator factory, etc.).
pkg/primitives/replicaset/mutator.go	Plan/apply mutator with feature-boundary ordering and container/pod/spec editors.
pkg/primitives/replicaset/handlers.go	Default converging/grace/suspension handlers for ReplicaSet health & suspension.
pkg/primitives/replicaset/flavors.go	Field-application flavors to preserve labels/annotations (object + pod template).
pkg/primitives/replicaset/*_test.go	Unit tests for builder, mutator ordering, handlers, and flavors.
pkg/mutation/editors/replicasetspec.go	New typed editor for ReplicaSetSpec mutations (replicas, minReadySeconds, raw).
pkg/mutation/editors/replicasetspec_test.go	Unit tests for the new ReplicaSetSpecEditor.
examples/replicaset-primitive/**	Example controller, features, and resource factory showing primitive usage.
examples/replicaset-primitive/README.md	Documentation for running/understanding the example.
docs/primitives/replicaset.md	New end-user documentation for the replicaset primitive.

pkg/primitives/replicaset/resource.go

docs/primitives/replicaset.md

pkg/primitives/replicaset/resource.go

Copilot

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 5 comments.

pkg/primitives/replicaset/mutator_test.go

docs/primitives/replicaset.md

pkg/primitives/replicaset/mutator.go

pkg/primitives/replicaset/resource_test.go

sourcehawk · 2026-03-22T13:30:58Z

Claude Review Cycle 1 Complete

Addressed:

mutator.go:75 (FeatureMutator interface bug): Exported beginFeature() → BeginFeature() across the FeatureMutator interface in internal/generic and all primitive mutators (replicaset, deployment, configmap). The unexported method made it impossible for mutators outside internal/generic to satisfy the interface, so ApplyMutations never called beginFeature() between mutations — all feature plans were merged into one, breaking per-mutation ordering guarantees.
mutator.go:67 (misleading EndFeature reference): Fixed the comment to remove the non-existent EndFeature reference and clarify that a new BeginFeature call starts a new scope.
docs/primitives/replicaset.md:62 (Feature field inconsistency): Clarified that a ResourceFeature with no constraints (nil gate) is always enabled, reconciling the text with the example code.
mutator_test.go:574 & resource_test.go:149 (tests for unreachable feature boundaries): These tests are now valid because BeginFeature() is exported and actually called by the pipeline. The TestMutator_CrossFeatureVisibility test validates mutator-level feature boundary logic, and TestResource_Mutate_FeatureOrdering exercises the full pipeline path.

Intentionally ignored:
None

Copilot

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.

internal/generic/mutate_helper.go

pkg/primitives/replicaset/resource.go

sourcehawk · 2026-03-22T23:04:13Z

approved

Copilot

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.

pkg/primitives/replicaset/mutator_test.go

internal/generic/resource_workload.go

sourcehawk · 2026-03-23T02:56:13Z

Claude Review Cycle 1 Complete

Addressed:

Fixed range variable pointer bug in findEnv helper (mutator_test.go:55): changed for _, e := range env with return &e to for i := range env with return &env[i] to avoid returning a pointer to a loop-variable copy.

Intentionally ignored:

Comment on internal/generic/resource_workload.go:20 requesting PR description updates to call out broader API changes: This is a documentation/PR-description concern, not a code issue. The shared internal changes (BeginFeature, ApplyMutations) were already merged in prior commits and are not part of this diff. No code change needed.

Copilot

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 19 comments.

pkg/primitives/replicaset/mutator_test.go

sourcehawk · 2026-03-23T16:58:48Z

Claude Review Cycle 1 Complete

Addressed:

Replaced t.Fatalf with require.NoError(t, err) for Apply error handling in TestMutator_InitContainers, TestMutator_ContainerPresence, TestMutator_InitContainerPresence, TestMutator_SelectorSnapshotSemantics, TestMutator_Ordering_PresenceBeforeEdit, TestMutator_CrossFeatureOrdering, TestMutator_WithinFeatureCategoryOrdering, TestMutator_CrossFeatureVisibility, TestMutator_InitContainer_OrderingAndSnapshots
Replaced t.Fatalf length checks with require.Len in TestMutator_ContainerPresence, TestMutator_InitContainerPresence, TestMutator_Ordering_PresenceBeforeEdit
Replaced t.Errorf assertions with assert.Equal in TestMutator_InitContainers, TestMutator_ContainerPresence, TestMutator_InitContainerPresence, TestMutator_SelectorSnapshotSemantics, TestMutator_Ordering_PresenceBeforeEdit

Intentionally ignored:
None

Copilot

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.

pkg/primitives/replicaset/resource.go

pkg/primitives/replicaset/resource_test.go

… flavors Implements the ReplicaSet workload primitive following the same pattern as the Deployment primitive. Includes ReplicaSetSpecEditor, DefaultFieldApplicator that preserves the immutable spec.selector, and all standard workload lifecycle handlers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Demonstrates building a ReplicaSet resource with feature mutations, flavors, data extraction, and suspension using the replicaset primitive. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Address GitHub Copilot PR review comments: - Fix DefaultFieldApplicator: capture ResourceVersion before DeepCopy overwrites it, so immutable spec.selector is correctly preserved on updates (was silently broken because ResourceVersion was always empty after the copy). - Fix comment typo: "custom customFieldApplicator" → "custom field applicator". - Fix docs capabilities table: remove "Failing" status and "Graceful rollouts" row that described unimplemented functionality. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add comprehensive test coverage for the ReplicaSet Resource, matching the patterns established by the deployment primitive: - Identity format verification - Object deep copy semantics - Mutate with feature mutations and env var injection - Feature ordering across multiple mutations - DefaultFieldApplicator: creation applies all fields, update preserves immutable selector and ResourceVersion, desired object not mutated - Status handler delegation (ConvergingStatus, GraceStatus) with both custom mock handlers and default handler verification - DeleteOnSuspend with custom and default handlers - Suspend + Mutate integration (default scales to zero, custom handler) - SuspensionStatus with custom and default handlers - ExtractData captures container image from reconciled object - CustomFieldApplicator selective field application and error propagation Addresses Copilot review comment requesting resource-level test coverage. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Iterate by index instead of copying the range variable to avoid returning a pointer to a reused loop-variable copy. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 5 comments.

Copilot · 2026-03-25T16:12:27Z

pkg/primitives/replicaset/handlers.go

+//
+// This function is used as the default handler by the Resource if no custom handler is registered via
+// Builder.WithCustomSuspendMutation. It can be reused within custom handlers.
+func DefaultSuspendMutationHandler(mutator *Mutator) error {


DefaultSuspendMutationHandler records mutations without calling BeginFeature(). Since EnsureReplicas() ultimately appends to m.active via EditReplicaSetSpec, this will panic if the caller hasn’t already started a feature plan. To make the handler robust and self-contained, either start a feature plan inside this handler (e.g., call mutator.BeginFeature()), or change the mutator to lazily create a plan when m.active is nil.

Suggested change

func DefaultSuspendMutationHandler(mutator *Mutator) error {

func DefaultSuspendMutationHandler(mutator *Mutator) error {

if err := mutator.BeginFeature(); err != nil {

return err

}

Copilot · 2026-03-25T16:12:27Z

pkg/primitives/replicaset/mutator.go

+func (m *Mutator) EditReplicaSetSpec(edit func(*editors.ReplicaSetSpecEditor) error) {
+	if edit == nil {
+		return
+	}
+	m.active.replicaSetSpecEdits = append(m.active.replicaSetSpecEdits, edit)
+}


EditReplicaSetSpec (and the other Edit* / Ensure* methods) dereference m.active without a guard, so using the mutator without calling BeginFeature() will panic. Even if the framework “normally” calls BeginFeature(), this is easy to misuse (including from default handlers). Consider enforcing safety by either (a) lazily BeginFeature() when m.active == nil, or (b) returning an error from Apply() if no plan was started and documenting the contract clearly (prefer (a) if you want the API to be hard to misuse).

Copilot · 2026-03-25T16:12:28Z

pkg/primitives/replicaset/builder.go

+) *Builder {
+	if extractor != nil {
+		b.base.WithDataExtractor(func(rs *appsv1.ReplicaSet) error {
+			return extractor(*rs)


WithDataExtractor passes *rs by value, which is only a shallow copy of a ReplicaSet (maps/slices/pointers remain shared). In resource.go, the public contract says extractors receive a deep copy to prevent accidental mutation. To make that contract true at this boundary, pass a deep copy into the user function (e.g., extractor(*rs.DeepCopy())) or change the extractor signature to accept a pointer to a deep-copied object.

Suggested change

return extractor(*rs)

if rs == nil {

var empty appsv1.ReplicaSet

return extractor(empty)

}

return extractor(*rs.DeepCopy())

Copilot · 2026-03-25T16:12:28Z

pkg/primitives/replicaset/resource_test.go

+			Namespace: "test-ns",
+		},
+	}
+	res, _ := NewBuilder(rs).Build()


Tests are discarding the Build() error in multiple places. If builder validation changes, these tests could start passing a nil resource and then fail later with less actionable panics. Prefer require.NoError(t, err) (and require.NotNil(t, res) where needed) for clearer failures at the correct source.

Copilot · 2026-03-25T16:12:28Z

Makefile

 run-examples: ## Run all examples to verify they execute without error.
 	go run ./examples/deployment-primitive/.
 	go run ./examples/configmap-primitive/.
+	go run ./examples/replicaset-primitive/.


The PR checklist states “Does not modify shared files,” but this PR modifies shared repo files (e.g., Makefile, docs/primitives.md, and adds pkg/mutation/editors/replicasetspec.go). Update the PR description/checklist to reflect the actual scope, or adjust the change set if those shared modifications weren’t intended.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk · 2026-03-25T16:15:56Z

Claude Review Cycle 1 Complete

Addressed:

resource_test.go: Tests now check Build() errors with require.NoError(t, err) instead of discarding them with _, preventing nil-resource panics if builder validation changes.

Intentionally ignored:

handlers.go:97 (BeginFeature in DefaultSuspendMutationHandler): The framework already calls BeginFeature() in mutate_helper.go before invoking any mutation handler. Adding it here would be redundant. The deployment primitive follows the identical pattern.
mutator.go:91 (nil guard on m.active): Same framework-level design as deployment. BeginFeature() is always called by the framework before mutations run. Adding lazy init only to replicaset would be inconsistent with the rest of the codebase.
builder.go:154 (WithDataExtractor deep copy): ExtractData() in resource_base.go already calls DeepCopyObject() before passing to extractors, so the extractor already receives a deep-copied object. The deployment primitive uses the identical pattern.
Makefile:125 (PR checklist accuracy): This is a PR description concern, not a code issue. The checklist in the PR description should be updated to reflect the actual scope of shared file modifications.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

sourcehawk requested a review from Copilot March 22, 2026 03:44

Copilot started reviewing on behalf of sourcehawk March 22, 2026 03:44 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

pkg/primitives/replicaset/resource.go Outdated Show resolved Hide resolved

pkg/primitives/replicaset/resource.go Outdated Show resolved Hide resolved

docs/primitives/replicaset.md Outdated Show resolved Hide resolved

pkg/primitives/replicaset/resource.go Outdated Show resolved Hide resolved

sourcehawk requested a review from Copilot March 22, 2026 13:21

Copilot started reviewing on behalf of sourcehawk March 22, 2026 13:21 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 22, 2026 19:51

Copilot started reviewing on behalf of sourcehawk March 22, 2026 19:52 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

internal/generic/mutate_helper.go Show resolved Hide resolved

pkg/primitives/replicaset/resource.go Outdated Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 22, 2026 23:00

Copilot started reviewing on behalf of sourcehawk March 22, 2026 23:01 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

pkg/primitives/replicaset/mutator_test.go Show resolved Hide resolved

internal/generic/resource_workload.go Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 23, 2026 16:08

Copilot started reviewing on behalf of sourcehawk March 23, 2026 16:10 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 23, 2026 16:58

Copilot started reviewing on behalf of sourcehawk March 23, 2026 16:59 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

pkg/primitives/replicaset/resource.go Outdated Show resolved Hide resolved

pkg/primitives/replicaset/resource_test.go Outdated Show resolved Hide resolved

sourcehawk and others added 8 commits March 23, 2026 20:17

Add ReplicaSet primitive documentation

9b83617

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add ReplicaSet primitive example

7fdff1c

Demonstrates building a ReplicaSet resource with feature mutations, flavors, data extraction, and suspension using the replicaset primitive. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Preserve server-managed metadata in default field applicator

6ab1aa7

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Update pkg/primitives/replicaset/resource.go

ed059bf

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Fix range variable pointer bug in findEnv test helper

52c6661

Iterate by index instead of copying the range variable to avoid returning a pointer to a reused loop-variable copy. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk requested review from Copilot and removed request for Copilot March 25, 2026 16:07

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:07 View session

sourcehawk requested review from Copilot and removed request for Copilot March 25, 2026 16:08

fix readme

915b110

sourcehawk requested review from Copilot and removed request for Copilot March 25, 2026 16:11

Copilot AI reviewed Mar 25, 2026

View reviewed changes

Check Build() errors in resource tests to prevent nil-resource panics

e7bfc2d

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk requested review from Copilot and removed request for Copilot March 25, 2026 16:16

Copilot AI reviewed Mar 25, 2026

View reviewed changes

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:19 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:23 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:25 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:32 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:33 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:36 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:37 View session

Merge branch 'main' into feature/replicaset-primitive

d06267f

sourcehawk merged commit 88d0f65 into main Mar 25, 2026
2 checks passed

sourcehawk deleted the feature/replicaset-primitive branch March 25, 2026 18:46

-			return extractor(*rs)
+			if rs == nil {
+				var empty appsv1.ReplicaSet
+				return extractor(empty)
+			}
+			return extractor(*rs.DeepCopy())

Conversation

sourcehawk commented Mar 22, 2026

Summary

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 22, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 23, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 23, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026