access/update a single file via the prr api

[dgyorgy-nokia]

[access/update a single file via the prr api]

---

Description

• What changed: Limit the scope of Get and Update PRR calls to a single file.
• Why it’s needed: Prevent to download all the unneccessary content in case of large packages for better performance.
• How it works: Get or Update individual files on a PackageRevisionResources object instead of always transferring the whole package. On GET, query parameters like ?file=Kptfile are parsed from the resource name and only those paths are returned; on UPDATE, ?partial=true merges the submitted files into the existing package, leaves omitted files unchanged, then runs the usual render pipeline.

---

Related Issue(s)

• Closes/Fixes # PIP - Enable to access a single file via the PackageRevisionResources API (EPIC) #915

---

Type of Change

• Bug fix
• New feature
• Enhancement
• Refactor
• Documentation
• Tests
• Other: ________

---

Checklist

• Code follows project style guidelines
• Self-reviewed changes
• Tests added/updated
• Documentation added/updated
• All tests and gating checks pass

---

AI Disclosure

• I have used AI in the creation of this PR.

If so, please describe how:

• Cursor's grok 4.6 was used to review the changes.

[netlify]

✅ Deploy Preview for kpt-porch ready!

Name	Link
🔨 Latest commit	a12ef56
🔍 Latest deploy log	https://app.netlify.com/projects/kpt-porch/deploys/6a980bea30ec86000891326a
😎 Deploy Preview	https://deploy-preview-1169--kpt-porch.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

🟡 Changes recommended

Confirmed correctness bugs in the new selector/plumbing (notably OCI filtering and partial-update result selection) can lead to empty or overly broad PRR responses and must be fixed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Implements selective GET and partial UPDATE semantics for the PackageRevisionResources (PRR) aggregated API by encoding query parameters in metadata.name, reducing data transferred for large packages.

Changes:

• Add PRR selectors (?file=... for GET; ?partial=true for UPDATE) and plumb them through the API server, engine, and repository backends.
• Update storage backends (git/oci/dbcache) and mocks to support filtered reads and partial updates.
• Add/adjust E2E tests and expand documentation describing the new PRR behaviors.

File summaries

File	Description
test/mockery/mocks/porch/pkg/repository/mock_PackageRevision.go	Update mocks to include GetFilteredResources.
test/mockery/mocks/porch/pkg/engine/mock_CaDEngine.go	Update CaD engine mock signature to accept update selector.
test/mockery/mocks/porch/pkg/cache/dbcache/mock_dbSQLInterface.go	Add mock for ScanTwoTextColumns.
test/e2e/api/advanced_test.go	Add E2E coverage for GET ?file= and UPDATE ?partial=true.
pkg/util/selector/prr_selector.go	New selector parsing/types for PRR GET/UPDATE.
pkg/util/selector/prr_selector_test.go	Unit tests for selector parsing/matching.
pkg/repository/repository.go	Extend PackageRevision interface with GetFilteredResources.
pkg/repository/repository_test.go	Update fake implementation to satisfy interface changes.
pkg/registry/porch/packagerevisionresources.go	Parse selectors from name; use filtered reads; support partial update results.
pkg/registry/porch/packagerevisionresources_test.go	Update tests to expect GetFilteredResources usage.
pkg/externalrepo/oci/oci.go	Use selector-aware LoadResources; add GetFilteredResources.
pkg/externalrepo/oci/loader.go	Add selector-aware tar loading (filtering).
pkg/externalrepo/git/package.go	Add GetFilteredResources; optimize GetKptfile via filtered read.
pkg/externalrepo/git/git.go	Add getFilteredResources implementation.
pkg/externalrepo/fake/packagerevision.go	Add fake GetFilteredResources.
pkg/engine/engine.go	Add partial-merge behavior via selector to UpdatePackageResources.
pkg/engine/engine_test.go	Update tests for new UpdatePackageResources signature.
pkg/cache/dbcache/dbsql.go	Add pgx-optimized ScanTwoTextColumns implementation.
pkg/cache/dbcache/dbreposync_test.go	Update tests for selector-aware resource reads.
pkg/cache/dbcache/dbpackagerevisionsql.go	Thread selector into DB package revision reads.
pkg/cache/dbcache/dbpackagerevisionsql_test.go	Update tests for new DB read signature.
pkg/cache/dbcache/dbpackagerevisionresourcessql.go	Add selector-aware SQL query for resource reads (with fallback path).
pkg/cache/dbcache/dbpackagerevision.go	Add DB-backed GetFilteredResources; refactor PRR object construction.
pkg/cache/dbcache/dbpackagerevision_test.go	Update tests for selector-aware DB reads.
docs/content/en/docs/7_cli_api/api-ref.md	Document PRR filtered GET and partial UPDATE behavior.
docs/content/en/docs/7_cli_api/_index.md	Add PRR selector/partial update notes to API index.
docs/content/en/docs/5_architecture_and_components/porch-apiserver/functionality.md	Document selector parsing and partial update semantics.
docs/content/en/docs/5_architecture_and_components/engine/functionality/task-coordination.md	Document merge step in engine update flow.
docs/content/en/docs/5_architecture_and_components/controllers/packagerevision-controller/interactions.md	Clarify controller flow for partial merges.
docs/content/en/docs/5_architecture_and_components/controllers/packagerevision-controller/functionality/rendering.md	Clarify render triggers for partial merges.
docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/_index.md	Add links to “read selected files” / “partial updates” sections.
docs/content/en/docs/4_tutorials_and_how-tos/working_with_crd_based_packagerevisions/differences.md	Note filtered GET / partial UPDATE works across architectures.
docs/content/en/docs/4_tutorials_and_how-tos/working_with_crd_based_packagerevisions/creating-packages.md	Document how to perform partial updates via PRR.
docs/content/en/docs/2_concepts/package.md	Mention selective read/partial update capabilities.
docs/content/en/docs/11_glossary/_index.md	Glossary updates for PRR selectors/partial updates.
controllers/repositories/pkg/controllers/repository/pkgrevsync_test.go	Update fake package revision for new interface method.

Review details

Suppressed comments (1)

pkg/registry/porch/packagerevisionresources.go:217

• If objInfo.UpdatedObject returns an unexpected type, newObj stays nil and updateValidation (and later code) will panic. Add a default case (or a nil check) to return a BadRequest for unsupported types.

	var newObj *porchapi.PackageRevisionResources
	switch obj := newRuntimeObj.(type) {
	case *porchapi.PackageRevisionResources:
		newObj = obj
	case *porch.PackageRevisionResources: // internal version

• Files reviewed: 36/36 changed files
• Comments generated: 6
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
4 Accepted issues

Measures
0 Security Hotspots
81.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud