proxyproto: add UDP session tracking for Spectrum PPv2 (#7967)

plugin/proxyproto/README.md

@@ -16,6 +16,7 @@ client's IP address and port information.
 proxyproto {
     allow <CIDR...>
     default <use|ignore|reject|skip>
+    udp_session_tracking <duration> [max_sessions]
 }
 ~~~
 
@@ -23,15 +24,26 @@ If `allow` is unspecified, PROXY protocol headers are accepted from all IP addre
 The `default` option controls how connections from sources not listed in `allow` are handled.
 If `default` is unspecified, it defaults to `ignore`.
 The possible values are:
+
 - `use`: accept and use PROXY protocol headers from these sources
 - `ignore`: accept and ignore PROXY protocol headers from other sources
 - `reject`: reject connections with PROXY protocol headers from other sources
 - `skip`: skip PROXY protocol processing for connections from other sources, treating them as normal connections preserving the PROXY protocol headers.
 
+The `udp_session_tracking <duration> [max_sessions]` option enables UDP session state tracking
+for Cloudflare Spectrum's PROXY Protocol v2 over UDP. Spectrum sends the PPv2 header as a
+standalone first datagram (with no DNS payload). Subsequent datagrams from the same client arrive
+without any header. When this option is set to a positive duration, the real client address from
+the header-only datagram is cached (keyed by the Spectrum-side remote address) for that duration
+and automatically applied to all subsequent headerless datagrams within that window. The TTL is
+refreshed on each matching packet. The optional `max_sessions` argument caps the number of
+concurrent sessions in the LRU cache (default: 10240). This option has no effect for TCP
+connections.
 
 ## Examples
 
 In this configuration, we allow PROXY protocol connections from all IP addresses:
+
 ~~~ corefile
 . {
     proxyproto
@@ -41,6 +53,7 @@ In this configuration, we allow PROXY protocol connections from all IP addresses
 
 In this configuration, we only allow PROXY protocol connections from the specified CIDR ranges
 and ignore proxy protocol headers from other sources:
+
 ~~~ corefile
 . {
     proxyproto {
@@ -52,6 +65,7 @@ and ignore proxy protocol headers from other sources:
 
 In this configuration, we only allow PROXY protocol headers from the specified CIDR ranges and reject
 connections without valid PROXY protocol headers from those sources:
+
 ~~~ corefile
 . {
     proxyproto {
@@ -61,3 +75,29 @@ connections without valid PROXY protocol headers from those sources:
     forward . /etc/resolv.conf
 }
 ~~~
+
+In this configuration, we enable UDP session tracking for Cloudflare Spectrum's PPv2-over-UDP
+with a 28-second TTL (slightly shorter than Spectrum's 30-second UDP idle timeout) and the
+default session cap of 10240:
+
+~~~ corefile
+. {
+    proxyproto {
+        allow 192.168.1.1/32
+        udp_session_tracking 28s
+    }
+    forward . /etc/resolv.conf
+}
+~~~
+
+In this configuration, the session cap is raised to 20480:
+
+~~~ corefile
+. {
+    proxyproto {
+        allow 192.168.1.1/32
+        udp_session_tracking 28s 20000
+    }
+    forward . /etc/resolv.conf
+}
+~~~