Create a direct way to configure endpoints on Kestrel

[Tratcher]

Right now endpoints can only be configured via UseUrls. This limits the opportunity for validation and causes confusion about what's allowed/supported by Kestrel.

e.g. options.AddEndpoint(https, host, port); where scheme is "http" or "https", host is "localhost", "", or an IPAddress, and port is valid. This avoids confusion around why registering "http://.foo.com/" does not filter by host.

@DamianEdwards @davidfowl

[muratg]

@davidfowl to schedule an api design meeting

[DamianEdwards]

@shirhatti let's get this designed for 1.1.0 ASAP pls

[halter73]

Are we willing to change the design/behavior of UseUrls? Will there be an analog for WebListener?

[Tratcher]

WebListener already has WebListenerOptions.ListenerSettings.UrlPrefixes.Add(UrlPrefix)

[shirhatti]

Based on our ( @davidfowl @Tratcher @halter73 @CesarBS ) design meeting yesterday, we made a couple of decisions. Some of these might be obvious but it's still worth explicitly calling out.

• No change in the behavior of the WebHostBuilder extension method .UseUrls(). If you are using Kestrel as your server, we will not filter based on host name. The argument to .UseUrls() only determines if we bind to IPAddress.Any vs IPAddress.Loopback. We are considering adding a middleware to support filtering by hostname. You'll have to opt-in to using that middleware if you want Kestrel to filter requests by hostname.
• Add an extension method to KestrelServerOptions for binding to a TCP socket. There is no overload on .Listen() that allows you to configure an SSL cert without using an options lambda.

var host = new WebHostBuilder()
            .UseKestrel(options =>
            {
                // Easy mode (http only)
                options.Listen(IPAddress.Any, 80);

                // Verbose
                options.Listen(IPAddress.Any, 443, listenOptions => 
                {
                    // Enable https
                    listenOptions.UseHttps("server.pfx");
                });
            })
            .UseStartup<Startup>()
            .Build();

host.Run();

• Add an extension method to KestrelServerOptions for binding to a unix socket. There is no overload on .ListenUnixSocket() that allows you to configure an SSL cert without using an options lambda.

var host = new WebHostBuilder()
            .UseKestrel(options =>
            {
                // Easy mode
                options.ListenUnixSocket("/tmp/kestrel-test.sock");

                // Verbose
                options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions => 
                {
                    listenOptions.UseHttps("server.pfx");
                });
            })
            .UseStartup<Startup>()
            .Build();

host.Run();

• Add an extension method to KestrelServerOptions for binding to a file descriptor. There is no overload on .ListenHandle() that allows you to configure an SSL cert without using an options lambda.

var host = new WebHostBuilder()
            .UseKestrel(options =>
            {

                var fds = Environment.GetEnvironment("SD_LISTEN_FDS_START");
                int fd = Int32.Parse(fds);

                // Easy mode
                options.ListenHandle(fd);

                // Verbose
                options.ListenHandle(fd, listenOptions => 
                {
                    listenOptions.UseHttps("server.pfx");
                });
            })
            .UseStartup<Startup>()
            .Build();
host.Run();

• Given that the file descriptor will be used will oftentimes be used with systemd socket activation (Support systemd socket activation #1057), provide an extension method to KestrelServerOptions that parses the environment variable set by systemd and binds to that file descriptor. This method will no-op if the requisite environment variable has not been set (Similar to how .UseIISIntegration() no-ops).

var host = new WebHostBuilder()
            .UseKestrel(options =>
            {
                options.UseSystemd();
            })
            .UseStartup<Startup>()
            .Build();
host.Run();

[muratg]

@shirhatti Is it OK to remove needs-design label then?