docs(sdks): document TDF decrypt convenience helpers - #379
Conversation
Add a Decrypt Helpers section to the TDF SDK reference (DecryptBytes, DecryptTo, DecryptFile — thin wrappers over LoadTDF + WriteTo, plus the ErrTDFNotDecryptable / ErrTDFDecryptFailed sentinels), and update the Go quickstart's decrypt examples to use them instead of the manual LoadTDF + WriteTo sequence. Corresponds to opentdf/platform#3828. Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
📝 WalkthroughWalkthroughThe Go SDK documentation adds ChangesGo decryption helpers
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 `@docs/sdks/tdf.mdx`:
- Around line 570-588: Update the error-handling example for DecryptBytes,
DecryptTo, and DecryptFile so the fallback case no longer lists writer errors as
outside the documented categories; remove that example or describe only
unexpected errors outside the helper contract, while preserving the
ErrTDFNotDecryptable and ErrTDFDecryptFailed branches.
🪄 Autofix
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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 2598c24a-daf9-4590-938d-3380bd0866e1
📒 Files selected for processing (2)
docs/sdks/quickstart/go.mdxdocs/sdks/tdf.mdx
|
📄 Preview deployed to https://opentdf-docs-pr-379.surge.sh |
The switch example's fallback case described writer errors as an uncategorized "other failure," contradicting the preceding table, which correctly classifies writer errors under ErrTDFDecryptFailed. Every failure from all three helpers wraps one of the two sentinels, so drop the misleading third case. Flagged by CodeRabbit on #379. Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
DecryptBytes now rejects payloads over 1 GiB before buffering, since it holds the full plaintext in memory unlike DecryptTo/DecryptFile. Corresponds to opentdf/platform#3828. Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
…ntence The 1 GiB limit was buried in the intro sentence before the Signature — easy to miss. Give it its own callout paragraph after the Example, matching how DecryptFile's behavior notes are presented. Also reword the "no third, uncategorized case" sentence, which read awkwardly. Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
…kward sentence" This reverts commit 5fe0f03.
The Decrypt Helpers signatures use opts ...TDFReaderOption but never linked to what it is, unlike LoadTDF's own Parameters table. Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
Was a parenthetical inside the Pre-decrypt failure row's Cause column — easy to miss. Split it into its own row. Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
…ss-link - All three Decrypt Helpers signatures/examples now take ctx context.Context as their first parameter, matching opentdf/platform#3828's review-driven signature change (ctx governs the KAS rewrap request). - Add <SdkVersion language="go" version="0.29.0" .../> under each of the three Signatures, matching the established per-Signature placement convention used elsewhere in this file. - Cross-link from assertion_examples.mdx's End-to-End Example to Decrypt Helpers, explaining why that example stays on LoadTDF directly (it reads tdfReader.Manifest().Assertions, which the helpers don't expose). Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/sdks/tdf.mdx (2)
574-584: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winAlign the documented error contract with decrypt helper returns.
The
DecryptFilehelper can return file-system and validation errors instead of onlysdk.ErrTDFNotDecryptableorsdk.ErrTDFDecryptFailed. Either have the SDK wrap those paths with the same sentinels, or update this table/example to call out an unclassifiedDecryptFilefallback path.🤖 Prompt for 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. In `@docs/sdks/tdf.mdx` around lines 574 - 584, Update the Errors documentation for DecryptFile to reflect its actual file-system and validation error behavior, either by documenting an unclassified fallback path or by changing the SDK implementation so every such failure is wrapped with ErrTDFNotDecryptable or ErrTDFDecryptFailed. Keep the documented errors.Is/errors.As contract consistent across DecryptBytes, DecryptTo, and DecryptFile.Source: MCP tools
530-532: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick winDocument partial writes for streaming decryption output.
DecryptTocalls theTDFReader.WriteTostream path, where payload-integrity checks can fail after plaintext bytes have already been written. A destination such as an HTTP response can therefore end with partial plaintext. For all-or-nothing output, recommend buffering the write and returning it only after decryption completes without error.🤖 Prompt for 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. In `@docs/sdks/tdf.mdx` around lines 530 - 532, Update the DecryptTo documentation to state that streaming decryption may write partial plaintext before a payload-integrity error occurs. Recommend buffering output and releasing it only after decryption completes successfully when all-or-nothing output is required.Source: MCP tools
🤖 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 `@code_samples/tdf/assertion_examples.mdx`:
- Line 59: Revise the explanatory text around the LoadTDF assertion example to
distinguish the helper outputs precisely: DecryptBytes returns plaintext bytes,
while DecryptTo and DecryptFile write plaintext to their destinations and return
only an error. Keep the rationale that LoadTDF is required to access
tdfReader.Manifest().Assertions.
---
Outside diff comments:
In `@docs/sdks/tdf.mdx`:
- Around line 574-584: Update the Errors documentation for DecryptFile to
reflect its actual file-system and validation error behavior, either by
documenting an unclassified fallback path or by changing the SDK implementation
so every such failure is wrapped with ErrTDFNotDecryptable or
ErrTDFDecryptFailed. Keep the documented errors.Is/errors.As contract consistent
across DecryptBytes, DecryptTo, and DecryptFile.
- Around line 530-532: Update the DecryptTo documentation to state that
streaming decryption may write partial plaintext before a payload-integrity
error occurs. Recommend buffering output and releasing it only after decryption
completes successfully when all-or-nothing output is required.
🪄 Autofix
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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: bee637de-e40c-4d3a-a66c-0d97a65a5305
📒 Files selected for processing (3)
code_samples/tdf/assertion_examples.mdxdocs/sdks/quickstart/go.mdxdocs/sdks/tdf.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/sdks/quickstart/go.mdx
2 participants
Summary
Documents the new Go SDK
DecryptBytes/DecryptTo/DecryptFileconvenience helpers added in opentdf/platform#3828.docs/sdks/tdf.mdx(betweenLoadTDFandIsValidTdf): signatures, examples,DecryptFile's temp-file/rename/backup-restore behavior, and an Errors table coveringErrTDFNotDecryptable/ErrTDFDecryptFailedwith anerrors.Isexample.docs/sdks/quickstart/go.mdx— all three places that manually didLoadTDF+WriteTo(the Step 3 running example, "Save TDF to a File", and the "Complete Reference Implementation") now use the new helpers.Modeled on the existing
BulkDecryptsection's structure (Go-only convenience methods don't need forced<Tabs>shells for Java/JS). Heading names (DecryptBytes/DecryptTo/DecryptFile) are unique across the page and its importedcode_samples/*.mdxfiles, per the anchor-collision rule inAGENTS.md.Test plan
vale docs/sdks/tdf.mdx docs/sdks/quickstart/go.mdx— 0 errors, warnings, or suggestions.sdk/decrypt.go,sdk/decrypterrors.go).tdf.mdxand its imports — none.Summary by CodeRabbit