Skip to content

feat(policy): add narrow attribute read API protos and generated code#3634

Merged
alkalescent merged 1 commit into
mainfrom
DSPX-2541-attribute-read-apis
Jul 1, 2026
Merged

feat(policy): add narrow attribute read API protos and generated code#3634
alkalescent merged 1 commit into
mainfrom
DSPX-2541-attribute-read-apis

Conversation

@alkalescent

@alkalescent alkalescent commented Jun 17, 2026

Copy link
Copy Markdown
Contributor

Proposed Changes

Proto and generated-code portion of the narrow attribute read APIs, split out so the heavy service implementation lands separately and protocol/go releases cleanly.

Adds two RPCs to AttributesService:

  • GetKeyMappingsByFqns — per value FQN: the attribute rule and effective KAS keys (value > definition > namespace precedence), for client-side key splits.
  • GetEntitleableAttributesByFqns — per value FQN: rule, value id, the definition's ordered value FQNs (hierarchy), and value-level subject mappings, for server-side decisioning.

Includes the .proto, regenerated protocol/go, gRPC/OpenAPI docs, and the generated sdkconnect client wrapper. The wrapper and the AttributesServiceClient test mocks ship here because CI regenerates them from the proto (make connect-wrapper-generate) and requires a clean tree. Server methods are Unimplemented stubs.

PR stack

Replaces the previous combined PR per review (separate proto/generated from service logic). Merge order:

  1. this PR — proto + generated + docs + sdkconnect wrapper
  2. feat(policy): implement narrow attribute read APIs #3697 — service implementation (DB, SQL, real handlers, tests)

Follow-up feature branch: switch the SDK granter to consume GetKeyMappingsByFqns and add an xtest proving key-split parity with the previous SDK.

@gemini-code-assist

Copy link
Copy Markdown
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces two purpose-built read RPCs to the attributes service, replacing the broader GetAttributeValuesByFqns for specific caller needs. These changes improve performance and reduce data payload size by providing only the necessary fields for client-side key splitting and server-side entitlement resolution. The implementation includes the required protobuf definitions, database queries, service handlers, and test coverage.

Highlights

  • New Attribute Read APIs: Added two new RPCs, GetKeyMappingsByFqns and GetEntitleableAttributesByFqns, to the attributes service to support optimized, narrow-scope data retrieval for client-side key splitting and server-side entitlement decisioning.
  • Database Optimization: Implemented a new lean SQL query getSubjectMappingsByValueFqns to fetch subject mappings in a single roundtrip, avoiding the overhead of full-policy loading.
  • SDK and Testing: Updated the SDK Connect wrapper, regenerated protocol definitions, and added comprehensive integration tests to verify the new API functionality and key resolution logic.
New Features

🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Ignored Files
  • Ignored by pattern: docs/openapi/**/* (1)
    • docs/openapi/policy/attributes/attributes.openapi.yaml
  • Ignored by pattern: protocol/**/* (3)
    • protocol/go/policy/attributes/attributes.pb.go
    • protocol/go/policy/attributes/attributes_grpc.pb.go
    • protocol/go/policy/attributes/attributesconnect/attributes.connect.go
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.


Two new paths for data to flow, Narrow reads to make it go. Keys and rules in tidy sets, Optimized for what it gets.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

@github-actions github-actions Bot added comp:db DB component comp:policy Policy Configuration ( attributes, subject mappings, resource mappings, kas registry) comp:sdk A software development kit, including library, for client applications and inter-service communicati comp:authorization docs Documentation labels Jun 17, 2026

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces two new narrow read APIs to the AttributesService: GetKeyMappingsByFqns (for client-side key split construction) and GetEntitleableAttributesByFqns (for server-side entitlement resolution). These APIs allow fetching targeted policy data without loading the entire policy. The changes include new Protobuf definitions, database query implementations, and comprehensive tests. The review feedback suggests optimizing the SQL query getSubjectMappingsByValueFqns by casting standard_actions and custom_actions to ::jsonb. This enables sqlc to generate these fields as []byte instead of interface{}, allowing the Go code to pass the raw bytes directly to unmarshalAllActionsProto and completely avoid the overhead of json.Marshal.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

Comment thread service/policy/db/queries/subject_mappings.sql Outdated
Comment thread service/policy/db/attribute_fqn.go Outdated
@coderabbitai

coderabbitai Bot commented Jun 17, 2026

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds two new narrow read RPCs on policy.attributes.AttributesService for key mappings and entitleable attributes by value FQN, with matching proto, DB, service, client, test, and documentation updates.

Changes

FQN-based Narrow Read RPCs

