Skip to content

docs(postgres): document direct-policy semantics of user search aggregates#1699

Merged
rohilsurana merged 1 commit into
mainfrom
search-aggregates-document-divergence
Jun 12, 2026
Merged

docs(postgres): document direct-policy semantics of user search aggregates#1699
rohilsurana merged 1 commit into
mainfrom
search-aggregates-document-divergence

Conversation

@rohilsurana

@rohilsurana rohilsurana commented Jun 12, 2026

Copy link
Copy Markdown
Member

Summary

SearchUserProjects / SearchUserOrganizations (admin search aggregates) return only resources the principal holds a direct policy on. The membership listing path (ListProjectsByUser etc.) additionally expands group-held policies and org-level inheritance — so an org admin with no direct project policies sees every org project in listings but zero in search.

This divergence is pre-existing and became visible once the listing semantics were made explicit in the membership package. After review, the decision is to keep both behaviors as-is and document them:

  • the search aggregates answer "what is this principal explicitly granted" — the right semantics for an admin auditing direct grants
  • the membership path answers "what can this principal access" — the right semantics for end-user listings

Mirroring membership's 3-way inheritance union into the aggregate SQL would add significant complexity for semantics that aren't clearly wanted in admin search; narrowing the listing path would regress end-user behavior.

Changes

Doc comments on UserProjectsRepository.buildBaseQuery and UserOrgsRepository.buildBaseQuery explaining the intentional divergence and warning against "fixing" one side to match the other without a product decision. No functional changes.

Test plan

  • go build ./... and postgres repo tests pass (comment-only change)

@vercel

vercel Bot commented Jun 12, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
frontier Ready Ready Preview, Comment Jun 12, 2026 9:46am

@coderabbitai

coderabbitai Bot commented Jun 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: bbadcf52-0b39-46e6-a724-411b54100f36

📥 Commits

Reviewing files that changed from the base of the PR and between ad53ea6 and d22d05c.

📒 Files selected for processing (2)
  • internal/store/postgres/user_orgs_repository.go
  • internal/store/postgres/user_projects_repository.go
📝 Walkthrough

Summary by CodeRabbit

  • Documentation
    • Enhanced internal documentation for repository query methods to clarify policy-level filtering behavior and intended scope differences.

Walkthrough

This PR adds clarifying documentation comments to two repository query methods. buildBaseQuery in the user organizations repository and buildBaseQuery in the user projects repository are documented to explain their intentionally narrower semantics: they return only direct org-level or project-level policy grants, deliberately excluding group-held and inheritance-based expansion that occurs in the broader membership listing paths.

Changes

Policy Query Method Documentation

Layer / File(s) Summary
buildBaseQuery documentation clarification
internal/store/postgres/user_orgs_repository.go, internal/store/postgres/user_projects_repository.go		 Multi-line comments added to buildBaseQuery in both repositories explaining that each method returns only direct policy grants (org-level or project-level) and intentionally diverges from broader membership listing paths.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

  • raystack/frontier#1648: Both PRs adjust documentation comments above buildBaseQuery in user_projects_repository.go to clarify the "direct policy only" semantics versus broader membership-based listing.

Suggested reviewers

  • whoAbhishekSah
🚥 Pre-merge checks | ✅ 2
✅ Passed checks (2 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coveralls

coveralls commented Jun 12, 2026

Copy link
Copy Markdown

Coverage Report for CI Build 27408055809

Coverage remained the same at 43.285%

Details

  • Coverage remained the same as the base build.
  • Patch coverage: No coverable lines changed in this PR.
  • No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

Coverage Stats

Coverage Status
Relevant Lines: 37154
Covered Lines: 16082
Line Coverage: 43.28%
Coverage Strength: 12.3 hits per line
💛 - Coveralls

@rohilsurana rohilsurana merged commit 1652e7b into main Jun 12, 2026
8 checks passed
@rohilsurana rohilsurana deleted the search-aggregates-document-divergence branch June 12, 2026 10:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@AmanGIT07 AmanGIT07 AmanGIT07 approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@rohilsurana @coveralls @AmanGIT07