feat: implement pvc primitive by sourcehawk · Pull Request #34 · sourcehawk/operator-component-framework

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

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

Summary

Adds pvc primitive package under pkg/primitives/pvc/
Implements required lifecycle interfaces
Includes editors, mutator, flavors, and builder
Adds shared PVCSpecEditor under pkg/mutation/editors/
Updates docs/primitives.md to include PVC in the built-in primitives table

Checklist

Compiles cleanly
Tests pass
Follows naming conventions in CONTEXT.md

Copilot

Pull request overview

Implements a new pvc primitive (PersistentVolumeClaim) that plugs into the framework’s integration-resource lifecycle, including typed mutation/editing support, default handlers, flavors, docs, and a runnable example.

Changes:

Added pkg/primitives/pvc/ (resource, builder, mutator, handlers, flavors) with unit tests.
Added a shared typed editor PVCSpecEditor under pkg/mutation/editors/ with tests.
Added a dedicated pvc-primitive example and new documentation page docs/primitives/pvc.md.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pkg/primitives/pvc/resource.go	Adds PVC integration Resource wrapper + default field applicator (immutable-field preservation).
pkg/primitives/pvc/mutator.go	Adds PVC mutator with plan/apply pattern and typed spec/meta edits.
pkg/primitives/pvc/mutator_test.go	Unit tests for mutator behavior and ordering.
pkg/primitives/pvc/handlers.go	Default operational + suspension handlers for PVCs.
pkg/primitives/pvc/handlers_test.go	Unit tests for default handlers.
pkg/primitives/pvc/flavors.go	PVC flavors for preserving labels/annotations.
pkg/primitives/pvc/flavors_test.go	Unit tests for flavors + builder integration check.
pkg/primitives/pvc/builder.go	Fluent builder for PVC primitive configuration.
pkg/primitives/pvc/builder_test.go	Unit tests for builder configuration/validation wiring.
pkg/mutation/editors/pvcspec.go	Adds shared PVCSpecEditor for typed PVC spec mutations.
pkg/mutation/editors/pvcspec_test.go	Unit tests for PVCSpecEditor.
examples/pvc-primitive/resources/pvc.go	Example resource factory using pvc.Builder + mutations/flavors/extractor.
examples/pvc-primitive/README.md	Documentation for running/understanding the PVC example.
examples/pvc-primitive/main.go	Runnable fake-client example demonstrating versioning/suspension flows.
examples/pvc-primitive/features/mutations.go	Example feature-gated PVC mutations.
examples/pvc-primitive/app/owner.go	Re-export of shared ExampleApp types for the example.
examples/pvc-primitive/app/controller.go	Example controller wiring the PVC resource into a Component.
docs/primitives/pvc.md	Adds primitive documentation for PVC.

docs/primitives/pvc.md

pkg/primitives/pvc/resource.go

pkg/mutation/editors/pvcspec.go

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

pkg/mutation/editors/pvcspec.go

sourcehawk · 2026-03-22T13:27:05Z

Claude Review Cycle 1 Complete

Addressed:
None

Intentionally ignored:

pvcspec.go line 6 (PR description/checklist mismatch): This comment is about PR metadata, not code. The PVCSpecEditor is a new file added to pkg/mutation/editors/ — it extends the shared editors package but does not modify any existing shared files. Adding a new editor alongside the primitive it supports is the intended pattern (consistent with how other primitives work). The PR description could be clarified to note this addition, but no code change is warranted and splitting into a separate PR would lose the cohesion of the feature.

Copilot

Pull request overview

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

docs/primitives/pvc.md

pkg/primitives/pvc/mutator.go

sourcehawk · 2026-03-23T02:57:12Z

Claude Review Cycle 1 Complete

Addressed:

Added PVC primitive entry to the Built-in Primitives table in docs/primitives.md so users can discover the PVC primitive documentation from the main primitives page.
Merged latest changes from main into the feature branch.

Intentionally ignored:

Double pipe separator comment (pvc.md line 15): The capabilities table already uses single | separators, consistent with configmap.md. No double pipes exist in the file.
Mutator beginFeature export comment (mutator.go line 45): The unexported beginFeature() method is the same pattern used by all other primitives (deployment, configmap). The FeatureMutator interface in internal/generic uses an unexported method by design. Changing this would require modifying shared infrastructure and affects all primitives, not just PVC. This is a pre-existing architectural pattern, not a PVC-specific issue.

Copilot

Pull request overview

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

pkg/primitives/pvc/resource.go

