fix: Accept single words as valid hostnames (#3591)

## Purpose of this PR

The regex we used to validate hostnames did not accept single words as
valid hostnames. But single words _can_ be valid hostnames. The most
common is of course "localhost" but one can edit one's hosts file to
define any word as something the local resolver will resolve to an IP
address.

This PR addresses this by removing any validation of the provided
hostname. We could modify the validity check to accept single words too,
but the regex is pretty indigestible already and it's simpler to just
let the resolver fail if the user provided garbage. UTP will signal this
through a disconnection event with an appropriate reason (which we'll be
able to map to a nice error message once [this
PR](#3551)
lands).

While I was at it, I also made a few cleanups and improvements:

- Removed the `UTP_TRANSPORT_2_4_ABOVE` define. NGO depends on UTP 2.4.0
so it can be safely assumed that users will have it installed. No need
to conditionally compile the code that depends on it.
- Added a test that establishes a connection using hostname resolution.
- Simplified the logic around connections and avoid bypassing the
`Connect` method when connecting to a hostname.
- Deprecated `ConnectionAddressData.ServerEndPoint`. We don't use it
anymore, it doesn't work with hostnames, and it's not providing any
value over just calling `NetworkEndpoint.Parse`. And worst of all: its
capitalization of "endpoint" doesn't match what we use elsewhere.
- Modified the listen address logic so that if a domain name is used, by
default if remote connections are allowed we will listen on :: (the IPv6
"any" address) instead of 0.0.0.0. This can still be overridden using
`SetConnectionData`. The reason for this change is that the resolver in
UTP prioritizes IPv6 addresses over IPv4. So if we listen on IPv4 by
default, we're likely to get issues if the resolver then ends up with an
IPv6 address. In current versions of UTP for instance, this causes
errors on Windows (a fix is on the way). I'm looking into changing the
behavior of the resolver to prefer IPv4, but that's an engine change so
might take a while to land. In the meantime defaulting to IPv6 seems
like the best approach.

### Changelog

- Fixed: Fixed an issue where `UnityTransport` would not accept single
words as valid hostnames (notably "localhost").
- Changed: Marked `UnityTransport.ConnectionAddressData.ServerEndPoint`
as obsolete. It can't work when using hostnames as the server address,
and its functionality can easily be replicated using
`NetworkEndpoint.Parse`.

## Documentation

No documentation changes or additions were necessary.

## Testing & QA

Tested with manual and automated tests.

## Backport

Hostname resolution is only supported in UTP 2.4+ and Unity 6.1+, so no
backport necessary.

---------

Co-authored-by: Michał Chrobot <[email protected]>
Co-authored-by: Noel Stephens <[email protected]>

Author: 3 people

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -14,14 +14,15 @@ Additional documentation and release notes are available at [Multiplayer Documen
 
 ### Fixed
 
+- Fixed an issue where `UnityTransport` would not accept single words as valid hostnames (notably "localhost"). (#3591)
 - Fixed issue where viewing a `NetworkBehaviour` with one or more `NetworkVariable` fields could throw an exception if running a distributed authority network topology with a local (DAHost) host and viewed on the host when the host is not the authority of the associated `NetworkObject`. (#3578)
 - Fixed issue when using a distributed authority network topology and  viewing a `NetworkBehaviour` with one or more `NetworkVariable` fields in the inspector view would not show editable fields. (#3578)
 
 ### Changed
 
+- Marked `UnityTransport.ConnectionAddressData.ServerEndPoint` as obsolete. It can't work when using hostnames as the server address, and its functionality can easily be replicated using `NetworkEndpoint.Parse`. (#3591)
 - Optimized `NetworkList<T>` indexer setter to skip operations when the new value equals the existing value, improving performance by avoiding unnecessary list events and network synchronization. (#3587)
 
-
 ## [2.5.0] - 2025-08-01
 
 ### Added

com.unity.netcode.gameobjects/Runtime/Transports/UTP/UnityTransport.cs

@@ -7,9 +7,6 @@
 
 using System;
 using System.Collections.Generic;
-#if HOSTNAME_RESOLUTION_AVAILABLE && UTP_TRANSPORT_2_4_ABOVE
-using System.Text.RegularExpressions;
-#endif
 using Unity.Burst;
 using Unity.Collections;
 using Unity.Collections.LowLevel.Unsafe;
@@ -235,7 +232,7 @@ public struct ConnectionAddressData
             [SerializeField]
             public string ServerListenAddress;
 
-            private static NetworkEndpoint ParseNetworkEndpoint(string ip, ushort port)
+            internal static NetworkEndpoint ParseNetworkEndpoint(string ip, ushort port)
             {
                 NetworkEndpoint endpoint = default;
                 if (!NetworkEndpoint.TryParse(ip, port, out endpoint, NetworkFamily.Ipv4))
@@ -245,31 +242,16 @@ private static NetworkEndpoint ParseNetworkEndpoint(string ip, ushort port)
                 return endpoint;
             }
 
-            private void InvalidEndpointError()
-            {
-                Debug.LogError($"Invalid network endpoint: {Address}:{Port}.");
-            }
-
             /// <summary>
             /// Endpoint (IP address and port) clients will connect to.
             /// </summary>
-            public NetworkEndpoint ServerEndPoint
-            {
-                get
-                {
-                    var networkEndpoint = ParseNetworkEndpoint(Address, Port);
-                    if (networkEndpoint == default)
-                    {
-#if HOSTNAME_RESOLUTION_AVAILABLE && UTP_TRANSPORT_2_4_ABOVE
-                        if (!IsValidFqdn(Address))
-#endif
-                        {
-                            InvalidEndpointError();
-                        }
-                    }
-                    return networkEndpoint;
-                }
-            }
+            /// <remarks>
+            /// If a DNS hostname was set as the address, this will return an invalid endpoint. This
+            /// is still handled correctly by NGO, but for this reason usage of this property is
+            /// discouraged.
+            /// </remarks>
+            [Obsolete("Use NetworkEndpoint.Parse on the Address field instead.")]
+            public NetworkEndpoint ServerEndPoint => ParseNetworkEndpoint(Address, Port);
 
             /// <summary>
             /// Endpoint (IP address and port) server will listen/bind on.
@@ -281,32 +263,27 @@ public NetworkEndpoint ListenEndPoint
                     NetworkEndpoint endpoint = default;
                     if (string.IsNullOrEmpty(ServerListenAddress))
                     {
-                        endpoint = NetworkEndpoint.LoopbackIpv4;
-
-                        // If an address was entered and it's IPv6, switch to using ::1 as the
-                        // default listen address. (Otherwise we always assume IPv4.)
-                        if (!string.IsNullOrEmpty(Address) && ServerEndPoint.Family == NetworkFamily.Ipv6)
-                        {
-                            endpoint = NetworkEndpoint.LoopbackIpv6;
-                        }
+                        endpoint = IsIpv6 ? NetworkEndpoint.LoopbackIpv6 : NetworkEndpoint.LoopbackIpv4;
                         endpoint = endpoint.WithPort(Port);
                     }
                     else
                     {
                         endpoint = ParseNetworkEndpoint(ServerListenAddress, Port);
                         if (endpoint == default)
                         {
-                            InvalidEndpointError();
+                            Debug.LogError($"Invalid listen endpoint: {ServerListenAddress}:{Port}. Note that the listen endpoint MUST be an IP address (not a hostname).");
                         }
                     }
                     return endpoint;
                 }
             }
 
             /// <summary>
-            /// Returns true if the end point address is of type <see cref="NetworkFamily.Ipv6"/>.
+            /// Returns true if the end point address is of type <see cref="NetworkFamily.Ipv6"/> or
+            /// if it is a hostname (because in current versions of the engine, hostname resolution
+            /// prioritizes IPv6 addresses).
             /// </summary>
-            public bool IsIpv6 => !string.IsNullOrEmpty(Address) && NetworkEndpoint.TryParse(Address, Port, out NetworkEndpoint _, NetworkFamily.Ipv6);
+            public bool IsIpv6 => !string.IsNullOrEmpty(Address) && !NetworkEndpoint.TryParse(Address, Port, out NetworkEndpoint _, NetworkFamily.Ipv4);
         }
 
 
@@ -667,16 +644,6 @@ private NetworkPipeline SelectSendPipeline(NetworkDelivery delivery)
             }
         }
 
-#if HOSTNAME_RESOLUTION_AVAILABLE && UTP_TRANSPORT_2_4_ABOVE
-        private static bool IsValidFqdn(string fqdn)
-        {
-            // Regular expression to validate FQDN
-            string pattern = @"^(?=.{1,255}$)(?!-)[A-Za-z0-9-]{1,63}(?<!-)\.(?!-)(?:[A-Za-z0-9-]{1,63}\.?)+[A-Za-z]{2,6}$";
-            var regex = new Regex(pattern);
-            return regex.IsMatch(fqdn);
-        }
-#endif
-
         private bool ClientBindAndConnect()
         {
             var serverEndpoint = default(NetworkEndpoint);
@@ -687,44 +654,28 @@ private bool ClientBindAndConnect()
             }
             else
             {
-                serverEndpoint = ConnectionData.ServerEndPoint;
-            }
-
-            // Verify the endpoint is valid before proceeding
-            if (serverEndpoint.Family == NetworkFamily.Invalid)
-            {
-#if HOSTNAME_RESOLUTION_AVAILABLE && UTP_TRANSPORT_2_4_ABOVE
+                // This will result in an invalid endpoint if the address is a hostname.
+                // This is handled later in the Connect method if hostname resolution is available
+                // (although we still check for hostname validity to error out early if it's not),
+                // but if not then we need to error out here.
+                serverEndpoint = ConnectionAddressData.ParseNetworkEndpoint(ConnectionData.Address, ConnectionData.Port);
 
-                // If it's not valid, assure it meets FQDN standards
-                if (IsValidFqdn(ConnectionData.Address))
+                if (serverEndpoint.Family == NetworkFamily.Invalid)
                 {
-                    // If so, then proceed with driver initialization and attempt to connect
-                    InitDriver();
-                    m_Driver.Connect(ConnectionData.Address, ConnectionData.Port);
-                    return true;
-                }
-                else
-                {
-                    // If not then log an error and return false
-                    Debug.LogError($"Target server network address ({ConnectionData.Address}) is not a valid Fully Qualified Domain Name!");
-                    return false;
-                }
+#if HOSTNAME_RESOLUTION_AVAILABLE
+                    if (Uri.CheckHostName(ConnectionData.Address) != UriHostNameType.Dns)
+                    {
+                        Debug.LogError($"Provided connection address \"{ConnectionData.Address}\" is not a valid hostname.");
+                        return false;
+                    }
 #else
-                Debug.LogError($"Target server network address ({ConnectionData.Address}) is {nameof(NetworkFamily.Invalid)}!");
-                return false;
+                    Debug.LogError($"Invalid server address: {ConnectionData.Address}:{ConnectionData.Port}.");
+                    return false;
 #endif
+                }
             }
 
             InitDriver();
-
-            var bindEndpoint = serverEndpoint.Family == NetworkFamily.Ipv6 ? NetworkEndpoint.AnyIpv6 : NetworkEndpoint.AnyIpv4;
-            int result = m_Driver.Bind(bindEndpoint);
-            if (result != 0)
-            {
-                Debug.LogError("Client failed to bind");
-                return false;
-            }
-
             Connect(serverEndpoint);
 
             return true;
@@ -737,30 +688,22 @@ private bool ClientBindAndConnect()
         /// <returns>A <see cref="NetworkConnection"/> representing the connection to the server, or an invalid connection if the connection attempt fails.</returns>
         protected virtual NetworkConnection Connect(NetworkEndpoint serverEndpoint)
         {
+#if HOSTNAME_RESOLUTION_AVAILABLE
+            // If the server endpoint is invalid, it means whatever the user entered in the address
+            // field was not an IP address, and must be presumed to be a hostname.
+            if (serverEndpoint.Family == NetworkFamily.Invalid)
+            {
+                return m_Driver.Connect(ConnectionData.Address, ConnectionData.Port);
+            }
+#endif
             return m_Driver.Connect(serverEndpoint);
         }
 
         private bool ServerBindAndListen(NetworkEndpoint endPoint)
         {
-            // Verify the endpoint is valid before proceeding
             if (endPoint.Family == NetworkFamily.Invalid)
             {
-#if HOSTNAME_RESOLUTION_AVAILABLE && UTP_TRANSPORT_2_4_ABOVE
-                // If it's not valid, assure it meets FQDN standards
-                if (!IsValidFqdn(ConnectionData.Address))
-                {
-                    // If not then log an error and return false
-                    Debug.LogError($"Listen network address ({ConnectionData.Address}) is not a valid {NetworkFamily.Ipv4} or {NetworkFamily.Ipv6} address!");
-                }
-                else
-                {
-                    Debug.LogError($"While ({ConnectionData.Address}) is a valid Fully Qualified Domain Name, you must use a valid {NetworkFamily.Ipv4} or {NetworkFamily.Ipv6} address when binding and listening for connections!");
-                }
                 return false;
-#else
-                Debug.LogError($"Network listen address ({ConnectionData.Address}) is {nameof(NetworkFamily.Invalid)}!");
-                return false;
-#endif
             }
 
             InitDriver();

com.unity.netcode.gameobjects/Runtime/Unity.Netcode.Runtime.asmdef

@@ -68,11 +68,6 @@
             "expression": "6000.0.11f1",
             "define": "COM_UNITY_MODULES_PHYSICS2D_LINEAR"
         },
-        {
-            "name": "com.unity.transport",
-            "expression": "2.4.0",
-            "define": "UTP_TRANSPORT_2_4_ABOVE"
-        },
         {
             "name": "Unity",
             "expression": "6000.1.0a1",

com.unity.netcode.gameobjects/Tests/Editor/Transports/UnityTransportTests.cs

@@ -127,16 +127,11 @@ public void UnityTransport_RestartSucceedsAfterFailure()
             UnityTransport transport = new GameObject().AddComponent<UnityTransport>();
             transport.Initialize();
 
-            transport.SetConnectionData("127.0.0.", 4242, "127.0.0.");
+            transport.SetConnectionData("127.0.0.1", 4242, "foobar");
 
             Assert.False(transport.StartServer());
-            LogAssert.Expect(LogType.Error, "Invalid network endpoint: 127.0.0.:4242.");
+            LogAssert.Expect(LogType.Error, "Invalid listen endpoint: foobar:4242. Note that the listen endpoint MUST be an IP address (not a hostname).");
 
-#if HOSTNAME_RESOLUTION_AVAILABLE && UTP_TRANSPORT_2_4_ABOVE
-            LogAssert.Expect(LogType.Error, "Listen network address (127.0.0.) is not a valid Ipv4 or Ipv6 address!");
-#else
-            LogAssert.Expect(LogType.Error, "Network listen address (127.0.0.) is Invalid!");
-#endif
             transport.SetConnectionData("127.0.0.1", 4242, "127.0.0.1");
             Assert.True(transport.StartServer());
 
@@ -156,24 +151,6 @@ public void UnityTransport_StartServerWithoutAddresses()
             transport.Shutdown();
         }
 
-        // Check that StartClient returns false with bad connection data.
-        [Test]
-        public void UnityTransport_StartClientFailsWithBadAddress()
-        {
-            UnityTransport transport = new GameObject().AddComponent<UnityTransport>();
-            transport.Initialize();
-
-            transport.SetConnectionData("foobar", 4242);
-            Assert.False(transport.StartClient());
-            LogAssert.Expect(LogType.Error, "Invalid network endpoint: foobar:4242.");
-#if HOSTNAME_RESOLUTION_AVAILABLE && UTP_TRANSPORT_2_4_ABOVE
-            LogAssert.Expect(LogType.Error, "Target server network address (foobar) is not a valid Fully Qualified Domain Name!");
-#else
-            LogAssert.Expect(LogType.Error, "Target server network address (foobar) is Invalid!");
-#endif
-            transport.Shutdown();
-        }
-
         [Test]
         public void UnityTransport_EmptySecurityStringsShouldThrow([Values("", null)] string cert, [Values("", null)] string secret)
         {
@@ -206,5 +183,37 @@ public void UnityTransport_EmptySecurityStringsShouldThrow([Values("", null)] st
                 }
             }
         }
