feat(remoteingress-core): add UDP tunneling support between edge and hub

rust/crates/remoteingress-protocol/src/lib.rs

@@ -19,6 +19,12 @@ pub const FRAME_PONG: u8 = 0x08;       // Edge -> Hub: heartbeat response
 pub const FRAME_WINDOW_UPDATE: u8 = 0x09;      // Edge -> Hub: per-stream flow control
 pub const FRAME_WINDOW_UPDATE_BACK: u8 = 0x0A;  // Hub -> Edge: per-stream flow control
 
+// UDP tunnel frame types
+pub const FRAME_UDP_OPEN: u8 = 0x0B;            // Edge -> Hub: open UDP session (payload: PROXY v2 header)
+pub const FRAME_UDP_DATA: u8 = 0x0C;            // Edge -> Hub: UDP datagram
+pub const FRAME_UDP_DATA_BACK: u8 = 0x0D;       // Hub -> Edge: UDP datagram
+pub const FRAME_UDP_CLOSE: u8 = 0x0E;           // Either direction: close UDP session
+
 // Frame header size: 4 (stream_id) + 1 (type) + 4 (length) = 9 bytes
 pub const FRAME_HEADER_SIZE: usize = 9;
 
@@ -107,6 +113,76 @@ pub fn build_proxy_v1_header(
     )
 }
 
+/// PROXY protocol v2 signature (12 bytes).
+pub const PROXY_V2_SIGNATURE: [u8; 12] = [
+    0x0D, 0x0A, 0x0D, 0x0A, 0x00, 0x0D, 0x0A, 0x51, 0x55, 0x49, 0x54, 0x0A,
+];
+
+/// Transport protocol for PROXY v2 header.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProxyV2Transport {
+    /// TCP (STREAM) — byte 13 low nibble = 0x1
+    Tcp,
+    /// UDP (DGRAM) — byte 13 low nibble = 0x2
+    Udp,
+}
+
+/// Build a PROXY protocol v2 binary header for IPv4.
+///
+/// Returns a 28-byte header:
+/// - 12B signature
+/// - 1B version (0x2) + command (0x1 = PROXY)
+/// - 1B address family (0x1 = AF_INET) + transport (0x1 = TCP, 0x2 = UDP)
+/// - 2B address block length (0x000C = 12)
+/// - 4B source IPv4 address
+/// - 4B destination IPv4 address
+/// - 2B source port
+/// - 2B destination port
+pub fn build_proxy_v2_header(
+    src_ip: &std::net::Ipv4Addr,
+    dst_ip: &std::net::Ipv4Addr,
+    src_port: u16,
+    dst_port: u16,
+    transport: ProxyV2Transport,
+) -> Bytes {
+    let mut buf = BytesMut::with_capacity(28);
+    // Signature (12 bytes)
+    buf.put_slice(&PROXY_V2_SIGNATURE);
+    // Version 2 + PROXY command
+    buf.put_u8(0x21);
+    // AF_INET (0x1) + transport
+    let transport_nibble = match transport {
+        ProxyV2Transport::Tcp => 0x1,
+        ProxyV2Transport::Udp => 0x2,
+    };
+    buf.put_u8(0x10 | transport_nibble);
+    // Address block length: 12 bytes for IPv4
+    buf.put_u16(12);
+    // Source address (4 bytes, network byte order)
+    buf.put_slice(&src_ip.octets());
+    // Destination address (4 bytes, network byte order)
+    buf.put_slice(&dst_ip.octets());
+    // Source port (2 bytes, network byte order)
+    buf.put_u16(src_port);
+    // Destination port (2 bytes, network byte order)
+    buf.put_u16(dst_port);
+    buf.freeze()
+}
+
+/// Build a PROXY protocol v2 binary header from string IP addresses.
+/// Falls back to 0.0.0.0 if parsing fails.
+pub fn build_proxy_v2_header_from_str(
+    src_ip: &str,
+    dst_ip: &str,
+    src_port: u16,
+    dst_port: u16,
+    transport: ProxyV2Transport,
+) -> Bytes {
+    let src: std::net::Ipv4Addr = src_ip.parse().unwrap_or(std::net::Ipv4Addr::UNSPECIFIED);
+    let dst: std::net::Ipv4Addr = dst_ip.parse().unwrap_or(std::net::Ipv4Addr::UNSPECIFIED);
+    build_proxy_v2_header(&src, &dst, src_port, dst_port, transport)
+}
+
 /// Stateful async frame reader that yields `Frame` values from an `AsyncRead`.
 pub struct FrameReader<R> {
     reader: R,
@@ -604,6 +680,62 @@ mod tests {
         assert_eq!(header, "PROXY TCP4 1.2.3.4 5.6.7.8 12345 443\r\n");
     }
 
+    #[test]
+    fn test_proxy_v2_header_tcp4() {
+        let src = "198.51.100.10".parse().unwrap();
+        let dst = "203.0.113.25".parse().unwrap();
+        let header = build_proxy_v2_header(&src, &dst, 54321, 8443, ProxyV2Transport::Tcp);
+        assert_eq!(header.len(), 28);
+        // Signature
+        assert_eq!(&header[0..12], &PROXY_V2_SIGNATURE);
+        // Version 2 + PROXY command
+        assert_eq!(header[12], 0x21);
+        // AF_INET + STREAM (TCP)
+        assert_eq!(header[13], 0x11);
+        // Address length = 12
+        assert_eq!(u16::from_be_bytes([header[14], header[15]]), 12);
+        // Source IP: 198.51.100.10
+        assert_eq!(&header[16..20], &[198, 51, 100, 10]);
+        // Dest IP: 203.0.113.25
+        assert_eq!(&header[20..24], &[203, 0, 113, 25]);
+        // Source port: 54321
+        assert_eq!(u16::from_be_bytes([header[24], header[25]]), 54321);
+        // Dest port: 8443
+        assert_eq!(u16::from_be_bytes([header[26], header[27]]), 8443);
+    }
+
+    #[test]
+    fn test_proxy_v2_header_udp4() {
+        let src = "10.0.0.1".parse().unwrap();
+        let dst = "10.0.0.2".parse().unwrap();
+        let header = build_proxy_v2_header(&src, &dst, 12345, 53, ProxyV2Transport::Udp);
+        assert_eq!(header.len(), 28);
+        assert_eq!(header[12], 0x21); // v2, PROXY
+        assert_eq!(header[13], 0x12); // AF_INET + DGRAM (UDP)
+        assert_eq!(&header[16..20], &[10, 0, 0, 1]); // src
+        assert_eq!(&header[20..24], &[10, 0, 0, 2]); // dst
+        assert_eq!(u16::from_be_bytes([header[24], header[25]]), 12345);
+        assert_eq!(u16::from_be_bytes([header[26], header[27]]), 53);
+    }
+
+    #[test]
+    fn test_proxy_v2_header_from_str() {
+        let header = build_proxy_v2_header_from_str("1.2.3.4", "5.6.7.8", 1000, 443, ProxyV2Transport::Tcp);
+        assert_eq!(header.len(), 28);
+        assert_eq!(&header[16..20], &[1, 2, 3, 4]);
+        assert_eq!(&header[20..24], &[5, 6, 7, 8]);
+    }
+
+    #[test]
+    fn test_proxy_v2_header_from_str_invalid_ip() {
+        let header = build_proxy_v2_header_from_str("not-an-ip", "also-not", 1000, 443, ProxyV2Transport::Udp);
+        assert_eq!(header.len(), 28);
+        // Falls back to 0.0.0.0
+        assert_eq!(&header[16..20], &[0, 0, 0, 0]);
+        assert_eq!(&header[20..24], &[0, 0, 0, 0]);
+        assert_eq!(header[13], 0x12); // UDP
+    }
+
     #[tokio::test]
     async fn test_frame_reader() {
         let frame1 = encode_frame(1, FRAME_OPEN, b"PROXY TCP4 1.2.3.4 5.6.7.8 1234 443\r\n");