PVA: Start version 3, encode/decode search flag reply src port

Author: kasemir

core/pva/TLS.md

@@ -39,7 +39,7 @@ This is an example recipe for getting started.
    Note its "Certificate identifier":
 
    ```
-   $ authnstd --name ioc --cert-usage hybrid
+   $ authnstd --name ioc --cert-usage ioc
    Keychain file created   : /home/user/.config/pva/1.3/server.p12
    Certificate identifier  : e53ed409:15273288300286014953
    ```

core/pva/src/main/java/org/epics/pva/client/ClientUDPHandler.java

@@ -87,7 +87,6 @@ public interface SearchResponseHandler
     // with the understanding that it will only receive broadcasts;
     // since they are often blocked by firewall, may receive nothing, ever.
     private final DatagramChannel udp_beacon;
-    private final ByteBuffer beacon_buffer = ByteBuffer.allocate(PVASettings.MAX_UDP_PACKET);
 
     private volatile Thread search_thread4, search_thread6, beacon_thread;
 
@@ -107,13 +106,15 @@ public ClientUDPHandler(final BeaconHandler beacon_handler,
 
         // IPv6 sockets
         // Beacon socket only receives, does not send broadcasts
-        if (PVASettings.EPICS_PVA_ENABLE_IPV6) {
+        if (PVASettings.EPICS_PVA_ENABLE_IPV6)
+        {
             udp_search6 = Network.createUDP(StandardProtocolFamily.INET6, null, 0);
             udp_localaddr6 = (InetSocketAddress) udp_search6.getLocalAddress();
             ipV6Msg = String.format(" and %s", udp_localaddr6);
             udp_beacon = Network.createUDP(StandardProtocolFamily.INET6, null, PVASettings.EPICS_PVA_BROADCAST_PORT);
         }
-        else {
+        else
+        {
             udp_search6 = null;
             udp_beacon = Network.createUDP(StandardProtocolFamily.INET, null, PVASettings.EPICS_PVA_BROADCAST_PORT);
             udp_localaddr6 = null;
@@ -150,11 +151,8 @@ public void send(final ByteBuffer buffer, final AddressInfo info) throws Excepti
         }
         else
         {
-            if (!PVASettings.EPICS_PVA_ENABLE_IPV6) {
-                throw new Exception(
-                    "EPICS_PVA_ENABLE_IPV6 must be enabled to use IPv6 address!"
-                );
-            }
+            if (!PVASettings.EPICS_PVA_ENABLE_IPV6)
+                throw new Exception("EPICS_PVA_ENABLE_IPV6 must be enabled to use IPv6 address!");
 
             synchronized (udp_search6)
             {
@@ -177,13 +175,15 @@ public void start()
         search_thread4.setDaemon(true);
         search_thread4.start();
 
-        if (PVASettings.EPICS_PVA_ENABLE_IPV6) {
+        if (PVASettings.EPICS_PVA_ENABLE_IPV6)
+        {
             final ByteBuffer receive_buffer6 = ByteBuffer.allocate(PVASettings.MAX_UDP_PACKET);
             search_thread6 = new Thread(() -> listen(udp_search6, receive_buffer6), "UDP6-receiver " + Network.getLocalAddress(udp_search6));
             search_thread6.setDaemon(true);
             search_thread6.start();
         }
 
+        final ByteBuffer beacon_buffer = ByteBuffer.allocate(PVASettings.MAX_UDP_PACKET);
         beacon_thread = new Thread(() -> listen(udp_beacon, beacon_buffer), "UDP-beacon-receiver " + Network.getLocalAddress(udp_beacon));
         beacon_thread.setDaemon(true);
         beacon_thread.start();

core/pva/src/main/java/org/epics/pva/common/PVAHeader.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019-2022 Oak Ridge National Laboratory.
+ * Copyright (c) 2019-2025 Oak Ridge National Laboratory.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -26,8 +26,12 @@ public class PVAHeader
     /** PVA protocol magic */
     public static final byte PVA_MAGIC = (byte)0xCA;
 
-    /** PVA protocol revision (implemented by this library) */
-    public static final byte PVA_PROTOCOL_REVISION = 2;
+    /** PVA protocol revision (implemented by this library)
+     * 
+     *  <br>v2: Server's Echo reply includes the request payload
+     *  <br>v3: SearchRequest FLAG_REPLY_SRC_PORT
+     */
+    public static final byte PVA_PROTOCOL_REVISION = 3;
 
     /** Oldest PVA protocol revision handled by this library */
     public static final byte REQUIRED_PVA_PROTOCOL_REVISION = 1;

core/pva/src/main/java/org/epics/pva/common/SearchRequest.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019-2023 Oak Ridge National Laboratory.
+ * Copyright (c) 2019-2025 Oak Ridge National Laboratory.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -63,12 +63,29 @@ public String toString()
         }
     };
 
+    /** Server should reply with its GUID and empty CID list
+     *  even if it does not host any of the searched channels
+     */
+    public static final byte FLAG_SEARCH_MUST_REPLY = 0x01;
+
+    /** Client should ignore the 'port' in the reply and
+     *  simply use the port of the 'source', that is the peer port
+     *  of the UDP message or TCP connection
+     *  @since Version 3
+     */
+    public static final byte FLAG_REPLY_SRC_PORT = 0x02;
+
+    /** Indicates that search message was unicast */
+    public static final byte FLAG_SEARCH_UNICAST    = (byte)0x80;
+
     /** Sequence number */
     public int seq;
     /** Is it a unicast? */
     public boolean unicast;
     /** Is reply required? */
     public boolean reply_required;
+    /** Reply to source port instead of port listed in the search request? */
+    public boolean reply_to_src_port;
     /** Address of client */
     public InetSocketAddress client;
     /** Use TLS, or plain TCP? */
@@ -106,10 +123,10 @@ public static SearchRequest decode(final InetSocketAddress from, final byte vers
         // Search Sequence ID
         search.seq = buffer.getInt();
 
-        // 0-bit for replyRequired, 7-th bit for "sent as unicast" (1)/"sent as broadcast/multicast" (0)
         final byte flags = buffer.get();
-        search.unicast = (flags & 0x80) == 0x80;
-        search.reply_required = (flags & 0x01) == 0x01;
+        search.unicast           = (flags & FLAG_SEARCH_UNICAST)    == FLAG_SEARCH_UNICAST;
+        search.reply_required    = (flags & FLAG_SEARCH_MUST_REPLY) == FLAG_SEARCH_MUST_REPLY;
+        search.reply_to_src_port = (flags & FLAG_REPLY_SRC_PORT)    == FLAG_REPLY_SRC_PORT;
 
         // reserved
         buffer.get();
@@ -127,7 +144,13 @@ public static SearchRequest decode(final InetSocketAddress from, final byte vers
             logger.log(Level.WARNING, "PVA Client " + from + " sent search #" + search.seq + " with invalid address");
             return null;
         }
-        final int port = Short.toUnsignedInt(buffer.getShort());
+        int port = Short.toUnsignedInt(buffer.getShort());
+        // Since version 3, flag can ask us to ignore the reply port in the message
+        // and instead use the peer's port.
+        // This should help with NAT where we get the message from an intermediate
+        // and need to reply via that same intermediate
+        if (version >= 3  &&  search.reply_to_src_port)
+            port = from.getPort();
 
         // Use address from message unless it's a generic local address
         if (addr.isAnyLocalAddress() || port <= 0)
@@ -201,8 +224,9 @@ public static void encode(final boolean unicast, final int seq, final Collection
         // only the one started last will see the unicast.
         // Mark search message as unicast so that receiver will forward
         // it via local broadcast to other local listeners.
-        // 0-bit for replyRequired, 7-th bit for "sent as unicast" (1)/"sent as broadcast/multicast" (0)
-        buffer.put((byte) ((unicast ? 0x80 : 0x00) | (channels == null ? 0x01 : 0x00)));
+        buffer.put((byte) ((unicast ? FLAG_SEARCH_UNICAST : 0x00) |
+                           ((channels == null || channels.isEmpty()) ? FLAG_SEARCH_MUST_REPLY : 0x00) |
+                           FLAG_REPLY_SRC_PORT));
 
         // reserved
         buffer.put((byte) 0);