Skip to content

Conversation

@nevans
Copy link
Collaborator

@nevans nevans commented Sep 3, 2025

The vanished kwarg to #uid_fetch can be used to request a list all of the message UIDs in set that have been expunged since changedsince. Setting vanished to true prepends a VanishedData object to the returned array. If the server does not return a VANISHED response, an empty VanishedData object will still be added.

For example:

  imap.enable("QRESYNC") # must enable before selecting the mailbox
  imap.select("INBOX")
  # the first value in the returned array is a VanishedData object
  vanished, *fetched = imap.uid_fetch(301..500, %w[FLAGS],
                                      changedsince: 12345,
                                      vanished: true)

The QRESYNC capabability must be enabled. RFC7162

Alternatives for return type

This PR chose to prepend a VanishedData object to the returned array. Because it only does this when the vanished: true kwarg is sent, it should be fully backward compatible. Other API choices were considered:

  • Make no changes and continue returning only an array of fetch data. This is not very user friendly.
  • Return a tuple of [vanished, fetched_array]. I strongly prefer a flat array of responses ([vanished, *fetched_array]). IMO, it's more consistent with the original API, and just as easy to work with.
  • Return a new FetchResult type, with a #vanished method.
    • This could subclass Array, like SearchResult. That was done to minimize any backward compatibility issues. Also, there's no simple way to distinguish between a modseq integer and a UID or sequence number. But I'd prefer not to subclass Array.
    • This could delegate to the fetch data array. This is my preferred approach. But I don't want to only enable it for vanished. I'd prefer to always return FetchResult according to a fetch_result config option. And that wouldn't be backward compatible enough to enable by default for the next release.

@nevans nevans added the enhancement New feature or request label Sep 3, 2025
@nevans nevans force-pushed the qresync-uid_fetch-vanished branch from 909d447 to e94c14b Compare September 5, 2025 14:47
Base automatically changed from qresync-enable to master September 5, 2025 14:49
@nevans nevans marked this pull request as ready for review September 5, 2025 16:05
@nevans nevans force-pushed the qresync-uid_fetch-vanished branch 2 times, most recently from 9541b7a to 2e4a744 Compare September 5, 2025 16:21
@nevans nevans marked this pull request as draft September 5, 2025 16:23
@nevans nevans force-pushed the qresync-uid_fetch-vanished branch from 2e4a744 to 017bda2 Compare September 5, 2025 16:30
@nevans nevans changed the title ✨ QRESYNC: Add vanished kwarg to #uid_fetch ✨ QRESYNC: Add vanished kwarg to #uid_fetch Sep 5, 2025
@nevans nevans force-pushed the qresync-uid_fetch-vanished branch from 017bda2 to 5c8c0e9 Compare September 5, 2025 16:35
@nevans
Copy link
Collaborator Author

nevans commented Sep 5, 2025

@shugo Before I merge this, do you have any thoughts on the vanished, *fetched = uid_fetch(...) API design choice?

@nevans nevans force-pushed the qresync-uid_fetch-vanished branch from 5c8c0e9 to 5ad5cbb Compare September 5, 2025 17:13
@nevans nevans changed the title ✨ QRESYNC: Add vanished kwarg to #uid_fetch ✨ QRESYNC: Add vanished keyword to #uid_fetch Sep 5, 2025
@nevans nevans marked this pull request as ready for review September 23, 2025 14:16
@nevans nevans requested a review from shugo September 23, 2025 14:40
@nevans nevans linked an issue Oct 16, 2025 that may be closed by this pull request
@nevans nevans added this to the v0.6 milestone Oct 16, 2025
The `vanished` kwarg to `#uid_fetch` can be used to request a list all
of the message UIDs in `set` that have been expunged since
`changedsince`.  Setting `vanished` to true prepends a `VanishedData`
object to the returned array.  If the server does not return a
`VANISHED` response, an empty `VanishedData` object will still be added.

_The +QRESYNC+ capabability must be enabled._
[RFC7162](https://rfc-editor.org/rfc/rfc7162)

For example:
```ruby
  imap.enable("QRESYNC") # must enable before selecting the mailbox
  imap.select("INBOX")
  # the first value in the returned array is a VanishedData object
  vanished, *fetched = imap.uid_fetch(301..500, %w[FLAGS],
                                      changedsince: 12345,
                                      vanished: true)
```
@nevans nevans force-pushed the qresync-uid_fetch-vanished branch from 5ad5cbb to 129fbda Compare October 21, 2025 13:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add :vanished kwarg to #fetch/#uid_fetch (RFC7162, QRESYNC)

2 participants