Add Dialer.GetMaxUID using RFC-4731 (from #83 + coverage fixes) (#85)

* Add Dialer.GetMaxUID as alt method using RFC-4731

* Use t.Skip() instread of if (false)

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* strings.Split -> strings.Fields; camelCase instead of snake

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* fix: fix indentation and add tests for parseMaxUIDSearchResponse coverage

Fix indentation issues from applying review suggestions and add unit
tests covering error paths (no ESEARCH line, empty response, non-numeric
MAX value) to satisfy code coverage requirements.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address review feedback for parseMaxUIDSearchResponse

- Rename searchMaxUIDre to searchMaxUIDRE for naming consistency
- Use case-insensitive regex with capturing group to extract MAX value
- Handles MAX not being the last token (RFC 4731 allows MIN/MAX/COUNT)
- Add tests for case-insensitive matching and MAX-not-last scenarios

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address code review feedback for GetMaxUID

- Handle empty mailbox: ESEARCH without MAX returns 0, nil (RFC 4731)
- Detect malformed ESEARCH MAX values and return error
- Add RFC-4731 server requirement caveat to README and example
- Example now handles GetMaxUID error instead of silently ignoring it

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: simplify ESEARCH detection in parseMaxUIDSearchResponse

- Replace redundant strings.EqualFold on "* " (no letters) with ==
- Move strings.ToUpper inside prefix check to avoid uppercasing
  every non-ESEARCH line

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Martin Brugnara <mb@martinbrugnara.me>
Co-authored-by: Martin Brugnara <martin@0x6d62.eu>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 4 people

.gitignore

@@ -3,3 +3,4 @@ imap.exe
 .devcontainer
 .vscode/settings.json
 coverage.out
+*.sw?

README.md

@@ -356,6 +356,10 @@ rangeUIDs, _ := m.GetUIDs("1:10")      // UIDs 1 through 10
 // Get the N most recent messages (recommended for "last N" queries)
 last10UIDs, _ := m.GetLastNUIDs(10)    // Last 10 messages by UID
 
+// Cheaper method to retrieve the latest UID (requires RFC-4731;
+// not all servers support this — check the error).
+maxUID, _ := m.GetMaxUID()             // Highest UID only
+
 // Size-based searches
 largeUIDs, _ := m.GetUIDs("LARGER 10485760")  // Emails larger than 10MB
 smallUIDs, _ := m.GetUIDs("SMALLER 1024")     // Emails smaller than 1KB

examples/search/main.go

@@ -98,11 +98,17 @@ func main() {
 
 	firstUID, _ := m.GetUIDs("1")       // First email
 	lastUID, _ := m.GetUIDs("*")        // Last email
+	maxUID, err := m.GetMaxUID()        // Last email (cheaper, requires RFC-4731)
 	first10UIDs, _ := m.GetUIDs("1:10") // First 10 emails
 	last10UIDs, _ := m.GetUIDs("*:10")  // Last 10 emails (reverse)
 
 	fmt.Printf("First email UID: %v\n", firstUID)
 	fmt.Printf("Last email UID: %v\n", lastUID)
+	if err != nil {
+		fmt.Printf("Last email UID (alt): not supported (%v)\n", err)
+	} else {
+		fmt.Printf("Last email UID (alt): %v\n", maxUID)
+	}
 	fmt.Printf("First 10 email UIDs: %v\n", first10UIDs)
 	if len(last10UIDs) <= 10 {
 		fmt.Printf("Last 10 email UIDs: %v\n", last10UIDs)

integration_test.go

@@ -204,6 +204,29 @@ func TestIntegration_GetLastNUIDs(t *testing.T) {
 			}
 		}
 	})
