Support for rfc5465: The IMAP NOTIFY Extension #718

WhyNotHugo · 2025-10-11T23:34:22Z

This patch series implements support for the NOTIFY extension.

The first commit implements support in imapclient, the main focus of my work. I've been using this on a client to monitor changes with success.

The second commit implements support in imapserver.

The third commit adds a minimal scaffold implementation in imapmemserver. This implementation simply rejects any request (which it technically allows as per the spec). It's not an actually useful implementation, and is mostly there so we can have minimal client-server unit tests. Implementing proper NOTIFY support for imapmemserver likely requires substantial changes which fall beyond the scope of this series.

This is likely easiest to review on a per-commit basis, and about half of the LoC are just unit tests for encoding/decoding.

WhyNotHugo · 2025-10-11T23:36:18Z

v2: removed a very long example from the docs. It's very easy for this to fall out of sync and not really useful.

WhyNotHugo · 2025-10-12T20:27:48Z

Tests with dovecot failed. When writing these tests I didn't realise that they also run with another server in CI.

I lean towards dropping the third commit— the one which implements the scaffold for NOTIFY in imapmemserver (along with the test which run server+client).

Thoughts?

WhyNotHugo · 2025-10-12T20:36:51Z

We can also drop the incomplete imapmemserver support and enable the client-server NOTIFY tests only for dovecot. I see the useDovecot flag which should be useful for that.

I'll wait for feedback before advancing this this in any way.

WhyNotHugo · 2025-10-14T15:13:45Z

v3: added test for how disconnections are handled (both with and without NOTIFY). Fix Overflow() channel hanging on disconnection.

WhyNotHugo · 2025-10-14T23:12:00Z

I've re-written the client test to run only with dovecot, which has real NOTIFY support. Those test will be skipped with the imapmemserver, but are a lot more meaningful than before.

I've ripped out the scaffold for the imapmemserver's NOTIFY support. Such broken support was useless beyond these tests.

emersion

Thanks for the patch! Here are a few comments. I've only read the client part for now, not the tests nor server.

notify.go

imapclient/status.go

imapclient/client.go

imapclient/notify.go

emersion · 2025-10-23T18:23:31Z

imapclient/notify.go

