imapserver: implement UIDONLY extension, RFC 9586

Once clients enable this extension, commands can no longer refer to "message
sequence numbers" (MSNs), but can only refer to messages with UIDs. This means
both sides no longer have to carefully keep their sequence numbers in sync
(error-prone), and don't have to keep track of a mapping of sequence numbers to
UIDs (saves resources).

With UIDONLY enabled, all FETCH responses are replaced with UIDFETCH response.

imapclient/cmds.go

@@ -388,6 +388,42 @@ func (c *Conn) StoreFlagsClear(seqset string, silent bool, flags ...string) (unt
 	return c.Transactf("store %s %s (%s)", seqset, item, strings.Join(flags, " "))
 }
 
+// UIDStoreFlagsSet stores a new set of flags for messages from uid set with
+// the UID STORE command.
+//
+// If silent, no untagged responses with the updated flags will be sent by the
+// server.
+func (c *Conn) UIDStoreFlagsSet(seqset string, silent bool, flags ...string) (untagged []Untagged, result Result, rerr error) {
+	defer c.recover(&rerr)
+	item := "flags"
+	if silent {
+		item += ".silent"
+	}
+	return c.Transactf("uid store %s %s (%s)", seqset, item, strings.Join(flags, " "))
+}
+
+// UIDStoreFlagsAdd is like UIDStoreFlagsSet, but only adds flags, leaving
+// current flags on the message intact.
+func (c *Conn) UIDStoreFlagsAdd(seqset string, silent bool, flags ...string) (untagged []Untagged, result Result, rerr error) {
+	defer c.recover(&rerr)
+	item := "+flags"
+	if silent {
+		item += ".silent"
+	}
+	return c.Transactf("uid store %s %s (%s)", seqset, item, strings.Join(flags, " "))
+}
+
+// UIDStoreFlagsClear is like UIDStoreFlagsSet, but only removes flags, leaving
+// other flags on the message intact.
+func (c *Conn) UIDStoreFlagsClear(seqset string, silent bool, flags ...string) (untagged []Untagged, result Result, rerr error) {
+	defer c.recover(&rerr)
+	item := "-flags"
+	if silent {
+		item += ".silent"
+	}
+	return c.Transactf("uid store %s %s (%s)", seqset, item, strings.Join(flags, " "))
+}
+
 // Copy adds messages from the sequences in seqSet in the currently selected/active mailbox to dstMailbox.
 func (c *Conn) Copy(seqSet NumSet, dstMailbox string) (untagged []Untagged, result Result, rerr error) {
 	defer c.recover(&rerr)

imapclient/parse.go

@@ -136,6 +136,7 @@ var knownCodes = stringMap(
 	"INPROGRESS",                       // ../rfc/9585:104
 	"BADEVENT", "NOTIFICATIONOVERFLOW", // ../rfc/5465:1023
 	"SERVERBUG",
+	"UIDREQUIRED", // ../rfc/9586:136
 )
 
 func stringMap(l ...string) map[string]struct{} {
@@ -654,14 +655,17 @@ func (c *Conn) xuntagged() Untagged {
 			w = c.xword()
 			W = strings.ToUpper(w)
 			switch W {
-			case "FETCH":
+			case "FETCH", "UIDFETCH":
 				if num == 0 {
 					c.xerrorf("invalid zero number for untagged fetch response")
 				}
 				c.xspace()
-				r := c.xfetch(num)
+				attrs := c.xfetch()
 				c.xcrlf()
-				return r
+				if W == "UIDFETCH" {
+					return UntaggedUIDFetch{num, attrs}
+				}
+				return UntaggedFetch{num, attrs}
 
 			case "EXPUNGE":
 				if num == 0 {
@@ -691,14 +695,14 @@ func (c *Conn) xuntagged() Untagged {
 
 // ../rfc/3501:4864 ../rfc/9051:6742
 // Already parsed: "*" SP nznumber SP "FETCH" SP
-func (c *Conn) xfetch(num uint32) UntaggedFetch {
+func (c *Conn) xfetch() []FetchAttr {
 	c.xtake("(")
 	attrs := []FetchAttr{c.xmsgatt1()}
 	for c.space() {
 		attrs = append(attrs, c.xmsgatt1())
 	}
 	c.xtake(")")
-	return UntaggedFetch{num, attrs}
+	return attrs
 }
 
 // ../rfc/9051:6746

imapclient/protocol.go

@@ -43,6 +43,7 @@ const (
 	CapPreview          Capability = "PREVIEW"            // ../rfc/8970:114
 	CapMultiSearch      Capability = "MULTISEARCH"        // ../rfc/7377:187
 	CapNotify           Capability = "NOTIFY"             // ../rfc/5465:195
+	CapUIDOnly          Capability = "UIDONLY"            // ../rfc/9586:129
 )
 
 // Status is the tagged final result of a command.
@@ -261,6 +262,14 @@ type UntaggedFetch struct {
 	Seq   uint32
 	Attrs []FetchAttr
 }
+
+// UntaggedUIDFetch is like UntaggedFetch, but with UIDs instead of message
+// sequence numbers, and returned instead of regular fetch responses when UIDONLY
+// is enabled.
+type UntaggedUIDFetch struct {
+	UID   uint32
+	Attrs []FetchAttr
+}
 type UntaggedSearch []uint32
 
 // ../rfc/7162:1101