Speed up Find Similar with precompute and inbox cache

POST /api/similar previously took many seconds because it re-fetched
1000 emails from JMAP on every call and ran O(N²) Levenshtein over
email bodies that could be tens of thousands of characters.

- Precompute normalized subject, sender, and body tokens once per
  email so the inner pairwise compare avoids re-normalizing and
  re-tokenizing the same strings.
- Replace Levenshtein on bodies with Jaccard overlap of word tokens
  (length >= 3). O(L) per pair instead of O(L1*L2).
- Short-circuit each weighted stage as soon as the partial score plus
  the maximum remaining contribution falls below the threshold.
- Cache the 1000-email inbox fetch server-side for 60 seconds, with
  invalidation on archive/unarchive, so successive "Find Similar" and
  rapid "Archive & Find Next" calls don't re-pull from JMAP.

BenchmarkFindSimilarEmails over a synthetic 1000-email corpus runs
in ~4.3 ms. The public similarity API is unchanged and all existing
tests pass; new tests cover Jaccard, tokenizeBody, cache hit, cache
invalidation, TTL expiration, and the no-cache-on-error path.

Author: taskinen

CLAUDE.md

@@ -84,10 +84,12 @@ mailboxzero/
 - **File:** `similarity.go`
 - **Purpose:** Advanced fuzzy matching for email similarity
 - **Algorithm:**
-  - **Subject Similarity (40% weight):** Levenshtein distance with normalization
-  - **Sender Similarity (40% weight):** Email address comparison
-  - **Content Similarity (20% weight):** Body/preview text analysis
+  - **Subject Similarity (40% weight):** Levenshtein distance over pre-normalized strings
+  - **Sender Similarity (40% weight):** Levenshtein distance over pre-normalized sender email address
+  - **Content Similarity (20% weight):** Jaccard similarity over normalized word tokens (length ≥ 3) extracted from the preview/body
 - **Features:**
+  - Per-email features (`subjectNorm`, `senderNorm`, `bodyTokens`) precomputed once per call so the inner pairwise compare avoids re-normalizing or re-tokenizing the same strings
+  - Threshold-aware short-circuit: each weighted stage bails out as soon as the partial score plus the maximum remaining contribution falls below `threshold`
   - String normalization (lowercase, punctuation removal)
   - Common word detection for similarity boosting
   - Configurable threshold matching
@@ -108,6 +110,7 @@ mailboxzero/
   - JSON API responses
   - Error handling and logging
   - Static file serving
+  - Inbox cache for `/api/similar`: the 1000-email JMAP fetch is cached in-process for 60 seconds (`inboxCacheTTL`) and invalidated at the end of `handleArchive`/`handleUnarchive`, so successive "Find Similar" / "Archive & Find Next" calls don't re-pull from JMAP
 
 #### 5. Frontend Interface (`web/`)
 - **Template:** `index.html` - Responsive dual-pane layout