+			// Validate the item before encoding
+			if item.MailboxSpec == "" && len(item.Mailboxes) == 0 {
+				// Skip invalid items - this shouldn't happen with properly constructed NotifyOptions
+				continue


We should probably return an error here?

I can't find any other method which uses an encoder and returns an error.

Is it fine to leave the command half-written in this case? (this indicates a programmer error anyway).

For some commands we panic when fed an invalid state (e.g. see GetMetadata). For some commands we validate upfront and we return a command struct already completed with an error (e.g. see Enable). Latter is more complicated and better suited for cases where the failure doesn't indicate a programmer error (Enable is probably a bad usage for this).

Do you prefer for this to panic or return an error?

I would prefer to not return an error so that callers can chain .Wait() like other short-running commands. I don't have strong opinions about returning a command struct already completed with an error vs. a panic. Simplest would probably be to panic. (We can change it later if it turns out to be an annoyance.)

It seems like this comment has been addressed?

imapclient/notify.go

notify.go

imapclient/client.go

WhyNotHugo · 2025-11-05T20:35:46Z

I've added another commit (which probably needs to be squashed later) which allows recognising whether a NOTIFY stream ended because of an explicit NOTIFICATIONOVERFLOW or because the connection closed.

I missed the review above. Using UnilateralDataHandler is much cleaner!

WhyNotHugo · 2025-11-05T21:11:58Z

All comments addressed; ready for a second round of review.

imapclient/client.go

imapclient/status.go

emersion · 2025-11-09T11:44:23Z

imapserver/session.go

+	Session
+
+	// Authenticated state
+	Notify(w *UpdateWriter, options *imap.NotifyOptions) error


I wonder about the implications of passing an UpdateWriter to the backend here. Up until now backends would only use UpdateWriter synchronously in handlers. Here the backend would need to use it after Notify returns. We have conn.encMutex to avoid stepping on our own toes when sending an update, but that still leaves considerations such as sequence number issues with EXPUNGE notifications while another command is running, see section 5.5.

Maybe there is a way to expose a safer interface to backends. Maybe we should just leave it up to the backend and document the issue.

Would you prefer that I drop the imapserver support from this PR and focus on the client part first?

FWIW, I only wrote some of the server portions to test the client, but eventually moved on to just testing with dovecot.

Moving the server parts to a separate PR would allow the client part to be merged first, which sounds like a good idea.

imapclient/connection_test.go

Extracted from emersion#718

Client–server tests run only with dovecot; the imapmemserver doesn't support NOTIFY.

emersion · 2025-12-06T11:35:39Z

imapclient/notify_encode_test.go

+	"github.com/emersion/go-imap/v2/internal/imapwire"
+)
+
+func encodeToString(options *imap.NotifyOptions) (string, error) {


Using table-driven tests should allow us to cut down the boiler plate here I believe: https://go.dev/wiki/TableDrivenTests

emersion · 2025-12-06T11:36:20Z

imapclient/notify_encode_test.go

+	if err != nil {
+		t.Fatalf("encodeToString() error = %v", err)
+	}
+	expected := " SET ((INBOX \"Foo Bar\" \"Test&-Mailbox\") (MessageNew))\r\n"


Backtick strings can improve readability here

emersion · 2025-12-06T11:37:38Z

imapclient/notify_test.go

+)
+
+func TestClient_Notify(t *testing.T) {
+	if os.Getenv("GOIMAP_TEST_DOVECOT") != "1" {


Can we check whether the extension is supported instead of hardcoding "Dovecot == supported"? See e.g. TestACL.

emersion · 2025-12-06T11:42:05Z

imapclient/notify_test.go

+		t.Fatalf("Notify() = %v", err)
+	}
+
+	if cmd == nil {


Shouldn't we wait for the command to complete in all tests?

emersion · 2025-12-06T11:43:01Z

imapclient/notify_test.go

+	conn, server := newDovecotClientServerPair(t)
+	defer server.Close()
+
+	options := &imapclient.Options{


Oh, do we need to pass custom UnilateralDataHandler to the client, but newClientServerPair doesn't support this?

WhyNotHugo force-pushed the v2-notify branch from 75e080d to f6ad38d Compare October 11, 2025 23:35

WhyNotHugo mentioned this pull request Oct 12, 2025

imapclient: initial VANISHED support #719

Closed

WhyNotHugo force-pushed the v2-notify branch from f6ad38d to 7b5ba32 Compare October 14, 2025 15:12

WhyNotHugo force-pushed the v2-notify branch 2 times, most recently from 06a1f88 to 2a6eb8e Compare October 14, 2025 23:11

emersion reviewed Oct 23, 2025

View reviewed changes

WhyNotHugo mentioned this pull request Nov 5, 2025

NOTIFY support #314

Open

WhyNotHugo force-pushed the v2-notify branch 3 times, most recently from 91cebce to f59d635 Compare November 5, 2025 21:11

WhyNotHugo mentioned this pull request Nov 5, 2025

imapclient: implement Client.Closed #721

Merged

emersion reviewed Nov 9, 2025

View reviewed changes

imapclient/client.go Outdated Show resolved Hide resolved

emersion reviewed Nov 9, 2025

View reviewed changes

imapclient/status.go Outdated Show resolved Hide resolved

emersion reviewed Nov 9, 2025

View reviewed changes

imapclient/connection_test.go Outdated Show resolved Hide resolved

WhyNotHugo added a commit to WhyNotHugo/go-imap that referenced this pull request Nov 22, 2025

imapclient: add test for client disconnection

912b0f0

Extracted from emersion#718

WhyNotHugo mentioned this pull request Nov 22, 2025

imapclient: add test for client disconnection #727

Open

WhyNotHugo force-pushed the v2-notify branch 2 times, most recently from 984125a to c2f95df Compare November 23, 2025 08:08

WhyNotHugo added 2 commits November 23, 2025 09:10

imapclient: implement support for NOTIFY

69ce163

Client–server tests run only with dovecot; the imapmemserver doesn't support NOTIFY.

imapserver: implement support for NOTIFY

58ef58f

WhyNotHugo force-pushed the v2-notify branch from c2f95df to 58ef58f Compare November 23, 2025 08:10

emersion reviewed Dec 6, 2025

View reviewed changes

Support for rfc5465: The IMAP NOTIFY Extension #718

Are you sure you want to change the base?

Support for rfc5465: The IMAP NOTIFY Extension #718

Conversation

WhyNotHugo commented Oct 11, 2025

Uh oh!

WhyNotHugo commented Oct 11, 2025

Uh oh!

WhyNotHugo commented Oct 12, 2025

Uh oh!

WhyNotHugo commented Oct 12, 2025

Uh oh!

WhyNotHugo commented Oct 14, 2025

Uh oh!

WhyNotHugo commented Oct 14, 2025

Uh oh!

emersion left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

WhyNotHugo commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

WhyNotHugo commented Nov 5, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

WhyNotHugo commented Nov 5, 2025 •

edited

Loading