+
+	// TODO: enable once test-imap server supports RFC-4731.
+	//  Currently fails with: "Search command not supported".
+	t.Run("GetMaxUID returns highest UID", func(t *testing.T) {
+		t.Skip("enable once test-imap server supports RFC-4731. Currently fails with: 'Search command not supported'.")
+
+		last1, err := conn.GetLastNUIDs(1)
+		if err != nil {
+			t.Fatalf("GetLastNUIDs(1) failed: %v", err)
+		}
+
+		maxUID, err := conn.GetMaxUID()
+		if err != nil {
+			t.Fatalf("GetMaxUID() failed: %v", err)
+		}
+
+		// last1 and maxUID must be identical.
+		// NOTE: depends on GetLastNUIDs correctness,
+		//       which is already tested above.
+		if maxUID != last1[0] {
+			t.Errorf("Mismatch on max uid: got %d, want %d", maxUID, last1[0])
+		}
+	})
 }
 
 func TestIntegration_GetUIDs_Ranges(t *testing.T) {

message.go

@@ -183,6 +183,18 @@ func (d *Dialer) GetLastNUIDs(n int) ([]int, error) {
 	return allUIDs[len(allUIDs)-n:], nil
 }
 
+// Get max UID in the current folder using RFC-4731.
+//
+// The folder of interest must be already selected in either read-only mode,
+// ExamineFolder, or in read-write mode, SelectFolder.
+func (d *Dialer) GetMaxUID() (uid int, err error) {
+	r, err := d.Exec("UID SEARCH RETURN (MAX) 1:*", true, RetryCount, nil)
+	if err != nil {
+		return 0, err
+	}
+	return parseMaxUIDSearchResponse(r)
+}
+
 // MoveEmail moves an email to a different folder
 func (d *Dialer) MoveEmail(uid int, folder string) (err error) {
 	// if we are currently read-only, switch to SELECT for the move-operation

message_test.go

@@ -133,6 +133,92 @@ func TestGetLastNUIDs_EdgeCases(t *testing.T) {
 	})
 }
 
