feat: accept X-PEER-ID peer hint for content retrieval

- Parse peer multiaddress from X-PEER-ID and best-effort connect (5s timeout)
- Middleware wired into gateway handler; non-blocking on failure
- Improves Bitswap fetches and aligns with Pinning Service API “origins”

Author: acejam

handlers.go

@@ -9,6 +9,7 @@ import (
 	"runtime"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/ipfs/boxo/blockstore"
 	leveldb "github.com/ipfs/go-ds-leveldb"
@@ -393,6 +394,9 @@ func setupGatewayHandler(cfg Config, nd *Node) (http.Handler, error) {
 	// Add tracing.
 	handler = withTracingAndDebug(handler, cfg.TracingAuthToken)
 
+	// Add peer hint support (X-PEER-ID).
+	handler = withPeerHint(nd, handler)
+
 	return handler, nil
 }
 
@@ -429,6 +433,34 @@ const NoBlockcacheHeader = "Rainbow-No-Blockcache"
 
 type NoBlockcache struct{}
 
+const PeerHintHeader = "X-PEER-ID"
+
+// withPeerHint inspects the request for a Peer hint header and, if present,
+// attempts a short, best-effort libp2p connect to the provided multiaddress.
+// This increases the likelihood that Bitswap can retrieve content directly
+// from the hinted peer even if it is not advertising on DHT/IPNI.
+func withPeerHint(nd *Node, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if nd != nil && nd.host != nil {
+			if maStr := r.Header.Get(PeerHintHeader); maStr != "" {
+				if ai, err := peer.AddrInfoFromString(maStr); err != nil {
+					goLog.Warnw("Invalid X-PEER-ID header", "value", maStr, "err", err)
+				} else {
+					ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+					defer cancel()
+					// Best-effort connect; do not fail the request on error.
+					if err := nd.host.Connect(ctx, *ai); err != nil {
+						goLog.Debugw("Failed to connect to hinted peer", "peer", ai.ID, "err", err)
+					} else {
+						goLog.Debugw("Connected to hinted peer", "peer", ai.ID)
+					}
+				}
+			}
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
 // MutexFractionOption allows to set runtime.SetMutexProfileFraction via HTTP
 // using POST request with parameter 'fraction'.
 func MutexFractionOption(path string, mux *http.ServeMux) *http.ServeMux {