feat: add negotiated binary UDP packets (#5456)

pkg/msg/udp_binary.go

@@ -0,0 +1,338 @@
+// Copyright 2026 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package msg
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io"
+	"net"
+	"unicode/utf8"
+
+	"github.com/fatedier/frp/pkg/proto/wire"
+)
+
+const MaxUDPPayloadSize = 65507
+
+const (
+	udpPacketFlagLocalAddr  byte = 1 << 0
+	udpPacketFlagRemoteAddr byte = 1 << 1
+	udpPacketValidFlags          = udpPacketFlagLocalAddr | udpPacketFlagRemoteAddr
+)
+
+type binaryUDPAddr struct {
+	family byte
+	ip     []byte
+	port   uint16
+	zone   string
+}
+
+// EncodeUDPPacketBinary encodes the body of a V2 binary UDP packet message.
+// RemoteAddr is required by the UDP forwarding path.
+func EncodeUDPPacketBinary(packet *UDPPacket) ([]byte, error) {
+	if packet == nil {
+		return nil, fmt.Errorf("nil UDP packet")
+	}
+	if packet.RemoteAddr == nil {
+		return nil, fmt.Errorf("UDP packet missing remote address")
+	}
+	if len(packet.Content) > MaxUDPPayloadSize {
+		return nil, fmt.Errorf("UDP payload length %d exceeds limit %d", len(packet.Content), MaxUDPPayloadSize)
+	}
+
+	var flags byte
+	var localAddr, remoteAddr binaryUDPAddr
+	bodyLen := 1 + 2 + len(packet.Content)
+	if packet.LocalAddr != nil {
+		flags |= udpPacketFlagLocalAddr
+		var err error
+		localAddr, err = validateBinaryUDPAddr(packet.LocalAddr)
+		if err != nil {
+			return nil, fmt.Errorf("local address: %w", err)
+		}
+		bodyLen += binaryUDPAddrLen(localAddr)
+	}
+	flags |= udpPacketFlagRemoteAddr
+	var err error
+	remoteAddr, err = validateBinaryUDPAddr(packet.RemoteAddr)
+	if err != nil {
+		return nil, fmt.Errorf("remote address: %w", err)
+	}
+	bodyLen += binaryUDPAddrLen(remoteAddr)
+	if 2+bodyLen > wire.DefaultMaxFramePayloadSize {
+		return nil, fmt.Errorf("v2 frame payload length %d exceeds limit %d", 2+bodyLen, wire.DefaultMaxFramePayloadSize)
+	}
+
+	body := make([]byte, bodyLen)
+	body[0] = flags
+	offset := 1
+	if flags&udpPacketFlagLocalAddr != 0 {
+		offset = putBinaryUDPAddr(body, offset, localAddr)
+	}
+	offset = putBinaryUDPAddr(body, offset, remoteAddr)
+	binary.BigEndian.PutUint16(body[offset:offset+2], uint16(len(packet.Content)))
+	offset += 2
+	copy(body[offset:], packet.Content)
+	return body, nil
+}
+
+// DecodeUDPPacketBinary decodes a V2 binary UDP packet body and returns data
+// that does not alias the input frame buffer.
+func DecodeUDPPacketBinary(body []byte) (*UDPPacket, error) {
+	if len(body) < 3 {
+		return nil, fmt.Errorf("UDP packet body too short: %d", len(body))
+	}
+	if 2+len(body) > wire.DefaultMaxFramePayloadSize {
+		return nil, fmt.Errorf("v2 frame payload length %d exceeds limit %d", 2+len(body), wire.DefaultMaxFramePayloadSize)
+	}
+
+	flags := body[0]
+	if flags&^udpPacketValidFlags != 0 {
+		return nil, fmt.Errorf("reserved UDP packet flags set: 0x%02x", flags)
+	}
+	if flags&udpPacketFlagRemoteAddr == 0 {
+		return nil, fmt.Errorf("UDP packet missing remote address")
+	}
+
+	packet := &UDPPacket{}
+	offset := 1
+	var err error
+	if flags&udpPacketFlagLocalAddr != 0 {
+		packet.LocalAddr, offset, err = readBinaryUDPAddr(body, offset)
+		if err != nil {
+			return nil, fmt.Errorf("local address: %w", err)
+		}
+	}
+	if flags&udpPacketFlagRemoteAddr != 0 {
+		packet.RemoteAddr, offset, err = readBinaryUDPAddr(body, offset)
+		if err != nil {
+			return nil, fmt.Errorf("remote address: %w", err)
+		}
+	}
+	if len(body)-offset < 2 {
+		return nil, fmt.Errorf("truncated UDP payload length")
+	}
+	payloadLen := int(binary.BigEndian.Uint16(body[offset : offset+2]))
+	offset += 2
+	if payloadLen > MaxUDPPayloadSize {
+		return nil, fmt.Errorf("UDP payload length %d exceeds limit %d", payloadLen, MaxUDPPayloadSize)
+	}
+	remaining := len(body) - offset
+	if remaining < payloadLen {
+		return nil, fmt.Errorf("truncated UDP payload: have %d want %d", remaining, payloadLen)
+	}
+	if remaining > payloadLen {
+		return nil, fmt.Errorf("trailing UDP packet bytes: %d", remaining-payloadLen)
+	}
+	packet.Content = append([]byte(nil), body[offset:offset+payloadLen]...)
+	return packet, nil
+}
+
+func validateBinaryUDPAddr(addr *net.UDPAddr) (binaryUDPAddr, error) {
+	if addr.Port < 0 || addr.Port > 65535 {
+		return binaryUDPAddr{}, fmt.Errorf("port out of range: %d", addr.Port)
+	}
+	if ip := addr.IP.To4(); ip != nil {
+		if addr.Zone != "" {
+			return binaryUDPAddr{}, fmt.Errorf("IPv4 zone is forbidden")
+		}
+		return binaryUDPAddr{family: 4, ip: ip, port: uint16(addr.Port)}, nil
+	}
+	ip := addr.IP.To16()
+	if ip == nil {
+		return binaryUDPAddr{}, fmt.Errorf("invalid IP")
+	}
+	if len(addr.Zone) > 255 {
+		return binaryUDPAddr{}, fmt.Errorf("zone exceeds 255 bytes")
+	}
+	if !utf8.ValidString(addr.Zone) {
+		return binaryUDPAddr{}, fmt.Errorf("zone is not valid UTF-8")
+	}
+	return binaryUDPAddr{family: 6, ip: ip, port: uint16(addr.Port), zone: addr.Zone}, nil
+}
+
+func binaryUDPAddrLen(addr binaryUDPAddr) int {
+	return 1 + len(addr.ip) + 2 + 1 + len(addr.zone)
+}
+
+func putBinaryUDPAddr(body []byte, offset int, addr binaryUDPAddr) int {
+	body[offset] = addr.family
+	offset++
+	copy(body[offset:], addr.ip)
+	offset += len(addr.ip)
+	binary.BigEndian.PutUint16(body[offset:offset+2], addr.port)
+	offset += 2
+	body[offset] = byte(len(addr.zone))
+	offset++
+	copy(body[offset:], addr.zone)
+	return offset + len(addr.zone)
+}
+
+func readBinaryUDPAddr(body []byte, offset int) (*net.UDPAddr, int, error) {
+	if offset >= len(body) {
+		return nil, offset, fmt.Errorf("truncated address family")
+	}
+	family := body[offset]
+	offset++
+	var ipLen int
+	switch family {
+	case 4:
+		ipLen = net.IPv4len
+	case 6:
+		ipLen = net.IPv6len
+	default:
+		return nil, offset, fmt.Errorf("unknown address family %d", family)
+	}
+	if len(body)-offset < ipLen+3 {
+		return nil, offset, fmt.Errorf("truncated address")
+	}
+	ip := append(net.IP(nil), body[offset:offset+ipLen]...)
+	offset += ipLen
+	port := binary.BigEndian.Uint16(body[offset : offset+2])
+	offset += 2
+	zoneLen := int(body[offset])
+	offset++
+	if len(body)-offset < zoneLen {
+		return nil, offset, fmt.Errorf("truncated zone")
+	}
+	zoneBytes := body[offset : offset+zoneLen]
+	if family == 4 && zoneLen != 0 {
+		return nil, offset, fmt.Errorf("IPv4 zone is forbidden")
+	}
+	if !utf8.Valid(zoneBytes) {
+		return nil, offset, fmt.Errorf("zone is not valid UTF-8")
+	}
+	offset += zoneLen
+	return &net.UDPAddr{IP: ip, Port: int(port), Zone: string(zoneBytes)}, offset, nil
+}
+
+type V2BinaryUDPPacketReadWriter struct {
+	conn *wire.Conn
+}
+
+func NewV2BinaryUDPPacketReadWriter(rw io.ReadWriter) *V2BinaryUDPPacketReadWriter {
+	return &V2BinaryUDPPacketReadWriter{conn: wire.NewConn(rw)}
+}
+
+func (rw *V2BinaryUDPPacketReadWriter) ReadMsg() (Message, error) {
+	frame, err := rw.conn.ReadFrame()
+	if err != nil {
+		return nil, err
+	}
+	if isV2MessageType(frame, V2TypeUDPPacketBinary) {
+		return decodeV2BinaryUDPPacketFrame(frame)
+	}
+	if isV2MessageType(frame, V2TypeUDPPacket) {
+		return nil, fmt.Errorf("received JSON UDP packet after binary codec negotiation")
+	}
+	return DecodeV2MessageFrame(frame)
+}
+
+func (rw *V2BinaryUDPPacketReadWriter) ReadMsgInto(out Message) error {
+	frame, err := rw.conn.ReadFrame()
+	if err != nil {
+		return err
+	}
+	if packetOut, ok := out.(*UDPPacket); ok {
+		if !isV2MessageType(frame, V2TypeUDPPacketBinary) {
+			return unexpectedV2UDPPacketType(frame)
+		}
+		packet, err := decodeV2BinaryUDPPacketFrame(frame)
+		if err != nil {
+			return err
+		}
+		*packetOut = *packet
+		return nil
+	}
+	return DecodeV2MessageFrameInto(frame, out)
+}
+
+func (rw *V2BinaryUDPPacketReadWriter) WriteMsg(message Message) error {
+	var packet *UDPPacket
+	switch typed := message.(type) {
+	case *UDPPacket:
+		packet = typed
+	case UDPPacket:
+		packet = &typed
+	default:
+		frame, err := EncodeV2MessageFrame(message)
+		if err != nil {
+			return err
+		}
+		return rw.conn.WriteFrame(frame)
+	}
+	body, err := EncodeUDPPacketBinary(packet)
+	if err != nil {
+		return err
+	}
+	payload := make([]byte, 2+len(body))
+	binary.BigEndian.PutUint16(payload[:2], V2TypeUDPPacketBinary)
+	copy(payload[2:], body)
+	return rw.conn.WriteFrame(&wire.Frame{Type: wire.FrameTypeMessage, Payload: payload})
+}
+
+func decodeV2BinaryUDPPacketFrame(frame *wire.Frame) (*UDPPacket, error) {
+	if frame.Type != wire.FrameTypeMessage {
+		return nil, fmt.Errorf("unexpected frame type %d, want %d", frame.Type, wire.FrameTypeMessage)
+	}
+	if len(frame.Payload) < 2 {
+		return nil, fmt.Errorf("message frame payload too short")
+	}
+	if binary.BigEndian.Uint16(frame.Payload[:2]) != V2TypeUDPPacketBinary {
+		return nil, unexpectedV2UDPPacketType(frame)
+	}
+	return DecodeUDPPacketBinary(frame.Payload[2:])
+}
+
+func isV2MessageType(frame *wire.Frame, typeID uint16) bool {
+	return frame.Type == wire.FrameTypeMessage && len(frame.Payload) >= 2 && binary.BigEndian.Uint16(frame.Payload[:2]) == typeID
+}
+
+func unexpectedV2UDPPacketType(frame *wire.Frame) error {
+	if frame.Type != wire.FrameTypeMessage {
+		return fmt.Errorf("unexpected frame type %d, want %d", frame.Type, wire.FrameTypeMessage)
+	}
+	if len(frame.Payload) < 2 {
+		return fmt.Errorf("message frame payload too short")
+	}
+	typeID := binary.BigEndian.Uint16(frame.Payload[:2])
+	if typeID == V2TypeUDPPacket {
+		return fmt.Errorf("received JSON UDP packet after binary codec negotiation")
+	}
+	return fmt.Errorf("unexpected message type %d, want %d", typeID, V2TypeUDPPacketBinary)
+}
+
+// NewUDPPacketReadWriter selects the negotiated packet codec without changing
+// the framing or codecs used by non-UDP messages on the work connection.
+func NewUDPPacketReadWriter(rw io.ReadWriter, wireProtocol, udpPacketCodec string) (ReadWriter, error) {
+	switch wireProtocol {
+	case "", wire.ProtocolV1:
+		if udpPacketCodec != "" {
+			return nil, fmt.Errorf("UDP packet codec %q requires wire protocol v2", udpPacketCodec)
+		}
+		return NewV1ReadWriter(rw), nil
+	case wire.ProtocolV2:
+		switch udpPacketCodec {
+		case "":
+			return NewV2ReadWriter(rw), nil
+		case wire.UDPPacketCodecBinary:
+			return NewV2BinaryUDPPacketReadWriter(rw), nil
+		default:
+			return nil, fmt.Errorf("unsupported UDP packet codec %q", udpPacketCodec)
+		}
+	default:
+		return nil, fmt.Errorf("unsupported wire protocol %q", wireProtocol)
+	}
+}