pkg/primitives/pvc/resource_test.go

pkg/primitives/pvc/mutator.go

docs/primitives/pvc.md

docs/primitives.md

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

Claude Review Cycle 1 Complete

Addressed:

resource.go:32 — PreserveStatus was already added in a prior commit; confirmed present and working
resource_test.go:136 — TestDefaultFieldApplicator_PreservesStatus regression test was already added in a prior commit; confirmed present and passing
docs/primitives/pvc.md:134 — Updated mutation ordering docs to accurately state that PVC mutations are applied in a single deterministic sequence without per-feature boundaries

Intentionally ignored:

mutator.go:51 (FeatureMutator unexported method) — Valid observation, but this is a pre-existing framework-level issue affecting all primitives (deployment, configmap, pvc), not specific to this PR. The unexported beginFeature() in generic.FeatureMutator prevents any external package from satisfying the interface. Should be addressed in a separate framework PR.
docs/primitives.md:134 (PR checklist accuracy) — This is about PR description metadata, not a code issue. The PR description can be updated separately if needed.

Copilot

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

Copilot · 2026-03-23T17:02:55Z

pkg/primitives/pvc/mutator.go

+	"k8s.io/apimachinery/pkg/api/resource"
+)
+
+// Mutation defines a mutation that is applied to a pvc Mutator


Spelling/terminology: "a pvc Mutator" should be "a PVC Mutator" (PVC is an acronym) to match naming used elsewhere in the repo and in the rest of this package's GoDoc.

Suggested change

// Mutation defines a mutation that is applied to a pvc Mutator

// Mutation defines a mutation that is applied to a PVC Mutator

Typed editor providing SetStorageRequest, SetAccessModes, SetStorageClassName, SetVolumeMode, SetVolumeName, and Raw() escape hatch. Follows the existing editor patterns (DeploymentSpecEditor, ContainerEditor, etc.). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Implements PersistentVolumeClaim as an Integration primitive with: - Builder with fluent API for mutations, flavors, status handlers - Mutator with plan-and-apply pattern (metadata edits, spec edits) - DefaultFieldApplicator preserving immutable fields (accessModes, storageClassName, volumeMode, volumeName) on existing PVCs - DefaultOperationalStatusHandler (Bound/Pending/Lost → status mapping) - DefaultSuspendMutationHandler (no-op, PVCs have no runtime state) - DefaultSuspensionStatusHandler (always Suspended) - DefaultDeleteOnSuspendHandler (false, preserve data) - PreserveCurrentLabels and PreserveCurrentAnnotations flavors Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Covers capabilities, building, default field application (immutable field preservation), mutations (boolean-gated, version-gated), internal ordering, editors (PVCSpecEditor, ObjectMetaEditor), convenience methods, flavors, status handlers, and usage guidance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Demonstrates PVC builder with version labels, storage annotations, conditional large-storage expansion, label/annotation flavors, data extraction, and suspension. Follows the configmap and deployment example patterns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Address Copilot review comment: DefaultFieldApplicator had no test coverage for its immutable field preservation logic. Add tests validating that: - New PVCs (empty ResourceVersion) use all fields from desired - Existing PVCs preserve immutable fields (accessModes, storageClassName, volumeMode, volumeName) from current - Mutable fields (e.g. storage requests) come from desired Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

…inFeature Aligns with the fix applied to the deployment and configmap primitives, preventing an empty leading feature plan when the mutator helper calls beginFeature(). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add generic.PreserveStatus call in DefaultFieldApplicator to prevent status clobbering on update - Add TestDefaultFieldApplicator_PreservesStatus regression test - Update pvc.md to accurately describe mutation ordering (no per-feature boundaries due to unexported FeatureMutator interface) - Update DefaultFieldApplicator doc comment to mention Status preservation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Align with upstream change in main that exported BeginFeature() on the FeatureMutator interface. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

pkg/primitives/pvc/resource.go

Add integration tests for the Resource type covering Identity, Object deep copy, Mutate with mutations and field flavors, ConvergingStatus for Bound/Pending/Lost phases, default suspension behavior, and data extraction. These tests validate the generic.IntegrationResource plumbing end-to-end, matching coverage provided by other primitives. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk · 2026-03-24T02:14:39Z

Claude Review Cycle 1 Complete

Addressed:

Added resource-level behavioral tests to pkg/primitives/pvc/resource_test.go covering: Identity, Object deep copy, Mutate with a mutation and a field flavor, feature ordering, ConvergingStatus for Bound/Pending/Lost phases, DeleteOnSuspend (default=false), Suspend + SuspensionStatus (reports Suspended), and ExtractData. These mirror the patterns in the deployment primitive's resource_test.go.

