pool: address Copilot review comments for hotfile migration pool selection

- Per #8049 (review)
- Log cache-entry lookup failures with stack trace (pass exception
  object to `LOGGER.warn`, not just `e.getMessage()`)
- Handle `null` `ProtocolInfo` in reportFileRequest: fall back to
  protocol unit "*/*" and empty net unit name instead of throwing NPE
- Ensure `netUnitName` is always non-`null`: use client IP address when
  available via `IpProtocolInfo`, otherwise empty string; guard against
  `null` socket address/inet address
- Enforce non-`null` `netUnitName` in `PoolListByPoolMgrQuery` constructor
  via `requireNonNull` (consistent with `PoolMgrQueryPoolsMsg` requirement)
- Annotate ProtocolInfo parameter as `@Nullable` in FileRequestMonitor
  interface to document that `null` is a valid input
- Update tests: replace `null` `netUnitName` with "" throughout;
  rename `testRefreshWithNullNetUnitName` to `testRefreshWithUnknownNetUnitName`
  and assert empty string is passed; remove now-unused `assertNull` import
- Update `hotfile-replication.md`: fix `reportFileRequest` snippet to
  include `protocolInfo` argument; update pool-selection description to
  reflect protocol/net unit derivation from `ProtocolInfo` instead of `null`

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

Author: greenc-FNAL

docs/dev/hotfile-replication.md

@@ -18,7 +18,7 @@ Any Door (DCap / NFS / WebDAV / xrootd / FTP / HTTP / …)
     → Pool.messageArrived(PoolIoFileMessage)
       → PoolV4.ioFile()          ← monitoring happens here
         → queues mover (protocol-specific)
-        → FileRequestMonitor.reportFileRequest(pnfsId, currentCount)
+        → FileRequestMonitor.reportFileRequest(pnfsId, currentCount, protocolInfo)
 ```
 
 Because the counting and triggering happen in `PoolV4.ioFile()`, no protocol-specific code
@@ -30,7 +30,8 @@ changes are required to benefit from this feature.
 
 ```java
 long requestCount = _ioQueue.numberOfRequestsFor(message.getPnfsId());