+
+#if HOSTNAME_RESOLUTION_AVAILABLE
+        private static readonly (string, bool)[] k_HostnameChecks =
+        {
+            ("localhost", true),
+            ("unity3d.com", true),
+            ("unity3d.com.", true),
+            (string.Empty, false),
+            ("unity3d.com/test", false),
+            ("test%123.com", false),
+        };
+
+        [Test]
+        [TestCaseSource(nameof(k_HostnameChecks))]
+        public void UnityTransport_HostnameValidation((string, bool) testCase)
+        {
+            var (hostname, isValid) = testCase;
+
+            UnityTransport transport = new GameObject().AddComponent<UnityTransport>();
+            transport.Initialize();
+
+            if (!isValid)
+            {
+                LogAssert.Expect(LogType.Error, $"Provided connection address \"{hostname}\" is not a valid hostname.");
+            }
+
+            transport.SetConnectionData(hostname, 4242);
+            Assert.AreEqual(isValid, transport.StartClient());
+
+            transport.Shutdown();
+        }
+#endif
     }
 }

com.unity.netcode.gameobjects/Tests/Editor/Unity.Netcode.Editor.Tests.asmdef

@@ -38,11 +38,6 @@
             "expression": "(0,2022.2.0a5)",
             "define": "UNITY_UNET_PRESENT"
         },
-        {
-            "name": "com.unity.transport",
-            "expression": "2.4.0",
-            "define": "UTP_TRANSPORT_2_4_ABOVE"
-        },
         {
             "name": "Unity",
             "expression": "6000.1.0a1",