Layer / File(s) Summary
API contract and docs
service/policy/attributes/attributes.proto, docs/grpc/index.html, docs/openapi/policy/attributes/attributes.openapi.yaml
Adds GetKeyMappingsByFqns* and GetEntitleableAttributesByFqns* request/response messages, registers both RPCs as NO_SIDE_EFFECTS, and updates the gRPC/OpenAPI docs with the new operations and schemas.
Subject-mapping query and generated accessors
service/policy/db/queries/subject_mappings.sql, service/policy/db/subject_mappings.sql.go
Adds the value-FQN subject-mapping query, generated row type, and query method that return mapping rows filtered by requested value FQNs.
DB client implementation and helpers
service/policy/db/attribute_fqn.go, service/policy/db/attribute_fqn_test.go
Implements key-mapping resolution, entitleable-attribute construction, subject-mapping hydration, effective KAS key selection, and unit tests for key precedence.
Service handler and client wiring
service/policy/attributes/attributes.go, protocol/go/policy/attributes/attributesconnect/attributes.connect.go, sdk/sdkconnect/attributes.go
Adds handler methods, Connect-Go client/server wiring, unimplemented stubs, and SDK wrapper methods for the new RPCs.
Integration tests and mock stubs
service/integration/attributes_test.go, service/authorization/authorization_test_structures.go
Adds integration coverage for key inheritance, entitleable attributes, and hierarchy behavior, plus authorization test stubs for the new RPCs.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant AttributesService
  participant PolicyDBClient
  participant getAttributesByValueFqns
  participant getSubjectMappingsByValueFqns
  participant resolveEffectiveKasKeys

  Client->>AttributesService: GetKeyMappingsByFqns / GetEntitleableAttributesByFqns
  AttributesService->>PolicyDBClient: DB lookup by FQNs
  PolicyDBClient->>getAttributesByValueFqns: resolve attribute/value pairs
  getAttributesByValueFqns-->>PolicyDBClient: resolved pairs
  alt GetKeyMappingsByFqns
    PolicyDBClient->>resolveEffectiveKasKeys: choose effective KAS keys
    resolveEffectiveKasKeys-->>PolicyDBClient: keys per value FQN
  else GetEntitleableAttributesByFqns
    PolicyDBClient->>getSubjectMappingsByValueFqns: fetch value-level subject mappings
    getSubjectMappingsByValueFqns-->>PolicyDBClient: rows per value FQN
  end
  PolicyDBClient-->>AttributesService: response data
  AttributesService-->>Client: RPC response
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Suggested reviewers

  • elizabethhealy

Poem

🐇 Two FQNs hopped in, side by side,
Keys and entitlements now can ride.
The DB hums, the proto sings,
With subject maps and KAS key things.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 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.
Title check ✅ Passed The title accurately summarizes the main change by adding narrow attribute read APIs and generated code, and it is concise and specific.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch DSPX-2541-attribute-read-apis

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.

@github-actions

Copy link
Copy Markdown
Contributor
Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 189.816269ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 101.921655ms

Benchmark Statistics

Name № Requests Avg Duration Min Duration Max Duration

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 695.143802ms
Throughput 143.86 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 43.554474551s
Average Latency 433.711678ms
Throughput 114.80 requests/second

@github-actions

Copy link
Copy Markdown
Contributor
Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 180.434577ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 102.805062ms

Benchmark Statistics

Name № Requests Avg Duration Min Duration Max Duration

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 412.994783ms
Throughput 242.13 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 42.843568377s
Average Latency 426.656636ms
Throughput 116.70 requests/second

@alkalescent alkalescent marked this pull request as ready for review June 17, 2026 20:03
@alkalescent alkalescent requested review from a team as code owners June 17, 2026 20:03
@alkalescent alkalescent enabled auto-merge June 18, 2026 14:48
@jakedoublev

Copy link
Copy Markdown
Contributor

@dmihalcik-virtru Would you mind taking a look as the author of the autoconfigure logic in the SDK today to build key splits? Any thoughts on this new API dedicated to that purpose?

Comment thread service/policy/attributes/attributes.proto Outdated
Comment thread service/policy/attributes/attributes.proto Outdated
@github-actions

Copy link
Copy Markdown
Contributor
Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 158.921111ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 81.72507ms

Benchmark Statistics

