eclipse-ee4j / eclipse-ee4j/angus-mail

IdleManager.watch() returns before IDLE state is established

Open
#159 3 comments 0 reactions 0 assignees View on GitHub
enhancement question
Dominant language
Java
Stars
87
Forks
23
PR merge metrics
No merged PRs in 30d

Description

## Current Behavior
The `IdleManager.watch(folder)` method returns immediately after queuing the folder for IDLE monitoring, before the IDLE state is actually established. This makes it impossible to know when the IMAP IDLE connection is ready to receive messages.

Debug logs show this sequence:

DEBUG IMAP: IdleManager.watch startIdle succeeded for imaps://%40gmail.com@imap.gmail.com/INBOX // watch() returns here
DEBUG IMAP: IdleManager selected 0 channels
DEBUG IMAP: IdleManager adding imaps://%40gmail.com@imap.gmail.com/INBOX to selector
DEBUG IMAP: IdleManager waiting... // IDLE is actually ready here.

It is easy to make the mistake of thinking IDLE is ready when it isn't as watch() succeeds prematurely.
We understand the reasoning on why watch() exits prematurely - it is due to the executor running in parallel however we must be able to wait for IDLE to succeed before continuing.

## Expected Behavior
One of these options:
1. `watch()` should wait until IDLE is fully established
2. Add a new method like `watchAndWait()` that blocks until IDLE is ready
3. Expose a way to query/listen for the IDLE ready state

## Use Case
When setting up IMAP IDLE monitoring, applications need to know when the connection is actually ready to receive messages. Currently there's no clean way to detect this without resorting to implementation details or log parsing.

**Mail server:**

It is an issue with the angus-mail itself and not the mail server.
- Protocol being used: imap
- Mail service URL: gmail.com

**Additional context**
Currently, it appears the only way to wait for an IDLE state to be ready is via "hacks".

Contributor guide

Open the contributing guide

Research direction

Start by reading IdleManager.watch(folder), its startIdle call, and the executor flow shown in the debug logs. Reproduce the timing where watch() returns before the selector reaches the IDLE-ready state, then determine which readiness behavior the API should guarantee. Done means callers have a documented, reliable way to know that IDLE monitoring is established.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
backend-api-design, networking
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.