perf(contacts): bound thread contact lookups

Fetch and cache only phone numbers present in the current thread page.
Keep cache entries consistent across mutations and include the staged
contact form UX updates.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: ffe6b904-8f76-4e89-a786-d07a0cc9096d

Author: AchoArnold

api/pkg/di/container.go

@@ -84,18 +84,20 @@ import (
 
 // Container is used to resolve services at runtime
 type Container struct {
-	projectID            string
-	db                   *gorm.DB
-	dedicatedDB          *gorm.DB
-	mongoDB              *mongoDriver.Database
-	version              string
-	app                  *fiber.App
-	eventDispatcher      *services.EventDispatcher
-	logger               telemetry.Logger
-	attachmentRepository repositories.AttachmentRepository
-	userRistrettoCache   *ristretto.Cache[string, entities.AuthContext]
-	phoneRistrettoCache  *ristretto.Cache[string, *entities.Phone]
-	inMemoryCache        cache.Cache
+	projectID             string
+	db                    *gorm.DB
+	dedicatedDB           *gorm.DB
+	mongoDB               *mongoDriver.Database
+	version               string
+	app                   *fiber.App
+	eventDispatcher       *services.EventDispatcher
+	logger                telemetry.Logger
+	attachmentRepository  repositories.AttachmentRepository
+	contactService        *services.ContactService
+	userRistrettoCache    *ristretto.Cache[string, entities.AuthContext]
+	phoneRistrettoCache   *ristretto.Cache[string, *entities.Phone]
+	contactRistrettoCache *ristretto.Cache[string, services.ContactCacheEntry]
+	inMemoryCache         cache.Cache
 }
 
 // NewLiteContainer creates a Container without any routes or listeners
@@ -1152,13 +1154,17 @@ func (container *Container) MessageThreadService() (service *services.MessageThr
 
 // ContactService creates a new instance of services.ContactService
 func (container *Container) ContactService() (service *services.ContactService) {
+	if container.contactService != nil {
+		return container.contactService
+	}
 	container.logger.Debug(fmt.Sprintf("creating %T", service))
-	return services.NewContactService(
+	container.contactService = services.NewContactService(
 		container.Logger(),
 		container.Tracer(),
 		container.ContactRepository(),
-		container.InMemoryCache(),
+		container.ContactRistrettoCache(),
 	)
+	return container.contactService
 }
 
 // EmailNotificationService creates a new instance of services.EmailNotificationService
@@ -1841,6 +1847,24 @@ func (container *Container) PhoneRistrettoCache() *ristretto.Cache[string, *enti
 	return container.phoneRistrettoCache
 }
 
+// ContactRistrettoCache creates an in-memory cache keyed by user and phone number.
+func (container *Container) ContactRistrettoCache() *ristretto.Cache[string, services.ContactCacheEntry] {
+	if container.contactRistrettoCache != nil {
+		return container.contactRistrettoCache
+	}
+	container.logger.Debug(fmt.Sprintf("creating %T", container.contactRistrettoCache))
+	ristrettoCache, err := ristretto.NewCache[string, services.ContactCacheEntry](&ristretto.Config[string, services.ContactCacheEntry]{
+		MaxCost:     5000,
+		NumCounters: 5000 * 10,
+		BufferItems: 64,
+	})
+	if err != nil {
+		container.logger.Fatal(stacktrace.Propagatef(err, "cannot create contact ristretto cache"))
+	}
+	container.contactRistrettoCache = ristrettoCache
+	return container.contactRistrettoCache
+}
+
 // UserRistrettoCache creates an in-memory *ristretto.Cache[string, entities.AuthContext]
 func (container *Container) UserRistrettoCache() *ristretto.Cache[string, entities.AuthContext] {
 	if container.userRistrettoCache != nil {

api/pkg/handlers/contact_handler.go

@@ -254,8 +254,9 @@ func (h *ContactHandler) Update(c fiber.Ctx) error {
 		return h.responseInternalServerError(c)
 	}
 
+	previousPhoneNumbers := append([]string{}, contact.PhoneNumbers...)
 	sanitized.ApplyTo(contact)
-	if err = h.service.Update(ctx, contact); err != nil {
+	if err = h.service.Update(ctx, contact, previousPhoneNumbers); err != nil {
 		ctxLogger.Error(stacktrace.Propagatef(err, "cannot update contact [%s] for user [%s]", contactID, userID))
 		return h.responseInternalServerError(c)
 	}

api/pkg/handlers/contact_handler_test.go

@@ -14,18 +14,17 @@ import (
 	"testing"
 	"time"
 
-	"github.com/NdoleStudio/httpsms/pkg/cache"
 	"github.com/NdoleStudio/httpsms/pkg/entities"
 	"github.com/NdoleStudio/httpsms/pkg/middlewares"
 	"github.com/NdoleStudio/httpsms/pkg/repositories"
 	"github.com/NdoleStudio/httpsms/pkg/services"
 	"github.com/NdoleStudio/httpsms/pkg/telemetry"
 	"github.com/NdoleStudio/httpsms/pkg/validators"
 	"github.com/NdoleStudio/stacktrace"
+	"github.com/dgraph-io/ristretto/v2"
 	"github.com/gofiber/fiber/v3"
 	"github.com/google/uuid"
 	"github.com/lib/pq"
-	ttlCache "github.com/patrickmn/go-cache"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"gorm.io/gorm"
@@ -122,7 +121,7 @@ func (r *contactHandlerFakeRepo) Count(_ context.Context, _ entities.UserID, par
 	return r.countResult, nil
 }
 
-func (r *contactHandlerFakeRepo) FetchAll(context.Context, entities.UserID) (*[]entities.Contact, error) {
+func (r *contactHandlerFakeRepo) FetchByPhoneNumbers(context.Context, entities.UserID, []string) (*[]entities.Contact, error) {
 	out := []entities.Contact{}
 	return &out, nil
 }
@@ -170,8 +169,13 @@ func newContactHandlerTestAppWithEntitlements(
 ) *fiber.App {
 	logger := &messageThreadHandlerNoopLogger{}
 	tracer := telemetry.NewOtelLogger("test", logger)
-	appCache := cache.NewMemoryCache(tracer, ttlCache.New(time.Minute, time.Minute))
-	service := services.NewContactService(logger, tracer, repo, appCache)
+	contactCache, err := ristretto.NewCache[string, services.ContactCacheEntry](&ristretto.Config[string, services.ContactCacheEntry]{
+		MaxCost: 100, NumCounters: 1_000, BufferItems: 64,
+	})
+	if err != nil {
+		panic(err)
+	}
+	service := services.NewContactService(logger, tracer, repo, contactCache)
 	entitlementService := services.NewEntitlementService(
 		logger,
 		tracer,
@@ -640,8 +644,12 @@ func TestContactHandler_Index_InvalidLimit_ReturnsUnprocessableEntity(t *testing
 func TestContactService_WiresIntoMessageThreadService(t *testing.T) {
 	logger := &messageThreadHandlerNoopLogger{}
 	tracer := telemetry.NewOtelLogger("test", logger)
-	appCache := cache.NewMemoryCache(tracer, ttlCache.New(time.Minute, time.Minute))
-	contactService := services.NewContactService(logger, tracer, &contactHandlerFakeRepo{}, appCache)
+	contactCache, err := ristretto.NewCache[string, services.ContactCacheEntry](&ristretto.Config[string, services.ContactCacheEntry]{
+		MaxCost: 100, NumCounters: 1_000, BufferItems: 64,
+	})
+	require.NoError(t, err)
+	t.Cleanup(contactCache.Close)
+	contactService := services.NewContactService(logger, tracer, &contactHandlerFakeRepo{}, contactCache)
 
 	// If this compiles and runs, the ContactService satisfies the
 	// contactMapProvider interface expected by NewMessageThreadService.

api/pkg/handlers/message_thread_handler_contacts_test.go

@@ -36,7 +36,7 @@ type messageThreadHandlerContactProviderStub struct {
 	calls    int
 }
 
-func (stub *messageThreadHandlerContactProviderStub) GetContactMap(context.Context, entities.UserID) (map[string]*entities.Contact, error) {
+func (stub *messageThreadHandlerContactProviderStub) GetContactMap(context.Context, entities.UserID, []string) (map[string]*entities.Contact, error) {
 	stub.calls++
 	return stub.contacts, nil
 }

api/pkg/repositories/contact_repository.go

@@ -25,8 +25,9 @@ type ContactRepository interface {
 	// name/emails/phone_numbers filter as Index, ignoring pagination.
 	Count(ctx context.Context, userID entities.UserID, params IndexParams) (int64, error)
 
-	// FetchAll returns every contact for a user ordered by updated_at ascending.
-	FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error)
+	// FetchByPhoneNumbers returns contacts containing at least one requested
+	// phone number, ordered by updated_at ascending.
+	FetchByPhoneNumbers(ctx context.Context, userID entities.UserID, phoneNumbers []string) (*[]entities.Contact, error)
 
 	// Delete a contact by ID for a user.
 	Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error

api/pkg/repositories/gorm_contact_repository.go

@@ -10,6 +10,7 @@ import (
 	"github.com/NdoleStudio/httpsms/pkg/telemetry"
 	"github.com/NdoleStudio/stacktrace"
 	"github.com/google/uuid"
+	"github.com/lib/pq"
 	"gorm.io/gorm"
 )
 
@@ -143,16 +144,17 @@ func (repository *gormContactRepository) Count(ctx context.Context, userID entit
 	return count, nil
 }
 
-func (repository *gormContactRepository) FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error) {
+func (repository *gormContactRepository) FetchByPhoneNumbers(ctx context.Context, userID entities.UserID, phoneNumbers []string) (*[]entities.Contact, error) {
 	ctx, span := repository.tracer.Start(ctx)
 	defer span.End()
 
 	contacts := new([]entities.Contact)
 	if err := repository.db.WithContext(ctx).
 		Where("user_id = ?", userID).
+		Where("phone_numbers && ?", pq.Array(phoneNumbers)).
 		Order("updated_at ASC").
 		Find(contacts).Error; err != nil {
-		return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch all contacts for user [%s]", userID))
+		return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch contacts for user [%s] by phone numbers [%v]", userID, phoneNumbers))
 	}
 
 	return contacts, nil

api/pkg/repositories/gorm_contact_repository_test.go

@@ -321,16 +321,21 @@ func TestGormContactRepository_Index_OrdersByRequestedFieldAndDirection(t *testi
 	}
 }
 
-func TestGormContactRepository_FetchAll_ScopesByUserAndOrdersUpdatedAtAsc(t *testing.T) {
+func TestGormContactRepository_FetchByPhoneNumbers_ScopesByUserAndRequestedNumbers(t *testing.T) {
 	repository, recorder := newContactTestRepo(t)
 
-	_, err := repository.FetchAll(context.Background(), entities.UserID("user-1"))
+	_, err := repository.FetchByPhoneNumbers(
+		context.Background(),
+		entities.UserID("user-1"),
+		[]string{"+18005550199", "+18005550100"},
+	)
 
 	require.NoError(t, err)
 	statement := lastContactStatement(t, recorder)
-	assert.Equal(t, `SELECT * FROM "contacts" WHERE user_id = $1 ORDER BY updated_at ASC`, statement.query)
-	require.Len(t, statement.args, 1)
+	assert.Equal(t, `SELECT * FROM "contacts" WHERE user_id = $1 AND phone_numbers && $2 ORDER BY updated_at ASC`, statement.query)
+	require.Len(t, statement.args, 2)
 	assert.Equal(t, entities.UserID("user-1"), statement.args[0])
+	assert.Equal(t, &pq.StringArray{"+18005550199", "+18005550100"}, statement.args[1])
 }
 
 func TestGormContactRepository_Delete_ScopesByUserAndContactID(t *testing.T) {