Document Range and String algorithms in ClientEncryption#encrypt - #3100
Open
comandeo-mongo wants to merge 2 commits into
Open
Document Range and String algorithms in ClientEncryption#encrypt#3100comandeo-mongo wants to merge 2 commits into
comandeo-mongo wants to merge 2 commits into
Conversation
The docs for #encrypt still described only the Indexed and Unindexed algorithms, so Range was missing from the algorithm list, range_opts and string_opts were undocumented, and the @raise clause named the wrong set of algorithms. Also add the note the client-side encryption spec requires drivers to document: payloads produced by the Indexed, Range and String algorithms have to be inserted or queried through a client configured with :auto_encryption_options. Same fixes applied to ExplicitEncrypter#encrypt, which #encrypt delegates to.
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the API documentation for explicit encryption to accurately describe the currently supported Queryable Encryption algorithms and related options, aligning ClientEncryption#encrypt and Mongo::Crypt::ExplicitEncrypter#encrypt docs with existing driver behavior.
Changes:
- Document
RangeandStringas valid:algorithmvalues for explicit encryption. - Document
:range_opts/:string_optsand clarify how:contention_factor/:query_typeapply across algorithms. - Add a spec-required note about using
:auto_encryption_optionswhen inserting/querying payloads produced by Queryable Encryption algorithms.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| lib/mongo/crypt/explicit_encrypter.rb | Expands YARD docs for algorithm/option applicability for explicit encryption. |
| lib/mongo/client_encryption.rb | Updates ClientEncryption#encrypt documentation to include Range/String algorithms, options, and required usage note. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # "String". If not provided, it defaults to a value of 0. Contention factor | ||
| # should be set only if encryption algorithm is set to "Indexed", "Range", | ||
| # or "String". | ||
| # @option options [ String | nil ] query_type Query type to be applied |
| # "String". If not provided, it defaults to a value of 0. Contention | ||
| # factor should be set only if encryption algorithm is set to "Indexed", | ||
| # "Range", or "String". | ||
| # @option options [ String | nil ] query_type Query type to be applied |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation only, no behaviour change.
ClientEncryption#encryptstill described only theIndexedandUnindexedalgorithms, even thoughRangeandStringhave both been supported for a while. As a result:Rangewas missing from the list of valid:algorithmvalues.:range_optsand:string_optswere not documented at all.:contention_factorandquery_typewere described as applying only toIndexed.@raiseclause claimedArgumentErroris raised unless the algorithm isIndexed, while the code acceptsIndexed,RangeandString.This also adds the note the client-side encryption spec requires drivers to document (spec): a payload produced by the
Indexed,RangeorStringalgorithm has to be inserted or queried through a client configured with:auto_encryption_options, where:bypass_query_analysismay be true but:bypass_auto_encryptionmust be false.The same corrections are applied to
Mongo::Crypt::ExplicitEncrypter#encrypt, whichClientEncryption#encryptdelegates to and whose docs had drifted further.Verified with RuboCop and by running
spec/mongo/client_encryption_spec.rb,spec/mongo/crypt/explicit_encryption_context_spec.rbandspec/integration/client_side_encryption/string_explicit_encryption_prose_spec.rbagainst a local 9.0 replica set.