pkg/msg/udp_binary_test.go

@@ -0,0 +1,248 @@
+// Copyright 2026 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+package msg
+
+import (
+	"bytes"
+	"encoding/binary"
+	"net"
+	"strconv"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/fatedier/frp/pkg/proto/wire"
+)
+
+func TestUDPPacketBinaryRoundTrip(t *testing.T) {
+	payload := bytes.Repeat([]byte{0xa5}, 1472)
+	in := &UDPPacket{
+		Content: payload,
+		LocalAddr: &net.UDPAddr{
+			IP:   net.ParseIP("2001:db8::1"),
+			Port: 1234,
+			Zone: "en0",
+		},
+		RemoteAddr: &net.UDPAddr{IP: net.ParseIP("203.0.113.9"), Port: 54321},
+	}
+	body, err := EncodeUDPPacketBinary(in)
+	require.NoError(t, err)
+	out, err := DecodeUDPPacketBinary(body)
+	require.NoError(t, err)
+	require.Equal(t, in.Content, out.Content)
+	require.Equal(t, in.LocalAddr.String(), out.LocalAddr.String())
+	require.Equal(t, in.RemoteAddr.String(), out.RemoteAddr.String())
+	body[len(body)-1] ^= 0xff
+	body[25] ^= 0xff
+	require.Equal(t, byte(0xa5), out.Content[len(out.Content)-1], "decoded payload must own frame bytes")
+	require.Equal(t, byte(203), out.RemoteAddr.IP.To4()[0], "decoded address must own frame bytes")
+}
+
+func TestUDPPacketBinarySizesAndOptionalLocalAddress(t *testing.T) {
+	for _, size := range []int{0, 32, 128, 512, 1200, 1472, 4096, 49107, 65507} {
+		t.Run(strconv.Itoa(size), func(t *testing.T) {
+			in := &UDPPacket{
+				Content:    bytes.Repeat([]byte{byte(size)}, size),
+				RemoteAddr: &net.UDPAddr{IP: net.ParseIP("203.0.113.9"), Port: 54321},
+			}
+			body, err := EncodeUDPPacketBinary(in)
+			require.NoError(t, err)
+			out, err := DecodeUDPPacketBinary(body)
+			require.NoError(t, err)
+			require.Equal(t, len(in.Content), len(out.Content))
+			if size == 0 {
+				require.Empty(t, out.Content)
+			} else {
+				require.Equal(t, in.Content, out.Content)
+			}
+		})
+	}
+}
+
+func TestUDPPacketBinaryMalformed(t *testing.T) {
+	valid, err := EncodeUDPPacketBinary(&UDPPacket{
+		Content:    []byte("payload"),
+		RemoteAddr: &net.UDPAddr{IP: net.ParseIP("203.0.113.9"), Port: 54321},
+	})
+	require.NoError(t, err)
+	tests := [][]byte{
+		{0x80, 0, 0},
+		{0x02, 4, 1, 2},
+		{0x02, 4, 1, 2, 3, 4, 0xd4},
+		append(append([]byte(nil), valid...), 0),
+	}
+	for _, malformed := range tests {
+		_, err := DecodeUDPPacketBinary(malformed)
+		require.Error(t, err)
+	}
+	_, err = DecodeUDPPacketBinary([]byte{0, 0, 0})
+	require.ErrorContains(t, err, "missing remote address")
+	payloadLengthOffset := len(valid) - len("payload") - 2
+	invalidPayloadLength := append([]byte(nil), valid...)
+	binary.BigEndian.PutUint16(invalidPayloadLength[payloadLengthOffset:payloadLengthOffset+2], 0xffff)
+	_, err = DecodeUDPPacketBinary(invalidPayloadLength)
+	require.ErrorContains(t, err, "payload length")
+	truncatedPayload := append([]byte(nil), valid[:payloadLengthOffset+2]...)
+	binary.BigEndian.PutUint16(truncatedPayload[payloadLengthOffset:payloadLengthOffset+2], 1)
+	_, err = DecodeUDPPacketBinary(truncatedPayload)
+	require.ErrorContains(t, err, "truncated UDP payload")
+	_, err = DecodeUDPPacketBinary(make([]byte, wire.DefaultMaxFramePayloadSize))
+	require.ErrorContains(t, err, "frame payload length")
+
+	badIPv4Zone := []byte{2, 4, 203, 0, 113, 9, 0xd4, 0x31, 1, 'z', 0, 0}
+	_, err = DecodeUDPPacketBinary(badIPv4Zone)
+	require.ErrorContains(t, err, "IPv4 zone")
+	badFamily := []byte{2, 9, 0, 0}
+	_, err = DecodeUDPPacketBinary(badFamily)
+	require.ErrorContains(t, err, "unknown address family")
+	badUTF8 := make([]byte, 0, 24)
+	badUTF8 = append(badUTF8, 2, 6)
+	badUTF8 = append(badUTF8, make([]byte, 16)...)
+	badUTF8 = append(badUTF8, 0, 1, 1, 0xff, 0, 0)
+	_, err = DecodeUDPPacketBinary(badUTF8)
+	require.ErrorContains(t, err, "UTF-8")
+}
+
+func TestUDPPacketBinaryEncodeRejectsInvalidPackets(t *testing.T) {
+	_, err := EncodeUDPPacketBinary(&UDPPacket{})
+	require.ErrorContains(t, err, "missing remote address")
+	_, err = EncodeUDPPacketBinary(&UDPPacket{
+		LocalAddr: &net.UDPAddr{IP: net.ParseIP("192.0.2.1"), Port: 1234},
+	})
+	require.ErrorContains(t, err, "missing remote address")
+	_, err = EncodeUDPPacketBinary(&UDPPacket{
+		Content:    make([]byte, MaxUDPPayloadSize+1),
+		RemoteAddr: &net.UDPAddr{IP: net.ParseIP("203.0.113.9"), Port: 54321},
+	})
+	require.ErrorContains(t, err, "exceeds limit")
+	_, err = EncodeUDPPacketBinary(&UDPPacket{RemoteAddr: &net.UDPAddr{IP: net.ParseIP("203.0.113.9"), Port: 1, Zone: "bad"}})
+	require.ErrorContains(t, err, "IPv4 zone")
+	_, err = EncodeUDPPacketBinary(&UDPPacket{RemoteAddr: &net.UDPAddr{IP: net.ParseIP("2001:db8::1"), Port: 1, Zone: string(bytes.Repeat([]byte{'z'}, 256))}})
+	require.ErrorContains(t, err, "zone exceeds")
+	_, err = EncodeUDPPacketBinary(&UDPPacket{RemoteAddr: &net.UDPAddr{IP: net.ParseIP("2001:db8::1"), Port: 1, Zone: string([]byte{0xff})}})
+	require.ErrorContains(t, err, "UTF-8")
+	_, err = EncodeUDPPacketBinary(&UDPPacket{RemoteAddr: &net.UDPAddr{Port: -1}})
+	require.ErrorContains(t, err, "port out of range")
+	_, err = EncodeUDPPacketBinary(&UDPPacket{RemoteAddr: &net.UDPAddr{Port: 65536}})
+	require.ErrorContains(t, err, "port out of range")
+	_, err = EncodeUDPPacketBinary(&UDPPacket{RemoteAddr: &net.UDPAddr{IP: net.IP{1, 2, 3}}})
+	require.ErrorContains(t, err, "invalid IP")
+	_, err = EncodeUDPPacketBinary(&UDPPacket{
+		Content:    make([]byte, MaxUDPPayloadSize),
+		RemoteAddr: &net.UDPAddr{IP: net.ParseIP("2001:db8::1"), Zone: string(bytes.Repeat([]byte{'z'}, 255))},
+	})
+	require.ErrorContains(t, err, "frame payload length")
+}
+
+func TestV2BinaryUDPPacketReadWriterPreservesOtherMessages(t *testing.T) {
+	var buf bytes.Buffer
+	rw := NewV2BinaryUDPPacketReadWriter(&buf)
+	in := &UDPPacket{Content: []byte("udp"), RemoteAddr: &net.UDPAddr{IP: net.ParseIP("203.0.113.9"), Port: 54321}}
+	require.NoError(t, rw.WriteMsg(in))
+	require.NoError(t, rw.WriteMsg(&Ping{Timestamp: 7}))
+	frameConn := wire.NewConn(&buf)
+	frame, err := frameConn.ReadFrame()
+	require.NoError(t, err)
+	require.Equal(t, V2TypeUDPPacketBinary, binary.BigEndian.Uint16(frame.Payload[:2]))
+	frame, err = frameConn.ReadFrame()
+	require.NoError(t, err)
+	require.Equal(t, V2TypePing, binary.BigEndian.Uint16(frame.Payload[:2]))
+}
+
+func TestV2BinaryUDPPacketReadWriterRoundTripAndCodecInvariant(t *testing.T) {
+	in := &UDPPacket{Content: []byte("udp"), RemoteAddr: &net.UDPAddr{IP: net.ParseIP("203.0.113.9"), Port: 54321}}
+	var binaryStream bytes.Buffer
+	binaryWriter, err := NewUDPPacketReadWriter(&binaryStream, wire.ProtocolV2, wire.UDPPacketCodecBinary)
+	require.NoError(t, err)
+	require.NoError(t, binaryWriter.WriteMsg(in))
+	binaryReader, err := NewUDPPacketReadWriter(&binaryStream, wire.ProtocolV2, wire.UDPPacketCodecBinary)
+	require.NoError(t, err)
+	out, err := binaryReader.ReadMsg()
+	require.NoError(t, err)
+	require.Equal(t, in.Content, out.(*UDPPacket).Content)
+
+	for _, read := range []func(ReadWriter) error{
+		func(rw ReadWriter) error {
+			_, err := rw.ReadMsg()
+			return err
+		},
+		func(rw ReadWriter) error {
+			return rw.ReadMsgInto(&UDPPacket{})
+		},
+	} {
+		var jsonStream bytes.Buffer
+		require.NoError(t, NewReadWriter(&jsonStream, wire.ProtocolV2).WriteMsg(in))
+		negotiatedReader, err := NewUDPPacketReadWriter(&jsonStream, wire.ProtocolV2, wire.UDPPacketCodecBinary)
+		require.NoError(t, err)
+		require.ErrorContains(t, read(negotiatedReader), "JSON UDP packet after binary codec negotiation")
+	}
+
+	var fallbackStream bytes.Buffer
+	fallbackWriter, err := NewUDPPacketReadWriter(&fallbackStream, wire.ProtocolV2, "")
+	require.NoError(t, err)
+	require.NoError(t, fallbackWriter.WriteMsg(in))
+	frame, err := wire.NewConn(&fallbackStream).ReadFrame()
+	require.NoError(t, err)
+	require.Equal(t, V2TypeUDPPacket, binary.BigEndian.Uint16(frame.Payload[:2]))
+}
+
+func TestNewUDPPacketReadWriterDefaultProtocolUsesV1(t *testing.T) {
+	var stream bytes.Buffer
+	rw, err := NewUDPPacketReadWriter(&stream, "", "")
+	require.NoError(t, err)
+	require.IsType(t, &V1ReadWriter{}, rw)
+	require.NoError(t, rw.WriteMsg(&UDPPacket{Content: []byte("legacy")}))
+	require.Equal(t, TypeUDPPacket, stream.Bytes()[0])
+}
+
+func TestNewUDPPacketReadWriterRejectsInvalidSelection(t *testing.T) {
+	for _, tc := range []struct {
+		name           string
+		wireProtocol   string
+		udpPacketCodec string
+		errorSubstring string
+	}{
+		{
+			name:           "binary codec over v1",
+			wireProtocol:   wire.ProtocolV1,
+			udpPacketCodec: wire.UDPPacketCodecBinary,
+			errorSubstring: "requires wire protocol v2",
+		},
+		{
+			name:           "binary codec over default protocol",
+			udpPacketCodec: wire.UDPPacketCodecBinary,
+			errorSubstring: "requires wire protocol v2",
+		},
+		{
+			name:           "unknown v2 codec",
+			wireProtocol:   wire.ProtocolV2,
+			udpPacketCodec: "unknown",
+			errorSubstring: "unsupported UDP packet codec",
+		},
+		{
+			name:           "unknown wire protocol",
+			wireProtocol:   "unknown",
+			errorSubstring: "unsupported wire protocol",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			rw, err := NewUDPPacketReadWriter(&bytes.Buffer{}, tc.wireProtocol, tc.udpPacketCodec)
+			require.Nil(t, rw)
+			require.ErrorContains(t, err, tc.errorSubstring)
+		})
+	}
+}
+
+func FuzzDecodeUDPPacketBinary(f *testing.F) {
+	f.Add([]byte{0, 0, 0})
+	f.Add([]byte{2, 4, 203, 0, 113, 9, 0xd4, 0x31, 0, 0, 1})
+	f.Fuzz(func(t *testing.T, body []byte) {
+		_, _ = DecodeUDPPacketBinary(body)
+	})
+}

pkg/msg/wire_v2.go

@@ -43,6 +43,7 @@ const (
 	V2TypeNatHoleResp        uint16 = 16
 	V2TypeNatHoleSid         uint16 = 17
 	V2TypeNatHoleReport      uint16 = 18
+	V2TypeUDPPacketBinary    uint16 = 19
 )
 
 var v2MsgTypeMap = map[uint16]any{

pkg/msg/wire_v2_test.go

@@ -84,6 +84,9 @@ func TestV2MessageTypeIDsAreStable(t *testing.T) {
 	require.Equal(t, uint16(16), V2TypeNatHoleResp)
 	require.Equal(t, uint16(17), V2TypeNatHoleSid)
 	require.Equal(t, uint16(18), V2TypeNatHoleReport)
+	require.Equal(t, uint16(19), V2TypeUDPPacketBinary)
+	_, registered := v2MsgTypeMap[V2TypeUDPPacketBinary]
+	require.False(t, registered, "binary UDP has a dedicated codec and must not alter generic type registry")
 }
 
 func TestV2MessageFrameEncoding(t *testing.T) {

pkg/proto/wire/crypto.go

@@ -68,7 +68,8 @@ func NewServerHello(clientHello ClientHello) (ServerHello, error) {
 	return ServerHello{
 		Selected: ServerSelection{
 			Message: MessageSelection{
-				Codec: MessageCodecJSON,
+				Codec:          MessageCodecJSON,
+				UDPPacketCodec: selectUDPPacketCodec(clientHello.Capabilities.Message.UDPPacketCodecs),
 			},
 			Crypto: CryptoSelection{
 				Algorithm:    algorithm,
@@ -92,6 +93,15 @@ func ValidateServerHelloForClient(clientHello ClientHello, serverHello ServerHel
 	if serverHello.Selected.Message.Codec != MessageCodecJSON {
 		return fmt.Errorf("unsupported selected message codec: %s", serverHello.Selected.Message.Codec)
 	}
+	udpPacketCodec := serverHello.Selected.Message.UDPPacketCodec
+	if udpPacketCodec != "" {
+		if udpPacketCodec != UDPPacketCodecBinary {
+			return fmt.Errorf("unsupported selected UDP packet codec: %s", udpPacketCodec)
+		}
+		if !Supports(clientHello.Capabilities.Message.UDPPacketCodecs, udpPacketCodec) {
+			return fmt.Errorf("selected UDP packet codec was not advertised by client: %s", udpPacketCodec)
+		}
+	}
 	cryptoSelection := serverHello.Selected.Crypto
 	if !IsSupportedAEADAlgorithm(cryptoSelection.Algorithm) {
 		return fmt.Errorf("unknown selected crypto algorithm: %s", cryptoSelection.Algorithm)
@@ -105,6 +115,13 @@ func ValidateServerHelloForClient(clientHello ClientHello, serverHello ServerHel
 	return nil
 }
 
+func selectUDPPacketCodec(codecs []string) string {
+	if Supports(codecs, UDPPacketCodecBinary) {
+		return UDPPacketCodecBinary
+	}
+	return ""
+}
+
 func NewCryptoContext(algorithm string, clientHelloPayload, serverHelloPayload []byte) *CryptoContext {
 	return &CryptoContext{
 		Algorithm:      algorithm,

pkg/proto/wire/wire.go

@@ -36,6 +36,7 @@ const (
 	FrameTypeMessage     uint16 = 16
 
 	MessageCodecJSON           = "json"
+	UDPPacketCodecBinary       = "binary-v1"
 	DefaultMaxFramePayloadSize = 64 * 1024
 
 	MagicV2 = "FRP\x00\x02\r\n"
@@ -182,7 +183,8 @@ type ClientCapabilities struct {
 }
 
 type MessageCapabilities struct {
-	Codecs []string `json:"codecs,omitempty"`
+	Codecs          []string `json:"codecs,omitempty"`
+	UDPPacketCodecs []string `json:"udpPacketCodecs,omitempty"`
 }
 
 type CryptoCapabilities struct {
@@ -201,7 +203,8 @@ type ServerSelection struct {
 }
 
 type MessageSelection struct {
-	Codec string `json:"codec,omitempty"`
+	Codec          string `json:"codec,omitempty"`
+	UDPPacketCodec string `json:"udpPacketCodec,omitempty"`
 }
 
 type CryptoSelection struct {
@@ -214,7 +217,8 @@ func clientHelloWithCryptoRandom(bootstrap BootstrapInfo, clientRandom []byte) C
 		Bootstrap: bootstrap,
 		Capabilities: ClientCapabilities{
 			Message: MessageCapabilities{
-				Codecs: []string{MessageCodecJSON},
+				Codecs:          []string{MessageCodecJSON},
+				UDPPacketCodecs: []string{UDPPacketCodecBinary},
 			},
 			Crypto: CryptoCapabilities{
 				Algorithms:   PreferredAEADAlgorithms(),

pkg/proto/wire/wire_test.go

@@ -148,10 +148,40 @@ func TestNewServerHelloSelectsFirstSupportedAEADAlgorithm(t *testing.T) {
 	serverHello, err := NewServerHello(hello)
 	require.NoError(t, err)
 	require.Equal(t, MessageCodecJSON, serverHello.Selected.Message.Codec)
+	require.Equal(t, UDPPacketCodecBinary, serverHello.Selected.Message.UDPPacketCodec)
 	require.Equal(t, AEADAlgorithmXChaCha20Poly1305, serverHello.Selected.Crypto.Algorithm)
 	require.Len(t, serverHello.Selected.Crypto.ServerRandom, CryptoRandomSize)
 }
 
+func TestUDPPacketCodecNegotiationFallbackAndValidation(t *testing.T) {
+	hello := mustClientHello(t, BootstrapInfo{})
+	serverHello, err := NewServerHello(hello)
+	require.NoError(t, err)
+	require.Equal(t, UDPPacketCodecBinary, serverHello.Selected.Message.UDPPacketCodec)
+	require.NoError(t, ValidateServerHelloForClient(hello, serverHello))
+
+	legacyHello := hello
+	legacyHello.Capabilities.Message.UDPPacketCodecs = nil
+	legacyServerHello, err := NewServerHello(legacyHello)
+	require.NoError(t, err)
+	require.Empty(t, legacyServerHello.Selected.Message.UDPPacketCodec)
+	require.NoError(t, ValidateServerHelloForClient(legacyHello, legacyServerHello))
+
+	unknownOffer := hello
+	unknownOffer.Capabilities.Message.UDPPacketCodecs = []string{"unknown"}
+	unknownServerHello, err := NewServerHello(unknownOffer)
+	require.NoError(t, err)
+	require.Empty(t, unknownServerHello.Selected.Message.UDPPacketCodec)
+
+	rejected := serverHello
+	rejected.Selected.Message.UDPPacketCodec = "unknown"
+	require.ErrorContains(t, ValidateServerHelloForClient(hello, rejected), "unsupported selected UDP packet codec")
+
+	unadvertised := serverHello
+	unadvertised.Selected.Message.UDPPacketCodec = UDPPacketCodecBinary
+	require.ErrorContains(t, ValidateServerHelloForClient(legacyHello, unadvertised), "was not advertised")
+}
+
 func TestNewClientCryptoContextValidatesServerHello(t *testing.T) {
 	hello := mustClientHello(t, BootstrapInfo{})
 	serverHello, err := NewServerHello(hello)