Intentionally ignored:
None

Copilot

Pull request overview

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

Align PVC mutator with deployment/configmap: NewMutator no longer creates an initial feature plan. BeginFeature must be called before registering mutations. Updates all tests accordingly and adds constructor/feature-plan invariant tests. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The framework now uses Server-Side Apply instead of ctrl.CreateOrUpdate, so field applicators and flavors are no longer needed. This removes DefaultFieldApplicator, WithCustomFieldApplicator, WithFieldApplicationFlavor, the FieldApplicationFlavor type, flavors.go, flavors_test.go, and updates all tests to use the Object()-then-Mutate() pattern. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Copilot · 2026-03-25T14:15:40Z

docs/primitives.md

 ## Built-in Primitives

-| Primitive                   | Category | Documentation                             |
-| --------------------------- | -------- | ----------------------------------------- |
-| `pkg/primitives/deployment` | Workload | [deployment.md](primitives/deployment.md) |
-| `pkg/primitives/configmap`  | Static   | [configmap.md](primitives/configmap.md)   |
+| Primitive                   | Category    | Documentation                             |
+| --------------------------- | ----------- | ----------------------------------------- |
+| `pkg/primitives/deployment` | Workload    | [deployment.md](primitives/deployment.md) |
+| `pkg/primitives/configmap`  | Static      | [configmap.md](primitives/configmap.md)   |
+| `pkg/primitives/pvc`        | Integration | [pvc.md](primitives/pvc.md)               |


PR description mentions the PVC primitive "includes ... flavors", but there doesn’t appear to be any flavor API/types added under pkg/primitives/pvc (or in the generic builders) in this change. Either implement the flavor functionality for PVC or update the PR description/checklist to match what was actually delivered.

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

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

Copilot AI reviewed Mar 22, 2026

View reviewed changes

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

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

pkg/mutation/editors/pvcspec.go Show resolved Hide resolved

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

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

Copilot AI reviewed Mar 22, 2026

View reviewed changes

pkg/mutation/editors/pvcspec.go Show resolved Hide resolved

sourcehawk force-pushed the feature/pvc-primitive branch from 1789aed to 2d07ac1 Compare March 23, 2026 00:49

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

Copilot started reviewing on behalf of sourcehawk March 23, 2026 00:50 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

docs/primitives/pvc.md Show resolved Hide resolved

docs/primitives/pvc.md Show resolved Hide resolved

pkg/primitives/pvc/mutator.go Outdated Show resolved Hide resolved

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

Copilot started reviewing on behalf of sourcehawk March 23, 2026 16:06 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

sourcehawk and others added 10 commits March 23, 2026 20:16

preserve server-managed metadata in default field applicator

ffb1d90

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

add PVC primitive to built-in primitives documentation table

4e7b2bb

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

fix(pvc): export BeginFeature to match FeatureMutator interface

dc9f30a

Align with upstream change in main that exported BeginFeature() on the FeatureMutator interface. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk force-pushed the feature/pvc-primitive branch from afbb0a0 to dc9f30a Compare March 23, 2026 21:38

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 02:08

Copilot started reviewing on behalf of sourcehawk March 24, 2026 02:10 View session

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 02:11

Copilot AI reviewed Mar 24, 2026

View reviewed changes

pkg/primitives/pvc/resource.go Show resolved Hide resolved

Copilot started reviewing on behalf of sourcehawk March 24, 2026 02:13 View session

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 02:15

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

Copilot AI reviewed Mar 24, 2026

View reviewed changes

Copilot started reviewing on behalf of sourcehawk March 24, 2026 02:18 View session

Copilot started reviewing on behalf of sourcehawk March 24, 2026 02:21 View session

sourcehawk and others added 4 commits March 24, 2026 17:51

Merge remote-tracking branch 'origin/main' into feature/pvc-primitive

1c649fe

Merge remote-tracking branch 'origin/main' into feature/pvc-primitive

85c7299

Copilot AI review requested due to automatic review settings March 25, 2026 14:10

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

Copilot AI reviewed Mar 25, 2026

View reviewed changes

	// Mutation defines a mutation that is applied to a pvc Mutator
	// Mutation defines a mutation that is applied to a PVC Mutator

Conversation

sourcehawk commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

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!

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!

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!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

sourcehawk commented Mar 24, 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sourcehawk commented Mar 22, 2026 •

edited

Loading