Name № Requests Avg Duration Min Duration Max Duration

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 414.387485ms
Throughput 241.32 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 42.54443733s
Average Latency 423.919809ms
Throughput 117.52 requests/second

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@service/integration/attributes_test.go`:
- Around line 1672-1688: The test currently validates that lowFqn exists in
resp.GetFqnEntitleableAttributes() with correct properties, but does not assert
that the map contains only the requested value and no other FQNs. Add an
assertion to verify the length of resp.GetFqnEntitleableAttributes() equals 1 or
add explicit checks that highFqn and midFqn are not present in the map, ensuring
the response does not inadvertently over-return entitleable attributes beyond
what was requested.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: e9a97052-0f55-4a9a-9338-b3656bc84e4c

📥 Commits

Reviewing files that changed from the base of the PR and between 8295bab and f16cd0d.

⛔ Files ignored due to path filters (1)
  • protocol/go/policy/attributes/attributes.pb.go is excluded by !**/*.pb.go
📒 Files selected for processing (6)
  • docs/grpc/index.html
  • docs/openapi/policy/attributes/attributes.openapi.yaml
  • service/integration/attributes_test.go
  • service/policy/attributes/attributes.go
  • service/policy/attributes/attributes.proto
  • service/policy/db/attribute_fqn.go

Comment thread service/integration/attributes_test.go Outdated
@alkalescent alkalescent force-pushed the DSPX-2541-attribute-read-apis branch from f16cd0d to 6adaa3e Compare June 23, 2026 19:34
@github-actions

Copy link
Copy Markdown
Contributor
Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 191.336638ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 105.34313ms

Benchmark Statistics

Name № Requests Avg Duration Min Duration Max Duration

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 441.785226ms
Throughput 226.35 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 45.574077404s
Average Latency 453.455568ms
Throughput 109.71 requests/second

@alkalescent alkalescent force-pushed the DSPX-2541-attribute-read-apis branch from fe9860f to 10d625d Compare June 30, 2026 21:33
@alkalescent alkalescent changed the title feat(policy): DSPX-2541 add narrow attribute read APIs feat(policy): add narrow attribute read API protos and generated code Jun 30, 2026
@alkalescent alkalescent force-pushed the DSPX-2541-attribute-read-apis branch from 10d625d to a40a66d Compare June 30, 2026 21:38
@github-actions

Copy link
Copy Markdown
Contributor

@github-actions

Copy link
Copy Markdown
Contributor
Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 207.916382ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 124.009601ms

Benchmark Statistics

Name № Requests Avg Duration Min Duration Max Duration

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 420.504237ms
Throughput 237.81 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 46.78618451s
Average Latency 465.933264ms
Throughput 106.87 requests/second

@github-actions

Copy link
Copy Markdown
Contributor
Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 222.278964ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 107.256011ms

Benchmark Statistics

Name № Requests Avg Duration Min Duration Max Duration

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 433.769876ms
Throughput 230.54 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 47.335069888s
Average Latency 471.806349ms
Throughput 105.63 requests/second

Add GetKeyMappingsByFqns and GetEntitleableAttributesByFqns RPCs to the
attributes service proto, with regenerated protocol/go, gRPC/OpenAPI docs, and
the generated sdkconnect client wrapper. The connect-wrapper and the
AttributesServiceClient test mocks ship here because CI regenerates them from
the proto and requires a clean tree. Server methods are Unimplemented stubs; the
DB-backed implementation and the SDK granter adoption land in follow-up PRs.

Signed-off-by: Krish Suchak <[email protected]>
@alkalescent alkalescent force-pushed the DSPX-2541-attribute-read-apis branch from a40a66d to 3239ed4 Compare June 30, 2026 22:41
@github-actions

Copy link
Copy Markdown
Contributor
Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 221.944525ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric Value
Approved Decision Requests 1000
Denied Decision Requests 0
Total Time 120.080957ms

Benchmark Statistics

Name № Requests Avg Duration Min Duration Max Duration

Bulk Benchmark Results

Metric Value
Total Decrypts 100
Successful Decrypts 100
Failed Decrypts 0
Total Time 430.931085ms
Throughput 232.06 requests/second

TDF3 Benchmark Results:

Metric Value
Total Requests 5000
Successful Requests 5000
Failed Requests 0
Concurrent Requests 50
Total Time 46.65088539s
Average Latency 463.91755ms
Throughput 107.18 requests/second

@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Govulncheck found vulnerabilities ⚠️

The following modules have known vulnerabilities:

  • examples
  • otdfctl
  • sdk
  • service
  • lib/fixtures
  • tests-bdd

See the workflow run for details.

Comment thread service/policy/attributes/attributes.go
@alkalescent alkalescent added this pull request to the merge queue Jul 1, 2026
Merged via the queue into main with commit 5726720 Jul 1, 2026
45 checks passed
@alkalescent alkalescent deleted the DSPX-2541-attribute-read-apis branch July 1, 2026 17:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp:authorization comp:db DB component comp:policy Policy Configuration ( attributes, subject mappings, resource mappings, kas registry) comp:sdk A software development kit, including library, for client applications and inter-service communicati docs Documentation size/l

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants