Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

✨ Enable parenthesized lists in search criteria #345

Merged
merged 1 commit into from
Nov 8, 2024

Conversation

nevans
Copy link
Collaborator

@nevans nevans commented Oct 30, 2024

This affects #search, #uid_search, #sort, #uid_sort, #thread, and #uid_thread#.

Prior to this, sending a parenthesized list in the search criteria for any of these commands required the use of strings, which are converted to RawData, which has security implications with untrusted inputs.

With this change, arrays will only be converted into SequenceSet when every element in the array is a valid SequenceSet input. Otherwise, the array will be left alone, which allows us to send parenthesized lists without using strings and RawData.

For example, some searches this change enables:

  • combining criteria to pass into OR, NOT, FUZZY, etc.
    • search(["not", %w(flagged unread)]) converts to:
      SEARCH not (flagged unread)
  • Adding return options (we should also add a return kwarg).
    • uid_search(["RETURN", ["PARTIAL", 1..50], "UID", 12345..67890] converts to:
      UID SEARCH RETURN (PARTIAL 1:50) UID 12345:67890
    • Note that PARTIAL supports negative ranges, which can't be coerced to SequenceSet.
      They'll need to be sent as strings, for now.
    • Note that searches with return options should return ESEARCH results, which are currently unsupported.
      See ✨ Add basic ESearch support #333.

This should be backward compatible: previously these inputs would simply raise an exception.

lib/net/imap.rb Outdated Show resolved Hide resolved
lib/net/imap/sequence_set.rb Outdated Show resolved Hide resolved
lib/net/imap.rb Outdated Show resolved Hide resolved
This affects `#search`, `#uid_search`, `#sort`, `#uid_sort`, `#thread`,
and `#uid_thread`.

Prior to this, sending a parenthesized list in the search criteria for
any of these commands required the use of strings, which are converted
to `RawData`, which has security implications with untrusted inputs.

With this change, arrays will only be converted into SequenceSet when
_every_ element in the array is a valid SequenceSet input.  Otherwise,
the array will be left alone, which allows us to send parenthesized
lists without using strings and RawData.

For example, some searches this change enables:

* Combining criteria to pass into `OR`, `NOT`, `FUZZY`, etc.
  * `search(["not", %w(flagged unread)])`
    converts to: `SEARCH not (flagged unread)`
* Adding return options (we should also add a return kwarg).
  * `uid_search(["RETURN", ["PARTIAL", 1..50], "UID", 12345..67890])`
    converts to: `UID SEARCH RETURN (PARTIAL 1:50) UID 12345:67890`
  * Note that `PARTIAL` supports negative ranges, which can't be coerced
    to SequenceSet.  They'll need to be sent as strings, for now.
  * Note that searches with return options should return ESEARCH
    results, which are currently unsupported.  See #333.

This _should_ be backward compatible: previously these inputs would
raise an exception.
@nevans nevans merged commit 2d6dbde into master Nov 8, 2024
22 checks passed
@nevans nevans deleted the search-parenthesized-lists branch November 8, 2024 22:44
@nevans nevans added the IMAP4rev1 Requirement for IMAP4rev1, RFC3501 label Nov 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
IMAP4rev1 Requirement for IMAP4rev1, RFC3501
Development

Successfully merging this pull request may close these issues.

1 participant