#2139 Add ListenLocalhost and ListenAnyIP

Author: Tratcher

samples/SampleApp/Startup.cs

@@ -76,6 +76,13 @@ public static Task Main(string[] args)
                         listenOptions.UseConnectionLogging();
                     });
 
+                    options.ListenLocalhost(basePort + 2, listenOptions =>
+                    {
+                        listenOptions.UseHttps("testCert.pfx", "testPassword");
+                    });
+
+                    options.ListenAnyIP(basePort + 3);
+
                     options.UseSystemd();
 
                     // The following section should be used to demo sockets

src/Kestrel.Core/Internal/AddressBinder.cs

@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics;
 using System.IO;
 using System.Linq;
 using System.Net;
@@ -11,6 +12,7 @@
 using Microsoft.AspNetCore.Hosting.Server.Features;
 using Microsoft.AspNetCore.Protocols;
 using Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Infrastructure;
+using Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal;
 using Microsoft.Extensions.Logging;
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal
@@ -109,140 +111,152 @@ protected internal static bool TryCreateIPEndPoint(ServerAddress address, out IP
             return true;
         }
 
-        private static Task BindEndpointAsync(IPEndPoint endpoint, AddressBindContext context)
-            => BindEndpointAsync(new ListenOptions(endpoint), context);
-
-        private static async Task BindEndpointAsync(ListenOptions endpoint, AddressBindContext context)
+        private static ListenOptions ParseAddress(string address, AddressBindContext context)
         {
-            try
+            var parsedAddress = ServerAddress.FromUrl(address);
+            var https = false;
+
+            if (parsedAddress.Scheme.Equals("https", StringComparison.OrdinalIgnoreCase))
             {
-                await context.CreateBinding(endpoint).ConfigureAwait(false);
+                https = true;
             }
-            catch (AddressInUseException ex)
+            else if (!parsedAddress.Scheme.Equals("http", StringComparison.OrdinalIgnoreCase))
             {
-                throw new IOException(CoreStrings.FormatEndpointAlreadyInUse(endpoint), ex);
+                throw new InvalidOperationException(CoreStrings.FormatUnsupportedAddressScheme(address));
             }
 
-            context.ListenOptions.Add(endpoint);
+            if (!string.IsNullOrEmpty(parsedAddress.PathBase))
+            {
+                throw new InvalidOperationException(CoreStrings.FormatConfigurePathBaseFromMethodCall($"{nameof(IApplicationBuilder)}.UsePathBase()"));
+            }
+
+            ListenOptions options = null;
+            if (parsedAddress.IsUnixPipe)
+            {
+                options = new ListenOptions(parsedAddress.UnixPipePath);
+            }
+            else if (string.Equals(parsedAddress.Host, "localhost", StringComparison.OrdinalIgnoreCase))
+            {
+                if (parsedAddress.Port == 0)
+                {
+                    throw new InvalidOperationException(CoreStrings.DynamicPortOnLocalhostNotSupported);
+                }
+
+                // "localhost" for both IPv4 and IPv6 can't be represented as an IPEndPoint.
+                options = new ListenOptions(ListenType.Localhost)
+                {
+                    IPEndPoint = new IPEndPoint(IPAddress.Loopback, parsedAddress.Port),
+                };
+            }
+            else if (TryCreateIPEndPoint(parsedAddress, out var endpoint))
+            {
+                options = new ListenOptions(endpoint);
+            }
+            else
+            {
+                // when address is 'http://hostname:port', 'http://*:port', or 'http://+:port'
+                options = new ListenOptions(ListenType.AnyIP) { IPEndPoint = new IPEndPoint(IPAddress.IPv6Any, parsedAddress.Port) };
+            }
+
+            if (https)
+            {
+                options.KestrelServerOptions = context.ServerOptions;
+                context.DefaultHttpsProvider.ConfigureHttps(options);
+            }
+
+            return options;
         }
 