@@ -247,7 +250,7 @@ go run main.go
 ```
 
 **Mock Mode Features:**
-- Uses realistic sample email data (40+ emails from various senders)
+- Uses realistic sample email data (~32–52 emails: 10 senders × 3–5 messages plus 2 unique)
 - No real JMAP connection required
 - Sample emails include groups of similar messages for testing similarity matching
 - Simulates archiving operations without affecting real emails

README.md

@@ -143,8 +143,8 @@ mock_mode: false          # Set to true to use built-in sample data (no JMAP nee
 The application uses fuzzy matching with weighted scoring:
 
 - **Subject Similarity** (40%): Compares email subjects using Levenshtein distance
-- **Sender Similarity** (40%): Compares sender email addresses
-- **Content Similarity** (20%): Compares email preview/body content
+- **Sender Similarity** (40%): Compares sender email addresses using Levenshtein distance
+- **Content Similarity** (20%): Jaccard overlap of normalized word tokens (length ≥ 3) extracted from the preview/body
 
 Additional boosters:
 - Common words in subjects increase similarity

internal/server/server.go

@@ -7,6 +7,8 @@ import (
 	"log"
 	"net/http"
 	"strconv"
+	"sync"
+	"time"
 
 	"mailboxzero/internal/config"
 	"mailboxzero/internal/jmap"
@@ -15,10 +17,16 @@ import (
 	"github.com/gorilla/mux"
 )
 
+const inboxCacheTTL = 60 * time.Second
+
 type Server struct {
 	config     *config.Config
 	jmapClient jmap.JMAPClient
 	templates  *template.Template
+
+	inboxMu       sync.Mutex
+	inboxCache    []jmap.Email
+	inboxCachedAt time.Time
 }
 
 type PageData struct {
@@ -114,7 +122,7 @@ func (s *Server) handleFindSimilar(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	emails, err := s.jmapClient.GetInboxEmails(1000)
+	emails, err := s.getInboxForSimilarity()
 	if err != nil {
 		http.Error(w, fmt.Sprintf("Failed to get emails: %v", err), http.StatusInternalServerError)
 		return
@@ -167,6 +175,7 @@ func (s *Server) handleArchive(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, fmt.Sprintf("Failed to archive emails: %v", err), http.StatusInternalServerError)
 		return
 	}
+	s.invalidateInboxCache()
 
 	response := map[string]interface{}{
 		"success": true,
@@ -194,6 +203,7 @@ func (s *Server) handleUnarchive(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, fmt.Sprintf("Failed to unarchive emails: %v", err), http.StatusInternalServerError)
 		return
 	}
+	s.invalidateInboxCache()
 
 	response := map[string]interface{}{
 		"success": true,
@@ -209,3 +219,36 @@ func (s *Server) handleClear(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	json.NewEncoder(w).Encode(map[string]interface{}{"success": true})
 }
+
+// getInboxForSimilarity returns the cached inbox slice used by /api/similar.
+// The cache avoids re-fetching 1000 emails over JMAP on every click of "Find
+// Similar" or every iteration of the rapid "Archive & Find Next" sweep.
+// handleArchive and handleUnarchive invalidate it so the next call sees the
+// post-archive state.
+func (s *Server) getInboxForSimilarity() ([]jmap.Email, error) {
+	s.inboxMu.Lock()
+	if s.inboxCache != nil && time.Since(s.inboxCachedAt) < inboxCacheTTL {
+		cached := s.inboxCache
+		s.inboxMu.Unlock()
+		return cached, nil
+	}
+	s.inboxMu.Unlock()
+
+	emails, err := s.jmapClient.GetInboxEmails(1000)
+	if err != nil {
+		return nil, err
+	}
+
+	s.inboxMu.Lock()
+	s.inboxCache = emails
+	s.inboxCachedAt = time.Now()
+	s.inboxMu.Unlock()
+	return emails, nil
+}
+
+func (s *Server) invalidateInboxCache() {
+	s.inboxMu.Lock()
+	s.inboxCache = nil
+	s.inboxCachedAt = time.Time{}
+	s.inboxMu.Unlock()
+}

internal/server/server_test.go

@@ -3,13 +3,15 @@ package server
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"mailboxzero/internal/config"
 	"mailboxzero/internal/jmap"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"strings"
 	"testing"
+	"time"
 )
 
 // setupTestServer creates a test server with mock JMAP client
@@ -826,3 +828,219 @@ func TestServer_ConfigValues(t *testing.T) {
 		t.Errorf("Test server DefaultSimilarity = %v, want 75", server.config.DefaultSimilarity)
 	}
 }
+
+// countingJMAPClient wraps a JMAPClient and counts how many times the
+// full 1000-email inbox fetch used by handleFindSimilar is invoked.
+type countingJMAPClient struct {
+	jmap.JMAPClient
+	getInboxCalls int
+}
+
+func (c *countingJMAPClient) GetInboxEmails(limit int) ([]jmap.Email, error) {
+	c.getInboxCalls++
+	return c.JMAPClient.GetInboxEmails(limit)
+}
+
+func setupCountingTestServer(t *testing.T) (*Server, *countingJMAPClient) {
+	t.Helper()
+
+	cfg := &config.Config{
+		Server: struct {
+			Port int    `yaml:"port"`
+			Host string `yaml:"host"`
+		}{Port: 8080, Host: "localhost"},
+		DryRun:            true,
+		DefaultSimilarity: 75,
+		MockMode:          true,
+	}
+
+	counter := &countingJMAPClient{JMAPClient: jmap.NewMockClient()}
+
+	tmpDir := t.TempDir()
+	templatePath := tmpDir + "/web/templates"
+	if err := os.MkdirAll(templatePath, 0755); err != nil {
+		t.Fatalf("Failed to create template directory: %v", err)
+	}
+	if err := os.WriteFile(templatePath+"/index.html", []byte("<html></html>"), 0644); err != nil {
+		t.Fatalf("Failed to write template file: %v", err)
+	}
+
+	oldWd, _ := os.Getwd()
+	os.Chdir(tmpDir)
+	t.Cleanup(func() { os.Chdir(oldWd) })
+
+	server, err := New(cfg, counter)
+	if err != nil {
+		t.Fatalf("Failed to create server: %v", err)
+	}
+
+	return server, counter
+}
+
+func TestHandleFindSimilar_CachesInbox(t *testing.T) {
+	server, counter := setupCountingTestServer(t)
+
+	body, _ := json.Marshal(SimilarRequest{SimilarityThreshold: 75.0})
+	for i := 0; i < 3; i++ {
+		req := httptest.NewRequest("POST", "/api/similar", bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		server.handleFindSimilar(w, req)
+		if w.Code != http.StatusOK {
+			t.Fatalf("call %d: status = %v, want 200", i, w.Code)
+		}
+	}
+
+	if counter.getInboxCalls != 1 {
+		t.Errorf("expected 1 inbox fetch across 3 calls, got %d", counter.getInboxCalls)
+	}
+}
+
+func TestHandleArchive_InvalidatesInboxCache(t *testing.T) {
+	server, counter := setupCountingTestServer(t)
+
+	body, _ := json.Marshal(SimilarRequest{SimilarityThreshold: 75.0})
+	req := httptest.NewRequest("POST", "/api/similar", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	server.handleFindSimilar(httptest.NewRecorder(), req)
+
+	if counter.getInboxCalls != 1 {
+		t.Fatalf("setup: expected 1 inbox fetch, got %d", counter.getInboxCalls)
+	}
+
+	// Archive an arbitrary id — under dry-run this is a no-op against the mock
+	// but the handler still invalidates the cache.
+	archiveBody, _ := json.Marshal(ArchiveRequest{EmailIDs: []string{"email-0-0"}})
+	archiveReq := httptest.NewRequest("POST", "/api/archive", bytes.NewReader(archiveBody))
+	archiveReq.Header.Set("Content-Type", "application/json")
+	archiveW := httptest.NewRecorder()
+	server.handleArchive(archiveW, archiveReq)
+	if archiveW.Code != http.StatusOK {
+		t.Fatalf("archive status = %v, want 200", archiveW.Code)
+	}
+
+	// Next /api/similar should re-fetch.
+	req2 := httptest.NewRequest("POST", "/api/similar", bytes.NewReader(body))
+	req2.Header.Set("Content-Type", "application/json")
+	server.handleFindSimilar(httptest.NewRecorder(), req2)
+
+	if counter.getInboxCalls != 2 {
+		t.Errorf("expected 2 inbox fetches after archive, got %d", counter.getInboxCalls)
+	}
+}
+
+func TestGetInboxForSimilarity_TTLExpiration(t *testing.T) {
+	server, counter := setupCountingTestServer(t)
+
+	body, _ := json.Marshal(SimilarRequest{SimilarityThreshold: 75.0})
+	req := httptest.NewRequest("POST", "/api/similar", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	server.handleFindSimilar(httptest.NewRecorder(), req)
+
+	if counter.getInboxCalls != 1 {
+		t.Fatalf("setup: expected 1 inbox fetch, got %d", counter.getInboxCalls)
+	}
+
+	// Backdate the cache timestamp past the TTL window so the next call
+	// must re-fetch instead of serving stale data indefinitely.
+	server.inboxMu.Lock()
+	server.inboxCachedAt = time.Now().Add(-2 * inboxCacheTTL)
+	server.inboxMu.Unlock()
+
+	req2 := httptest.NewRequest("POST", "/api/similar", bytes.NewReader(body))
+	req2.Header.Set("Content-Type", "application/json")
+	server.handleFindSimilar(httptest.NewRecorder(), req2)
+
+	if counter.getInboxCalls != 2 {
+		t.Errorf("expected 2 inbox fetches after TTL expiration, got %d", counter.getInboxCalls)
+	}
+}
+
+// erroringJMAPClient always fails on GetInboxEmails; the embedded JMAPClient
+// supplies stub implementations for every other interface method via the mock.
+type erroringJMAPClient struct {
+	jmap.JMAPClient
+	calls int
+	err   error
+}
+
+func (c *erroringJMAPClient) GetInboxEmails(limit int) ([]jmap.Email, error) {
+	c.calls++
+	return nil, c.err
+}
+
+func TestGetInboxForSimilarity_ErrorNotCached(t *testing.T) {
+	cfg := &config.Config{
+		Server: struct {
+			Port int    `yaml:"port"`
+			Host string `yaml:"host"`
+		}{Port: 8080, Host: "localhost"},
+		DryRun:            true,
+		DefaultSimilarity: 75,
+		MockMode:          true,
+	}
+
+	failing := &erroringJMAPClient{
+		JMAPClient: jmap.NewMockClient(),
+		err:        errors.New("jmap transient failure"),
+	}
+
+	tmpDir := t.TempDir()
+	templatePath := tmpDir + "/web/templates"
+	if err := os.MkdirAll(templatePath, 0755); err != nil {
+		t.Fatalf("Failed to create template directory: %v", err)
+	}
+	if err := os.WriteFile(templatePath+"/index.html", []byte("<html></html>"), 0644); err != nil {
+		t.Fatalf("Failed to write template file: %v", err)
+	}
+
+	oldWd, _ := os.Getwd()
+	os.Chdir(tmpDir)
+	t.Cleanup(func() { os.Chdir(oldWd) })
+
+	server, err := New(cfg, failing)
+	if err != nil {
+		t.Fatalf("Failed to create server: %v", err)
+	}
+
+	body, _ := json.Marshal(SimilarRequest{SimilarityThreshold: 75.0})
+
+	// Both calls must propagate the JMAP error (HTTP 500) AND make their own
+	// underlying fetch. Caching a nil/empty result on error would poison the
+	// cache for the full TTL window after a single transient failure.
+	for i := 0; i < 2; i++ {
+		req := httptest.NewRequest("POST", "/api/similar", bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		server.handleFindSimilar(w, req)
+		if w.Code != http.StatusInternalServerError {
+			t.Errorf("call %d: status = %v, want 500", i, w.Code)
+		}
+	}
+
+	if failing.calls != 2 {
+		t.Errorf("expected 2 underlying fetches across 2 failing /api/similar calls, got %d", failing.calls)
+	}
+}
+
+func TestHandleUnarchive_InvalidatesInboxCache(t *testing.T) {
+	server, counter := setupCountingTestServer(t)
+
+	body, _ := json.Marshal(SimilarRequest{SimilarityThreshold: 75.0})
+	req := httptest.NewRequest("POST", "/api/similar", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	server.handleFindSimilar(httptest.NewRecorder(), req)
+
+	unarchiveBody, _ := json.Marshal(ArchiveRequest{EmailIDs: []string{"email-0-0"}})
+	unarchiveReq := httptest.NewRequest("POST", "/api/unarchive", bytes.NewReader(unarchiveBody))
+	unarchiveReq.Header.Set("Content-Type", "application/json")
+	server.handleUnarchive(httptest.NewRecorder(), unarchiveReq)
+
+	req2 := httptest.NewRequest("POST", "/api/similar", bytes.NewReader(body))
+	req2.Header.Set("Content-Type", "application/json")
+	server.handleFindSimilar(httptest.NewRecorder(), req2)
+
+	if counter.getInboxCalls != 2 {
+		t.Errorf("expected 2 inbox fetches after unarchive, got %d", counter.getInboxCalls)
+	}
+}