-_fileRequestMonitor.reportFileRequest(message.getPnfsId(), requestCount);
+_fileRequestMonitor.reportFileRequest(message.getPnfsId(), requestCount,
+      message.getProtocolInfo());
 ```
 
 When `requestCount` reaches or exceeds the configured threshold,
@@ -40,9 +41,12 @@ When `requestCount` reaches or exceeds the configured threshold,
 ### Pool Selection
 
 The migration job selects target pools by querying PoolManager via `PoolMgrQueryPoolsMsg`,
-using `null` for both `protocolUnit` and `netUnitName`. This means selection is based
-**solely on the file's storage group and pool-group read preferences** — protocol and
-network criteria are intentionally excluded.
+deriving `protocolUnit` from the triggering request's `ProtocolInfo` (e.g., `"DCap/3"`) and
+`netUnitName` from the client's IP address when available (e.g., `"192.168.1.10"`). When the
+client IP is not available (non-IP protocol or unknown), an empty string is used for `netUnitName`,
+which causes PoolManager to match any network unit. When `ProtocolInfo` is null (e.g., for
+internal pool-to-pool transfers), `protocolUnit` falls back to `"*/*"` and `netUnitName` to `""`
+so that selection is based solely on the file's storage group and pool-group read preferences.
 
 `PoolMgrQueryPoolsMsg.getPools()` returns a `List<String>[]` where index 0 is the highest
 read-preference level. `PoolListByPoolMgrQuery` selects **only** the first non-empty

modules/dcache/src/main/java/org/dcache/pool/classic/FileRequestMonitor.java

@@ -2,6 +2,7 @@
 
 import diskCacheV111.util.PnfsId;
 import diskCacheV111.vehicles.ProtocolInfo;
+import javax.annotation.Nullable;
 
 /**
  * Abstract interface for monitoring file requests in the pool.
@@ -13,8 +14,9 @@ public interface FileRequestMonitor {
      *
      * @param pnfsId           the file identifier
      * @param numberOfRequests the number of requests for this file
-     * @param protocolInfo     the protocol info of the request
+     * @param protocolInfo     the protocol info of the request, may be {@code null} if unknown
      */
-    void reportFileRequest(PnfsId pnfsId, long numberOfRequests, ProtocolInfo protocolInfo);
+    void reportFileRequest(PnfsId pnfsId, long numberOfRequests,
+          @Nullable ProtocolInfo protocolInfo);
 }
 

modules/dcache/src/main/java/org/dcache/pool/migration/MigrationModule.java

@@ -1278,20 +1278,34 @@ public synchronized void reportFileRequest(PnfsId pnfsId, long numberOfRequests,
             try {
                 cacheEntry = _context.getRepository().getEntry(pnfsId);
             } catch (Exception e) {
-                LOGGER.warn("Failed to get cache entry for {}: {}", pnfsId, e.getMessage());
+                LOGGER.warn("Failed to get cache entry for {}: {}", pnfsId, e.getMessage(), e);
                 return;
             }
             FileAttributes fileAttributes = cacheEntry.getFileAttributes();
 
-            String protocolUnit = protocolInfo.getProtocol() + "/" + protocolInfo.getMajorVersion();
-            if (protocolInfo.getMinorVersion() != 0) {
-                protocolUnit += "." + protocolInfo.getMinorVersion();
-            }
-
-            String netUnitName = null;
-            if (protocolInfo instanceof IpProtocolInfo) {
-                netUnitName = ((IpProtocolInfo) protocolInfo).getSocketAddress().getAddress()
-                      .getHostAddress();
+            String protocolUnit;
+            String netUnitName;
+            if (protocolInfo != null) {
+                protocolUnit = protocolInfo.getProtocol() + "/" + protocolInfo.getMajorVersion();
+                if (protocolInfo.getMinorVersion() != 0) {
+                    protocolUnit += "." + protocolInfo.getMinorVersion();
+                }
+                if (protocolInfo instanceof IpProtocolInfo) {
+                    IpProtocolInfo ipProtocolInfo = (IpProtocolInfo) protocolInfo;
+                    if (ipProtocolInfo.getSocketAddress() != null
+                          && ipProtocolInfo.getSocketAddress().getAddress() != null) {
+                        netUnitName = ipProtocolInfo.getSocketAddress().getAddress()
+                              .getHostAddress();
+                    } else {
+                        netUnitName = "";
+                    }
+                } else {
+                    netUnitName = "";
+                }
+            } else {
+                // Fall back to PoolSelectionUnit default protocol and net units
+                protocolUnit = "*/*";
+                netUnitName = "";
             }
 
             Collection<Pattern> excluded = new HashSet<>();

modules/dcache/src/main/java/org/dcache/pool/migration/PoolListByPoolMgrQuery.java

@@ -46,7 +46,7 @@ class PoolListByPoolMgrQuery
      * @param pnfsId the PNFS ID of the file
      * @param fileAttributes the file attributes for selection
      * @param protocolUnit the protocol unit (e.g., "DCap/3")
-     * @param netUnitName the network unit name (IP address or null)
+     * @param netUnitName the network unit name (IP address of the client, or empty string if unknown)
      */
     public PoolListByPoolMgrQuery(CellStub poolManager,
           PnfsId pnfsId,
@@ -57,7 +57,7 @@ public PoolListByPoolMgrQuery(CellStub poolManager,
         _pnfsId = requireNonNull(pnfsId);
         _fileAttributes = requireNonNull(fileAttributes);
         _protocolUnit = requireNonNull(protocolUnit);
-        _netUnitName = netUnitName;
+        _netUnitName = requireNonNull(netUnitName);
     }
 
     @Override

modules/dcache/src/test/java/org/dcache/pool/migration/PoolListByPoolMgrQueryTest.java

@@ -2,7 +2,6 @@
 
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
-import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.inOrder;
@@ -166,9 +165,9 @@ public void testRefreshWithMissingStorageInfo() {
     }
 
     @Test
-    public void testRefreshWithNullNetUnitName() throws Exception {
+    public void testRefreshWithUnknownNetUnitName() throws Exception {
         PoolListByPoolMgrQuery poolList = new PoolListByPoolMgrQuery(
-              poolManager, pnfsId, fileAttributes, "DCap/3", null);
+              poolManager, pnfsId, fileAttributes, "DCap/3", "");
 
         SettableFuture<PoolMgrQueryPoolsMsg> future = SettableFuture.create();
         when(poolManager.send(any(PoolMgrQueryPoolsMsg.class))).thenReturn(future);
@@ -180,7 +179,7 @@ public void testRefreshWithNullNetUnitName() throws Exception {
         verify(poolManager).send(queryMsgCaptor.capture());
 
         PoolMgrQueryPoolsMsg queryMsg = queryMsgCaptor.getValue();
-        assertNull(queryMsg.getNetUnitName());
+        assertEquals("", queryMsg.getNetUnitName());
     }
 
     /**
@@ -196,7 +195,7 @@ public void testSelectsOnlyHighestPreferenceLevel() throws Exception {
         // Setup: Two pool groups with different read preferences
         // Pool1 is in both groups, pool2-5 only in high-pref group, pool6-10 only in low-pref group
         PoolListByPoolMgrQuery poolList = new PoolListByPoolMgrQuery(
-              poolManager, pnfsId, fileAttributes, "DCap/3", null);
+              poolManager, pnfsId, fileAttributes, "DCap/3", "");
 
         InOrder inOrder = inOrder(poolManager);
 
@@ -222,7 +221,7 @@ public void testSelectsOnlyHighestPreferenceLevel() throws Exception {
         poolLists[1] = Arrays.asList("pool1", "pool6", "pool7", "pool8", "pool9", "pool10"); // Low pref
 
         PoolMgrQueryPoolsMsg response = new PoolMgrQueryPoolsMsg(
-              DirectionType.READ, "DCap/3", null, fileAttributes);
+              DirectionType.READ, "DCap/3", "", fileAttributes);
         response.setPoolList(poolLists);
         response.setSucceeded();
 
@@ -275,7 +274,7 @@ public void testSelectsOnlyHighestPreferenceLevel() throws Exception {
     @Test
     public void testSelectsFirstNonEmptyPreferenceLevel() throws Exception {
         PoolListByPoolMgrQuery poolList = new PoolListByPoolMgrQuery(
-              poolManager, pnfsId, fileAttributes, "DCap/3", null);
+              poolManager, pnfsId, fileAttributes, "DCap/3", "");
 
         InOrder inOrder = inOrder(poolManager);
 
@@ -298,7 +297,7 @@ public void testSelectsFirstNonEmptyPreferenceLevel() throws Exception {
         poolLists[2] = Arrays.asList("pool1", "pool2"); // Lower preference (should be ignored)
 
         PoolMgrQueryPoolsMsg response = new PoolMgrQueryPoolsMsg(
-              DirectionType.READ, "DCap/3", null, fileAttributes);
+              DirectionType.READ, "DCap/3", "", fileAttributes);
         response.setPoolList(poolLists);
         response.setSucceeded();