-        private static async Task BindLocalhostAsync(ServerAddress address, AddressBindContext context, bool https)
+        private static async Task BindAsync(ListenOptions options, AddressBindContext context)
         {
-            if (address.Port == 0)
+            if (options.Type == ListenType.SocketPath
+                || options.Type == ListenType.IPEndPoint)
+            {
+                await BindEndpointAsync(options, context).ConfigureAwait(false);
+                context.Addresses.Add(options.GetDisplayName());
+            }
+            else if (options.Type == ListenType.Localhost)
+            {
+                // "localhost" for both IPv4 and IPv6 can't be represented as an IPEndPoint.
+                await BindLocalhostAsync(options, context).ConfigureAwait(false);
+            }
+            else if (options.Type == ListenType.AnyIP)
+            {
+                // when address is 'http://hostname:port', 'http://*:port', or 'http://+:port'
+                try
+                {
+                    options = options.CloneAs(ListenType.IPEndPoint);
+                    options.IPEndPoint = new IPEndPoint(IPAddress.IPv6Any, options.IPEndPoint.Port);
+                    await BindEndpointAsync(options, context).ConfigureAwait(false);
+                }
+                catch (Exception ex) when (!(ex is IOException))
+                {
+                    context.Logger.LogDebug(CoreStrings.FormatFallbackToIPv4Any(options.IPEndPoint.Port));
+
+                    // for machines that do not support IPv6
+                    options.IPEndPoint = new IPEndPoint(IPAddress.Any, options.IPEndPoint.Port);
+                    await BindEndpointAsync(options, context).ConfigureAwait(false);
+                }
+                context.Addresses.Add(options.GetDisplayName());
+            }
+            else
             {
-                throw new InvalidOperationException(CoreStrings.DynamicPortOnLocalhostNotSupported);
+                throw new NotImplementedException(options.Type.ToString());
             }
+        }
+
+        private static async Task BindLocalhostAsync(ListenOptions options, AddressBindContext context)
+        {
+            Debug.Assert(options.Type == ListenType.Localhost);
 
             var exceptions = new List<Exception>();
 
             try
             {
-                var options = new ListenOptions(new IPEndPoint(IPAddress.Loopback, address.Port));
-                await BindEndpointAsync(options, context).ConfigureAwait(false);
-                
-                if (https)
-                {
-                    options.KestrelServerOptions = context.ServerOptions;
-                    context.DefaultHttpsProvider.ConfigureHttps(options);
-                }
+                var v4Options = options.CloneAs(ListenType.IPEndPoint);
+                v4Options.IPEndPoint = new IPEndPoint(IPAddress.Loopback, v4Options.IPEndPoint.Port);
+                await BindEndpointAsync(v4Options, context).ConfigureAwait(false);
             }
             catch (Exception ex) when (!(ex is IOException))
             {
-                context.Logger.LogWarning(0, CoreStrings.NetworkInterfaceBindingFailed, address, "IPv4 loopback", ex.Message);
+                context.Logger.LogWarning(0, CoreStrings.NetworkInterfaceBindingFailed, options.GetDisplayName(), "IPv4 loopback", ex.Message);
                 exceptions.Add(ex);
             }
 
             try
             {
-                var options = new ListenOptions(new IPEndPoint(IPAddress.IPv6Loopback, address.Port));
-                await BindEndpointAsync(options, context).ConfigureAwait(false);
-
-                if (https)
-                {
-                    options.KestrelServerOptions = context.ServerOptions;
-                    context.DefaultHttpsProvider.ConfigureHttps(options);
-                }
+                var v6Options = options.CloneAs(ListenType.IPEndPoint);
+                v6Options.IPEndPoint = new IPEndPoint(IPAddress.IPv6Loopback, v6Options.IPEndPoint.Port);
+                await BindEndpointAsync(v6Options, context).ConfigureAwait(false);
             }
             catch (Exception ex) when (!(ex is IOException))
             {
-                context.Logger.LogWarning(0, CoreStrings.NetworkInterfaceBindingFailed, address, "IPv6 loopback", ex.Message);
+                context.Logger.LogWarning(0, CoreStrings.NetworkInterfaceBindingFailed, options.GetDisplayName(), "IPv6 loopback", ex.Message);
                 exceptions.Add(ex);
             }
 
             if (exceptions.Count == 2)
             {
-                throw new IOException(CoreStrings.FormatAddressBindingFailed(address), new AggregateException(exceptions));
+                throw new IOException(CoreStrings.FormatAddressBindingFailed(options.GetDisplayName()), new AggregateException(exceptions));
             }
 
             // If StartLocalhost doesn't throw, there is at least one listener.
             // The port cannot change for "localhost".
-            context.Addresses.Add(address.ToString());
+            context.Addresses.Add(options.GetDisplayName());
         }
 
