connector: pace media re-requests instead of firing them in a burst

pkg/connector/backfill.go

@@ -649,14 +649,24 @@ func (wa *WhatsAppClient) convertHistorySyncMessages(
 			wa.deleteHistorySyncMessages(ctx, portalJID, newestTS, oldestTS)
 			if len(mediaRequests) > 0 {
 				go func(ctx context.Context) {
+					immediate := wa.Main.Config.HistorySync.MediaRequests.AutoRequestMedia &&
+						wa.Main.Config.HistorySync.MediaRequests.RequestMethod == MediaRequestMethodImmediate
+					sent := 0
 					for _, req := range mediaRequests {
 						err := wa.Main.DB.MediaRequest.Put(ctx, req)
 						if err != nil {
 							zerolog.Ctx(ctx).Err(err).Msg("Failed to save media request to database")
 						}
-						if wa.Main.Config.HistorySync.MediaRequests.AutoRequestMedia && wa.Main.Config.HistorySync.MediaRequests.RequestMethod == MediaRequestMethodImmediate {
-							wa.sendMediaRequest(ctx, req)
+						if !immediate {
+							continue
 						}
+						// Saved to the database above regardless, so a request that
+						// does not go out now is not lost - the daily sweep sends it.
+						if sent > 0 && !pauseBetweenMediaRequests(ctx) {
+							return
+						}
+						wa.sendMediaRequest(ctx, req)
+						sent++
 					}
 				}(context.WithoutCancel(ctx))
 			}

pkg/connector/mediarequest.go

@@ -17,6 +17,7 @@
 package connector
 
 import (
+	"math/rand/v2"
 	"context"
 	"fmt"
 	"time"
@@ -109,11 +110,33 @@ func (wa *WhatsAppClient) sendMediaRequests(ctx context.Context) {
 		return
 	}
 	zerolog.Ctx(ctx).Info().Int("request_count", len(reqs)).Msg("Sending media requests")
-	for _, req := range reqs {
+	for i, req := range reqs {
+		if i > 0 && !pauseBetweenMediaRequests(ctx) {
+			return
+		}
 		wa.sendMediaRequest(ctx, req)
 	}
 }
 
+// mediaRequestSpacing is the pause between consecutive media re-request
+// stanzas. A phone fetches expired media lazily, one item at a time, as a
+// person scrolls into a chat; it does not fire dozens of requests within a
+// millisecond right after linking. Half a second, with jitter, keeps a burst
+// of a few hundred requests spread over minutes rather than instants.
+const mediaRequestSpacing = 500 * time.Millisecond
+
+// pauseBetweenMediaRequests waits mediaRequestSpacing plus up to 50% jitter.
+// It returns false if the context ended during the wait.
+func pauseBetweenMediaRequests(ctx context.Context) bool {
+	wait := mediaRequestSpacing + time.Duration(rand.Float64()*float64(mediaRequestSpacing)*0.5)
+	select {
+	case <-time.After(wait):
+		return true
+	case <-ctx.Done():
+		return false
+	}
+}
+
 func (wa *WhatsAppClient) sendMediaRequest(ctx context.Context, req *wadb.MediaRequest) {
 	log := zerolog.Ctx(ctx).With().Str("action", "send media request").Str("message_id", string(req.MessageID)).Logger()
 	defer func() {