Feat: DSPX-2418 add SDK convenience/discovery method documentation#186
Conversation
Summary of ChangesHello @marythought, 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 significantly enhances the developer experience for users of the Go and Java SDKs by introducing comprehensive documentation for new attribute discovery and validation methods. These methods empower developers to proactively manage and verify attributes before data encryption, thereby preventing cryptic runtime errors and improving the robustness of applications interacting with the platform's attribute-based access control. Highlights
🧠 New Feature in Public Preview: You can now enable Memory 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. Changelog
Activity
Using Gemini Code AssistThe 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
Customization To customize 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 Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. 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. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
The pull request introduces new documentation for SDK convenience methods related to attribute discovery and validation in Go and Java. It also updates the troubleshooting guide to reference these new methods. The changes are well-structured and provide clear examples for both languages. The documentation effectively highlights the benefits of using these methods for early error detection.
Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
Add JavaScript (TypeScript) code examples for all four discovery methods alongside the existing Go and Java tabs. Remove the "Go and Java only" caveat now that the JavaScript SDK also supports these methods. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
…add ValidateAttributeValue Update discovery.mdx to reflect the method rename and new semantics: - Rename "ValidateAttributeValue" section → "ValidateAttributeExists" with updated code examples using the new method name in all 3 SDKs. - Add new "ValidateAttributeValue" section documenting the two-argument form that handles both enumerated and dynamic attribute types, with examples for Go, Java, and JavaScript. - Add tip explaining dynamic vs. enumerated attribute behavior. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…and prevention note to all SDKs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Remove invented "dynamic vs enumerated" attribute terminology — the platform has no such concept. The method checks whether a value is in the attribute's registered values list; the rule type (ANY_OF, ALL_OF, HIERARCHY) governs access decisions at decryption time, not value registration. Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
c5f5ca4 to
56d65a1
Compare
…ue with AttributeExists/AttributeValueExists Both methods now return bool, documented with true/false return examples in all three SDK tabs. Updated "Putting It Together" pattern to show the two-step check: AttributeExists then ValidateAttributes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
## Summary - Add five discovery methods directly on the `SDK` class: `listAttributes()`, `validateAttributes()`, `attributeExists()`, `attributeValueExists()`, `getEntityAttributes()` - Add `SDK.AttributeNotFoundException extends SDKException`, thrown when FQNs or attribute values are not found on the platform - Add 26 unit tests in `DiscoveryTest.java` covering all methods and edge cases - docs update: opentdf/docs#186 ## Rationale Addresses GitHub discussion developer feedback. Developers currently work with verbose Connect RPC request/response types through `sdk.getServices().attributes()`. These methods provide ergonomic wrappers that: - Auto-paginate `listAttributes()` with a 1,000-page safety cap to prevent unbounded memory growth from a misbehaving server - Validate FQN format and existence before `createTDF()` so failures happen at encryption time with a clear message rather than at decryption time with a cryptic "resource not found" - Match entity ID in the `GetEntitlements` response to prevent silent wrong-entity attribute returns - Cap `validateAttributes()` at 250 FQNs client-side to match the server limit Matches the API shape and security properties of the Go SDK implementation: opentdf/platform#3082. ## Test plan - [ ] `mvn -pl sdk test -Dtest=DiscoveryTest` — all 26 tests pass - [ ] `mvn -pl sdk test` — no regressions in existing test suite --------- Signed-off-by: Mary Dickson <mary.dickson@virtru.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Summary Adds five convenience discovery methods to the Go SDK's SDK struct, addressing GitHub Discussions [#947](https://github.com/orgs/opentdf/discussions/947) and [#1204](https://github.com/orgs/opentdf/discussions/1204) where developers had no ergonomic way to discover attributes or validate them before encryption. * ListAttributes(ctx, namespace...) — returns all active attributes, auto-paginates * ValidateAttributes(ctx, fqns) — fail-fast batch check that value FQNs exist before CreateTDF; returns ErrAttributeNotFound naming which FQNs are missing * AttributeExists(ctx, fqn) — checks that an attribute exists with any amount of values, bool return * AttributeValueExists(ctx, attributeFqn, value) — checks that an attribute / value combination exists -- bool return; addresses [#2930](https://github.com/orgs/opentdf/discussions/2930) * GetEntityAttributes(ctx, entity) — returns attribute FQNs assigned to a PE/NPE via GetEntitlements * Adds ErrAttributeNotFound sentinel to sdk.go ## Security hardening applied during implementation - Pagination loop in `ListAttributes` capped at 1000 pages to prevent unbounded memory growth from a misbehaving server - `ValidateAttributes` enforces the server's 250-FQN limit client-side for a clear local error - `GetEntityAttributes` matches response entitlements against the requested entity ID rather than blindly returning index 0 ### Checklist - [x] I have added or updated unit tests - [ ] I have added or updated integration tests (if appropriate) - [x] I have added or updated documentation: opentdf/docs#186 ### Testing Instructions - [x] 21 unit tests in `sdk/discovery_test.go` covering all methods, edge cases (empty input, pagination overflow, ID mismatch, service errors, invalid FQN format) - [x] `go test ./sdk/...` passes (pre-existing `auth/oauth` failure is unrelated) - [x] `golangci-lint run ./sdk/...` — no new issues introduced - [x] Docs updated in companion PR against `opentdf/docs` --------- Signed-off-by: Mary Dickson <mary.dickson@virtru.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: dmihalcik-virtru <dmihalcik-virtru@users.noreply.github.com>
|
SDK branches approved and merged! |
dmihalcik-virtru
left a comment
dmihalcik-virtru
left a comment
There was a problem hiding this comment.
What is up with the yaml (openapi) updates?
it's the result of running run npm run update-vendored-yaml, without which the build would not build... but completely unrelated to my changes. thanks for the reminder I was going to look into a better way to handle those, since I hate having unrelated passenger files in a PR. |
## Summary Adds five convenience discovery methods to the Go SDK's SDK struct, addressing GitHub Discussions [#947](https://github.com/orgs/opentdf/discussions/947) and [#1204](https://github.com/orgs/opentdf/discussions/1204) where developers had no ergonomic way to discover attributes or validate them before encryption. * ListAttributes(ctx, namespace...) — returns all active attributes, auto-paginates * ValidateAttributes(ctx, fqns) — fail-fast batch check that value FQNs exist before CreateTDF; returns ErrAttributeNotFound naming which FQNs are missing * AttributeExists(ctx, fqn) — checks that an attribute exists with any amount of values, bool return * AttributeValueExists(ctx, attributeFqn, value) — checks that an attribute / value combination exists -- bool return; addresses [#2930](https://github.com/orgs/opentdf/discussions/2930) * GetEntityAttributes(ctx, entity) — returns attribute FQNs assigned to a PE/NPE via GetEntitlements * Adds ErrAttributeNotFound sentinel to sdk.go ## Security hardening applied during implementation - Pagination loop in `ListAttributes` capped at 1000 pages to prevent unbounded memory growth from a misbehaving server - `ValidateAttributes` enforces the server's 250-FQN limit client-side for a clear local error - `GetEntityAttributes` matches response entitlements against the requested entity ID rather than blindly returning index 0 ### Checklist - [x] I have added or updated unit tests - [ ] I have added or updated integration tests (if appropriate) - [x] I have added or updated documentation: opentdf/docs#186 ### Testing Instructions - [x] 21 unit tests in `sdk/discovery_test.go` covering all methods, edge cases (empty input, pagination overflow, ID mismatch, service errors, invalid FQN format) - [x] `go test ./sdk/...` passes (pre-existing `auth/oauth` failure is unrelated) - [x] `golangci-lint run ./sdk/...` — no new issues introduced - [x] Docs updated in companion PR against `opentdf/docs` --------- Signed-off-by: Mary Dickson <mary.dickson@virtru.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: dmihalcik-virtru <dmihalcik-virtru@users.noreply.github.com>
3 participants
Preview
https://opentdf-docs-preview-dspx-2418.surge.sh/sdks/discovery
Summary
docs/sdks/discovery.mdx) — Documents five conveniencemethods in the Go, Java, and JavaScript SDKs for discovering and validating attributes before
encryption:
ListAttributes— returns all active attributes on the platform with optional namespacefiltering; auto-paginates through all results
ValidateAttributes— checks a list of attribute value FQNs exist before callingCreateTDF, surfacing missing attributes at encryption time rather than decryption time;accepts up to 250 FQNs per call
AttributeExists— boolean lookup -- does an attribute exist? (with any number of values)AttributeValueExists— boolean lookup -- does an attribute/value set exist?GetEntityAttributes— returns the FQNs assigned to a specific entity (PE or NPE),identified by email, username, client ID, or UUID
docs/sdks/troubleshooting.mdx) — Added a prevention note tothe "Resource Not Found" section pointing to
ValidateAttributesas a way to surface missingattributes at encryption time rather than decryption time
Each method includes side-by-side Go/Java/JavaScript code examples, an end-to-end
"putting it all together" pattern, and a callout noting these wrap the lower-level service
clients available in all SDKs.
Test plan
opentdf-docs-preview-dspx-2418.surge.shnpm run buildcompletes successfully