-        private static async Task BindAddressAsync(string address, AddressBindContext context)
+        private static async Task BindEndpointAsync(ListenOptions endpoint, AddressBindContext context)
         {
-            var parsedAddress = ServerAddress.FromUrl(address);
-            var https = false;
-
-            if (parsedAddress.Scheme.Equals("https", StringComparison.OrdinalIgnoreCase))
-            {
-                https = true;
-            }
-            else if (!parsedAddress.Scheme.Equals("http", StringComparison.OrdinalIgnoreCase))
-            {
-                throw new InvalidOperationException(CoreStrings.FormatUnsupportedAddressScheme(address));
-            }
-
-            if (!string.IsNullOrEmpty(parsedAddress.PathBase))
-            {
-                throw new InvalidOperationException(CoreStrings.FormatConfigurePathBaseFromMethodCall($"{nameof(IApplicationBuilder)}.UsePathBase()"));
-            }
-
-            ListenOptions options = null;
-            if (parsedAddress.IsUnixPipe)
-            {
-                options = new ListenOptions(parsedAddress.UnixPipePath);
-                await BindEndpointAsync(options, context).ConfigureAwait(false);
-                context.Addresses.Add(options.GetDisplayName());
-            }
-            else if (string.Equals(parsedAddress.Host, "localhost", StringComparison.OrdinalIgnoreCase))
+            try
             {
-                // "localhost" for both IPv4 and IPv6 can't be represented as an IPEndPoint.
-                await BindLocalhostAsync(parsedAddress, context, https).ConfigureAwait(false);
+                await context.CreateBinding(endpoint).ConfigureAwait(false);
             }
-            else
+            catch (AddressInUseException ex)
             {
-                if (TryCreateIPEndPoint(parsedAddress, out var endpoint))
-                {
-                    options = new ListenOptions(endpoint);
-                    await BindEndpointAsync(options, context).ConfigureAwait(false);
-                }
-                else
-                {
-                    // when address is 'http://hostname:port', 'http://*:port', or 'http://+:port'
-                    try
-                    {
-                        options = new ListenOptions(new IPEndPoint(IPAddress.IPv6Any, parsedAddress.Port));
-                        await BindEndpointAsync(options, context).ConfigureAwait(false);
-                    }
-                    catch (Exception ex) when (!(ex is IOException))
-                    {
-                        context.Logger.LogDebug(CoreStrings.FormatFallbackToIPv4Any(parsedAddress.Port));
-
-                        // for machines that do not support IPv6
-                        options = new ListenOptions(new IPEndPoint(IPAddress.Any, parsedAddress.Port));
-                        await BindEndpointAsync(options, context).ConfigureAwait(false);
-                    }
-                }
-
-                context.Addresses.Add(options.GetDisplayName());
+                throw new IOException(CoreStrings.FormatEndpointAlreadyInUse(endpoint), ex);
             }
 
-            if (https && options != null)
-            {
-                options.KestrelServerOptions = context.ServerOptions;
-                context.DefaultHttpsProvider.ConfigureHttps(options);
-            }
+            context.ListenOptions.Add(endpoint);
         }
 
         private interface IStrategy
@@ -256,7 +270,7 @@ public async Task BindAsync(AddressBindContext context)
             {
                 context.Logger.LogDebug(CoreStrings.BindingToDefaultAddress, Constants.DefaultServerAddress);
 
-                await BindLocalhostAsync(ServerAddress.FromUrl(Constants.DefaultServerAddress), context, https: false).ConfigureAwait(false);
+                await AddressBinder.BindAsync(ParseAddress(Constants.DefaultServerAddress, context), context).ConfigureAwait(false);
             }
         }
 
