perf(marketplace): fetch search pages concurrently (~5x faster deep scans)

Keyword search has to scan the catalog (the Content API has no server-side
filter), and a rare/multi-word query forced a ~23-page sequential walk — ~3m45s
in a high-latency environment, slow enough that callers thought it had hung.

Search now fetches the first page alone (so a common early match stays a single
request) then ramps to concurrent batches (errgroup, bounded at
searchConcurrency=8) for the deep-scan tail, preserving catalog order and the
stop-at-limit / stop-at-end-of-catalog semantics. Measured ~3m45s -> ~44s on a
slow link (network-bound; ~5x); near-instant on a normal link.

Tests (race-clean): first-page-alone keeps the common case to one request;
pagination still finds a second-page match; end-of-catalog stops early.
Promotes golang.org/x/sync to a direct dependency.

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

Author: ako

go.mod

@@ -26,6 +26,7 @@ require (
 	go.mongodb.org/mongo-driver v1.17.9
 	go.starlark.net v0.0.0-20260102030733-3fee463870c9
 	go.uber.org/zap v1.28.0
+	golang.org/x/sync v0.20.0
 	golang.org/x/term v0.43.0
 	gopkg.in/yaml.v3 v3.0.1
 	modernc.org/sqlite v1.51.0
@@ -69,7 +70,6 @@ require (
 	go.uber.org/multierr v1.10.0 // indirect
 	golang.org/x/crypto v0.50.0 // indirect
 	golang.org/x/exp v0.0.0-20251023183803-a4bb9ffd2546 // indirect
-	golang.org/x/sync v0.20.0 // indirect
 	golang.org/x/sys v0.44.0 // indirect
 	golang.org/x/text v0.36.0 // indirect
 	modernc.org/libc v1.72.3 // indirect

internal/marketplace/client.go

@@ -11,6 +11,8 @@ import (
 	"net/url"
 	"strconv"
 	"strings"
+
+	"golang.org/x/sync/errgroup"
 )
 
 const (
@@ -24,6 +26,10 @@ const (
 	// (End-of-catalog normally terminates the loop first: an offset past the
 	// end returns a short/empty page.)
 	maxSearchPages = 50
+	// searchConcurrency bounds how many catalog pages are fetched in parallel
+	// during a deep keyword scan (the first page is always fetched alone so a
+	// common early match stays a single request).
+	searchConcurrency = 8
 )
 
 // Client is a typed wrapper around the marketplace REST API. Callers
@@ -72,20 +78,40 @@ func (c *Client) Search(ctx context.Context, query string, limit int) (*ContentL
 		return &out, nil
 	}
 
+	// Fetch the first page alone so a common query that matches early costs a
+	// single request, then ramp to concurrent batches so a rare/deep match
+	// (near-full scan) is a handful of round-trips instead of ~23 sequential
+	// ones. Stops at `limit` matches or end-of-catalog (a short page).
 	var matched []Content
-	for page := range maxSearchPages {
-		items, err := c.fetchContentPage(ctx, page*pageSize)
+	for page := 0; page < maxSearchPages; {
+		batch := searchConcurrency
+		if page == 0 {
+			batch = 1
+		}
+		if page+batch > maxSearchPages {
+			batch = maxSearchPages - page
+		}
+
+		pages, err := c.fetchPages(ctx, page, batch)
 		if err != nil {
 			return nil, err
 		}
-		matched = append(matched, filterItems(items, query)...)
+
+		endReached := false
+		for _, items := range pages {
+			matched = append(matched, filterItems(items, query)...)
+			if len(items) < pageSize {
+				endReached = true
+			}
+		}
 		if limit > 0 && len(matched) >= limit {
 			matched = matched[:limit]
 			break
 		}
-		if len(items) < pageSize {
-			break // reached the end of the catalog
+		if endReached {
+			break
 		}
+		page += batch
 	}
 	return &ContentList{Items: matched}, nil
 }
@@ -101,6 +127,28 @@ func (c *Client) fetchContentPage(ctx context.Context, offset int) ([]Content, e
 	return out.Items, nil
 }
 
+// fetchPages fetches n catalog pages starting at startPage concurrently and
+// returns them in page order (so client-side filtering preserves catalog order).
+func (c *Client) fetchPages(ctx context.Context, startPage, n int) ([][]Content, error) {
+	results := make([][]Content, n)
+	g, gctx := errgroup.WithContext(ctx)
+	g.SetLimit(searchConcurrency)
+	for i := range n {
+		g.Go(func() error {
+			items, err := c.fetchContentPage(gctx, (startPage+i)*pageSize)
+			if err != nil {
+				return err
+			}
+			results[i] = items
+			return nil
+		})
+	}
+	if err := g.Wait(); err != nil {
+		return nil, err
+	}
+	return results, nil
+}
+
 // filterItems returns items whose name or publisher contains query
 // (case-insensitive substring match).
 func filterItems(items []Content, query string) []Content {

internal/marketplace/client_test.go

@@ -9,6 +9,7 @@ import (
 	"net/http/httptest"
 	"strconv"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 )
@@ -143,10 +144,13 @@ func contentPage(startID, n int, special string) string {
 // page (offset=100) must still be found. The server returns a full page of 100
 // non-matching items at offset 0, and the match at offset 100.
 func TestSearch_PaginatesPastFirstPage(t *testing.T) {
-	var offsetsSeen []string
+	var mu sync.Mutex
+	offsetsSeen := map[string]bool{}
 	client, _ := newMockServer(t, func(w http.ResponseWriter, r *http.Request) {
 		off := r.URL.Query().Get("offset")
-		offsetsSeen = append(offsetsSeen, off)
+		mu.Lock()
+		offsetsSeen[off] = true
+		mu.Unlock()
 		switch off {
 		case "0":
 			_, _ = w.Write([]byte(contentPage(1, 100, ""))) // full page, no match
@@ -164,9 +168,35 @@ func TestSearch_PaginatesPastFirstPage(t *testing.T) {
 	if len(result.Items) != 1 || result.Items[0].ContentID != 999999 {
 		t.Fatalf("expected the second-page match (999999), got %+v", result.Items)
 	}
-	// It must have advanced past the first page (offset 0 was a full 100).
-	if len(offsetsSeen) < 2 || offsetsSeen[1] != "100" {
-		t.Errorf("expected pagination to request offset=100; offsets seen: %v", offsetsSeen)
+	// It must have advanced past the first page (offset 0 was a full 100) and
+	// requested the second page where the match lives. The second batch is
+	// fetched concurrently, so order is not asserted.
+	mu.Lock()
+	defer mu.Unlock()
+	if !offsetsSeen["0"] || !offsetsSeen["100"] {
+		t.Errorf("expected requests at offset 0 and 100; offsets seen: %v", offsetsSeen)
+	}
+}
+
+// TestSearch_FirstPageAlone: when enough matches appear on the first (full)
+// page, search stops there — a single request — without firing the concurrent
+// follow-on batch. This keeps the common case fast.
+func TestSearch_FirstPageAlone(t *testing.T) {
+	var calls int
+	client, _ := newMockServer(t, func(w http.ResponseWriter, _ *http.Request) {
+		calls++
+		// A full page (pageSize items) that includes a match for "filler".
+		_, _ = w.Write([]byte(contentPage(1, pageSize, "")))
+	})
+	res, err := client.Search(context.Background(), "filler", 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Items) != 1 {
+		t.Errorf("expected limit=1 to return 1 match, got %d", len(res.Items))
+	}
+	if calls != 1 {
+		t.Errorf("expected exactly 1 request when the limit is met on page 0, got %d", calls)
 	}
 }