HTTP2 scenario coverage

[Tratcher]

This is for tracking notes about HTTP/2 related features in 2.2. Most of the work will be related to Kestrel, but HttpSys and IIS In-Proc will also get a few notes.

HTTP/2 support is limited by TLS ALPN availability on various platforms.

Kestrel

• OS
  • Windows 8.1+
  • Linux W/OpenSSL 1.0.2 (e.g. Ubuntu 16.04)
  • Mac - Not yet supported - https://github.com/dotnet/corefx/issues/30492
• Framework
  • NetCoreApp 2.2 or later
  • .NET Framework - Not yet supported

Not ASP.NET Core version specific, only constrained by the OS:

HttpSysServer

• Win10+
• Not framework specific

IIS In proc

• Win10+
• .NET Core (in proc restriction)

IIS Out of proc

• Win10+
• The front end can use HTTP/2, but the reverse proxy to Kestrel will continue to use HTTP/1.1.
• Not framework specific

[Tratcher]

New kestrel APIs:

• Http2Limits: https://github.com/aspnet/KestrelHttpServer/blob/release/2.2/src/Kestrel.Core/Http2Limits.cs
• ListenOptions.Protocols: https://github.com/aspnet/KestrelHttpServer/blob/f38f60f8cefe45bd4078b25773becc105b8c7bbc/src/Kestrel.Core/ListenOptions.cs#L130 (expect the default to change before RTM Set default to HTTP/1.1 for RTM aspnet/KestrelHttpServer#2775)
• New config schema to set HttpProtocols: Map ListenOptions.Protocols from IConfiguration aspnet/KestrelHttpServer#2908

[guardrex]

@Tratcher

A Tale of Two Options

1. Split HTTP/2 coverage across the server topics, where the content is maintained within the existing topics.
2. Provide a dedicated HTTP/2 topic that would appear in the Servers node of the TOC. The topic would break down along the lines of the outline you provided in the OP ☝️.

TOC and topic proposal (for Option 2):

• Fundamentals
  • Servers
    • Kestrel
    • ASP.NET Core Module
    • HTTP.sys
    • HTTP/2

Title: HTTP/2 support in ASP.NET Core
Description: Discover how HTTP/2, the latest HTTP network protocol, is supported in ASP.NET Core.
Location: fundamentals\servers\http2.md
UID: fundamentals/servers/http2

👉 Which way would u like to go?

[Tratcher]

Why not both? 😁

There won't be a lot of common HTTP/2 content so the first option should be adequate. Having the second page too that gives you an overview of all your options would be a bonus.

[guardrex]

Let's go ahead with Option 1. I'm just concerned about the size of the Kestrel and IIS topics (and to some extent versioning hell 😈 in the Kestrel topic). This would have been an opportunity to (mostly) cleanly break out a subject into its own topic. However, it probably is less work and a cost savings to roll it into the existing topics.

Side-note on the Kestrel topic: I'm not happy with the heading/section structure of the topic, especially for the config/options subject matter, given how much content was placed into the topic for 2.0 and 2.1. Without good section support, the topic has become a kind of word wall/code wall and the topic's internal TOC is just about useless. ☹️ I might do some work on this for the PR, but I've opened #8496 to make sure it gets addressed later.

RE: Both

Wouldn't that be duplicate coverage? I'm looking at the backlog, too. 🏃 😅 Might be best to put the call for a standalone topic on a new issue.

[Tratcher]

The part you don't get with option 1 is the high level side-by-side comparison. E.g. which server should I use? Option 2 wouldn't need to include the extra details like #7161 (comment).

When we get around to server push then we'll want a shared HTTP/2 doc because that would be a common API across multiple servers. dotnet/aspnetcore#2727. That likely won't happen until 3.0 though.

[guardrex]

the high level side-by-side comparison

We could (for the time being until 3.0) place that content into the Servers landing page: https://docs.microsoft.com/aspnet/core/fundamentals/servers/

... and then link back out to it from the individual topics. Later, that content could move to the dedicated HTTP/2 topic.

[guardrex]

... or bite the bullet and go ahead and create the dedicated HTTP/2 topic now with it. That wouldn't take long if a basic set of guiding principles for server selection is provided there. (No duplication of what's going into the individual topics.)

[Tratcher]

The server landing page would be a good start.

[guardrex]

ok

[guardrex]

@Tratcher When you say "high level side-by-side comparison," do you mean that you want the content rolled into each server section of the Servers landing page, or you you want one HTTP/2 support section laid out similar to the way you have them outlined in the OP ☝️?

https://docs.microsoft.com/aspnet/core/fundamentals/servers/

[Tratcher]

One HTTP/2 section like the OP. There are enough caveats around versions that it's nice to see side by side.

[guardrex]

@Tratcher Your OP suggests that the IIS in-process deployment scenario relies on the Kestrel limits+options ... is that correct?

... similar question on HTTP.sys. I don't see new props in the HttpSysOptions, so is it configured entirely thru registry settings? I don't see a topic anywhere that explains HTTP/2 config for HTTP.sys; so if it is configured via HTTP.sys, I don't know what to link to or examine for more information.

[Tratcher]

@Tratcher Your OP suggests that the IIS in-process deployment scenario relies on the Kestrel limits+options ... is that correct?

No, IIS in-process is completely independent of Kestrel. Its HTTP/2 configuration/limitations stem from Http.Sys.

For IIS/HttpSysServer/Http.Sys HTTP/2 was not initially configurable, it was automatically on if the base requirements were met (TLS, ALPN, Win10). The Http.Sys team is only now retroactively adding APIs and config flags to disable it. One is netsh http add sslcert [disablehttp2=enable|disable]. @shirhatti do you have any doc links for this feature in IIS?

[Tratcher]

For now there are no new APIs for HttpSysServer or IIS, only HttpRequest.Protocol will indicate if HTTP/2 was negotiated.

[guardrex]

IIS in-process is completely independent of Kestrel

Independent of Kestrel but not independent of the TFM/app framework [i.e., ".NET Core (in proc restriction)"] ... that's why I thought they might be connected.

One approach we could take: I can go ahead with what I have (it's not very much text to review), and you can correct it and indicate what it's missing on review.

RE: HTTP.sys

disablehttp2 hasn't reached the command doc yet ( https://docs.microsoft.com/windows/desktop/http/add-sslcert ).

[guardrex]

Another slightly confusing point: This issue and your OP say for 2.2, but your outline states 2.1. Not sure how to version it. However, we can fix that stuff on review easily enough.

[EDIT] ... and I'm noting on the server-side: WS2016 or better (Win10 equivalent) ... and for IIS, IIS 10 or better.

[Tratcher]

Edited to clarify 2.2 for Kestrel and no version for the others.

The HttpSysServer/IIS/Http.Sys stuff isn't dependent on the version of ASP.NET Core since the functionality is all provided by the OS. The only change to these for 2.2 is making HttpRequest.Protocol correctly report HTTP/2.