@@ -308,9 +322,7 @@ public virtual async Task BindAsync(AddressBindContext context)
             {
                 foreach (var endpoint in _endpoints)
                 {
-                    await BindEndpointAsync(endpoint, context).ConfigureAwait(false);
-
-                    context.Addresses.Add(endpoint.GetDisplayName());
+                    await AddressBinder.BindAsync(endpoint, context).ConfigureAwait(false);
                 }
             }
         }
@@ -328,7 +340,8 @@ public virtual async Task BindAsync(AddressBindContext context)
             {
                 foreach (var address in _addresses)
                 {
-                    await BindAddressAsync(address, context).ConfigureAwait(false);
+                    var options = ParseAddress(address, context);
+                    await AddressBinder.BindAsync(options, context).ConfigureAwait(false);
                 }
             }
         }

src/Kestrel.Core/KestrelServerOptions.cs

@@ -105,6 +105,42 @@ public void Listen(IPEndPoint endPoint, Action<ListenOptions> configure)
             ListenOptions.Add(listenOptions);
         }
 
+        public void ListenLocalhost(int port) => ListenLocalhost(port, options => { });
+
+        public void ListenLocalhost(int port, Action<ListenOptions> configure)
+        {
+            if (configure == null)
+            {
+                throw new ArgumentNullException(nameof(configure));
+            }
+
+            var listenOptions = new ListenOptions(ListenType.Localhost)
+            {
+                KestrelServerOptions = this,
+                IPEndPoint = new IPEndPoint(IPAddress.Loopback, port),
+            };
+            configure(listenOptions);
+            ListenOptions.Add(listenOptions);
+        }
+
+        public void ListenAnyIP(int port) => ListenAnyIP(port, options => { });
+
+        public void ListenAnyIP(int port, Action<ListenOptions> configure)
+        {
+            if (configure == null)
+            {
+                throw new ArgumentNullException(nameof(configure));
+            }
+
+            var listenOptions = new ListenOptions(ListenType.AnyIP)
+            {
+                KestrelServerOptions = this,
+                IPEndPoint = new IPEndPoint(IPAddress.IPv6Any, port),
+            };
+            configure(listenOptions);
+            ListenOptions.Add(listenOptions);
+        }
+
         /// <summary>
         /// Bind to given Unix domain socket path.
         /// </summary>

src/Kestrel.Core/ListenOptions.cs

@@ -21,6 +21,11 @@ public class ListenOptions : IEndPointInformation, IConnectionBuilder
         private FileHandleType _handleType;
         private readonly List<Func<ConnectionDelegate, ConnectionDelegate>> _components = new List<Func<ConnectionDelegate, ConnectionDelegate>>();
 
+        internal ListenOptions(ListenType type)
+        {
+            Type = type;
+        }
+
         internal ListenOptions(IPEndPoint endPoint)
         {
             Type = ListenType.IPEndPoint;
@@ -148,8 +153,11 @@ internal string GetDisplayName()
 
             switch (Type)
             {
+                case ListenType.AnyIP:
                 case ListenType.IPEndPoint:
                     return $"{scheme}://{IPEndPoint}";
+                case ListenType.Localhost:
+                    return $"{scheme}://localhost:{IPEndPoint.Port}";
                 case ListenType.SocketPath:
                     return $"{scheme}://unix:{SocketPath}";
                 case ListenType.FileHandle:
@@ -182,5 +190,20 @@ public ConnectionDelegate Build()
 
             return app;
         }
+
+        // primarily used for cloning localhost to two IPEndpoints
+        internal ListenOptions CloneAs(ListenType type)
+        {
+            var options = new ListenOptions(type)
+            {
+                HandleType = HandleType,
+                IPEndPoint = IPEndPoint,
+                KestrelServerOptions = KestrelServerOptions,
+                NoDelay = NoDelay,
+                Protocols = Protocols,
+            };
+            options.ConnectionAdapters.AddRange(ConnectionAdapters);
+            return options;
+        }
     }
 }

src/Kestrel.Transport.Abstractions/Internal/ListenType.cs

@@ -9,6 +9,8 @@ namespace Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal
     public enum ListenType
     {
         IPEndPoint,
+        Localhost,
+        AnyIP,
         SocketPath,
         FileHandle
     }