+func TestParseMaxUIDSearchResponse(t *testing.T) {
+	t.Run("valid ESEARCH response", func(t *testing.T) {
+		response := `COFFEE 121
+	some more random UID 122
+	some more random UID MAX 123
+	UID MAX 124
+	* ESEARCH (TAG "D6OVA9F5SOCMJIK7FEH0") UID MAX 387992
+	not me UID MAX 125
+	`
+		maxUID, err := parseMaxUIDSearchResponse(response)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if maxUID != 387992 {
+			t.Errorf("unexpected maxuid: got %d, want 387992", maxUID)
+		}
+	})
+
+	t.Run("minimal ESEARCH response", func(t *testing.T) {
+		response := "* ESEARCH (TAG \"A285\") UID MAX 3800\r\nA285 OK SEARCH completed\r\n"
+		maxUID, err := parseMaxUIDSearchResponse(response)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if maxUID != 3800 {
+			t.Errorf("unexpected maxuid: got %d, want 3800", maxUID)
+		}
+	})
+
+	t.Run("no ESEARCH line returns error", func(t *testing.T) {
+		response := "A285 OK SEARCH completed\r\n"
+		_, err := parseMaxUIDSearchResponse(response)
+		if err == nil {
+			t.Fatal("expected error for response without ESEARCH line")
+		}
+	})
+
+	t.Run("empty response returns error", func(t *testing.T) {
+		_, err := parseMaxUIDSearchResponse("")
+		if err == nil {
+			t.Fatal("expected error for empty response")
+		}
+	})
+
+	t.Run("ESEARCH with non-numeric MAX returns error", func(t *testing.T) {
+		response := "* ESEARCH (TAG \"A285\") UID MAX notanumber\r\n"
+		_, err := parseMaxUIDSearchResponse(response)
+		if err == nil {
+			t.Fatal("expected error for non-numeric MAX value")
+		}
+	})
+
+	t.Run("MAX not last token in ESEARCH", func(t *testing.T) {
+		response := "* ESEARCH (TAG \"A285\") UID MIN 1 MAX 3800 COUNT 50\r\n"
+		maxUID, err := parseMaxUIDSearchResponse(response)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if maxUID != 3800 {
+			t.Errorf("unexpected maxuid: got %d, want 3800", maxUID)
+		}
+	})
+
+	t.Run("case insensitive ESEARCH", func(t *testing.T) {
+		response := "* esearch (TAG \"A285\") uid max 4200\r\n"
+		maxUID, err := parseMaxUIDSearchResponse(response)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if maxUID != 4200 {
+			t.Errorf("unexpected maxuid: got %d, want 4200", maxUID)
+		}
+	})
+
+	t.Run("empty mailbox ESEARCH without MAX returns zero", func(t *testing.T) {
+		response := "* ESEARCH (TAG \"A285\") UID\r\nA285 OK SEARCH completed\r\n"
+		maxUID, err := parseMaxUIDSearchResponse(response)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if maxUID != 0 {
+			t.Errorf("expected 0 for empty mailbox, got %d", maxUID)
+		}
+	})
+}
+
 func TestEnvelopeAtomAddress(t *testing.T) {
 	name := "CBJ SAP SUPPORT INSIGHT"
 	env := &Token{Type: TContainer, Tokens: []*Token{

parse.go

@@ -17,6 +17,7 @@ const (
 var (
 	atom             = regexp.MustCompile(`{\d+\+?}$`)
 	fetchLineStartRE = regexp.MustCompile(`(?m)^\* \d+ FETCH`)
+	searchMaxUIDRE   = regexp.MustCompile(`(?i)\* ESEARCH .* MAX (\d+)`)
 )
 
 // Token represents a parsed IMAP token
@@ -456,6 +457,53 @@ func parseUIDSearchResponse(r string) ([]int, error) {
 	return nil, fmt.Errorf("invalid response: %q", strings.TrimSpace(r))
 }
 
+// Parse SEARCH RETURN(MAX) command response
+//
+// Expected response format (RFC 4731)
+//
+//	C: A285 UID SEARCH RETURN (MAX) 1:5000
+//	S: * ESEARCH (TAG "A285") UID MAX 3800
+//	S: A285 OK SEARCH completed
+//
+// When the mailbox is empty, RFC 4731 omits MAX from the ESEARCH line:
+//
+//	S: * ESEARCH (TAG "A285") UID
+//
+// In that case this function returns 0, nil.
+// ref https://www.rfc-editor.org/rfc/rfc4731.html#page-2
+func parseMaxUIDSearchResponse(r string) (int, error) {
+	normalized := strings.ReplaceAll(r, nl, "\n")
+	for rawLine := range strings.SplitSeq(normalized, "\n") {
+		line := strings.TrimSpace(rawLine)
+		if line == "" {
+			continue
+		}
+
+		if matches := searchMaxUIDRE.FindStringSubmatch(line); len(matches) > 1 {
+			maxUID, err := strconv.Atoi(matches[1])
+			if err != nil {
+				return 0, fmt.Errorf("parse max uid %q: %w", matches[1], err)
+			}
+			return maxUID, nil
+		}
+
+		// Check for ESEARCH line without a valid MAX capture
+		if len(line) > 2 && line[:2] == "* " {
+			upper := strings.ToUpper(line)
+			if strings.Contains(upper, "ESEARCH") {
+				// If MAX keyword is present but didn't match \d+, that's malformed
+				if strings.Contains(upper, " MAX ") {
+					return 0, fmt.Errorf("malformed ESEARCH MAX value in: %q", line)
+				}
+				// ESEARCH present without MAX means empty result set (RFC 4731)
+				return 0, nil
+			}
+		}
+	}
+
+	return 0, fmt.Errorf("no ESEARCH line. rfc4731 not supported?")
+}
+
 // IsLiteral checks if a rune is valid for a literal token
 func IsLiteral(b rune) bool {
 	switch {