Listener options

docs/fundamentals/networking/quic/quic-options.md

@@ -0,0 +1,23 @@
+---
+title: QUIC configuration options in .NET
+description: Learn details about the configuration for QUIC protocol in .NET.
+ms.date: 01/11/2025
+---
+# QUIC configuration options
+
+`System.Net.Quic` library uses options classes to configure the protocol objects (<xref:System.Net.Quic.QuicListener> and <xref:System.Net.Quic.QuicConnection>) before their construction and initialization. There are three different options classes to do that:
+
+- <xref:System.Net.Quic.QuicListenerOptions>: to configure <xref:System.Net.Quic.QuicListener> before starting with <xref:System.Net.Quic.QuicListener.ListenAsync(System.Net.Quic.QuicListenerOptions,System.Threading.CancellationToken)?displayProperty=nameWithType>
+- <xref:System.Net.Quic.QuicClientConnectionOptions>: to configure outgoing <xref:System.Net.Quic.QuicConnection> before establishing it via <xref:System.Net.Quic.QuicConnection.ConnectAsync(System.Net.Quic.QuicClientConnectionOptions,System.Threading.CancellationToken)?displayProperty=nameWithType>
+- <xref:System.Net.Quic.QuicServerConnectionOptions>: to configure incoming <xref:System.Net.Quic.QuicConnection> before handing it out from <xref:System.Net.Quic.QuicListener.AcceptConnectionAsync(System.Threading.CancellationToken)?displayProperty=nameWithType>
+
+All of the options classes can be set up incrementally, meaning that they do not require any of their properties to be initialized via constructor. But the moment they are being used to configure a new listener or a connection, the options are validated and an appropriate type of  <xref:System.ArgumentException> is thrown for any missing mandatory values or misconfigured ones. For example, if mandatory <xref:System.Net.Quic.QuicClientConnectionOptions.DefaultStreamErrorCode?displayProperty=nameWithType> is not set, calling <xref:System.Net.Quic.QuicConnection.ConnectAsync(System.Net.Quic.QuicClientConnectionOptions,System.Threading.CancellationToken)> will throw <xref:System.ArgumentOutOfRangeException>.
+
+## `QuicListenerOptions`
+
+These options are used in <xref:System.Net.Quic.QuicListener.ListenAsync(System.Net.Quic.QuicListenerOptions,System.Threading.CancellationToken)?displayProperty=nameWithType> when starting a new <xref:System.Net.Quic.QuicListener>. The individual configuration properties are:
+
+- <xref:System.Net.Quic.QuicListenerOptions.ApplicationProtocols>: defines the application protocols accepted by this server ([RFC 7301 - ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)). It can contain multiple values for different protocols that might not be related. In the process of accepting a new connection, listener can narrow down or select one specific protocol for each incoming connection, see <xref:System.Net.Quic.QuicListenerOptions.ConnectionOptionsCallback?displayProperty=nameWithType>. **This property is mandatory and must contains at least one value.**
+- <xref:System.Net.Quic.QuicListenerOptions.ConnectionOptionsCallback>: delegate to choose <xref:System.Net.Quic.QuicServerConnectionOptions> for an incoming connection. The function is given <xref:System.Net.Quic.QuicConnection> (not fully initialized yet) and <xref:System.Net.Security.SslClientHelloInfo> containing the server name requested by the client ([RFC 6066 - SNI](https://www.rfc-editor.org/rfc/rfc6066.html#section-3)). The delegate is invoked for each incoming connection. It can return different options based on the client info provided or it can safely return the very same instance of the options every time. The delegate purpose and shape is intentionally similar to <xref:System.Net.Security.ServerOptionsSelectionCallback> used in <xref:System.Net.Security.SslStream.AuthenticateAsServerAsync(System.Net.Security.ServerOptionsSelectionCallback,System.Object,System.Threading.CancellationToken)?displayProperty=nameWithType>. **This property is mandatory.**
+- <xref:System.Net.Quic.QuicListenerOptions.ListenBacklog>: determines how many incoming connections can be held by the listener before they start being refused. Every attempt to establish a connection counts, even when it fails or when the connection gets shut down while waiting in the accept queue. Ongoing processes to establish a new connection count towards this limit as well. Connections or connection attempts are counted until they are retrieved via <xref:System.Net.Quic.QuicListener.AcceptConnectionAsync(System.Threading.CancellationToken)?displayProperty=nameWithType>. The purpose of the backlog limit is to prevent servers from being overwhelmed by more incoming connections than it can process. **This property is optional, default is 512.**
+- <xref:System.Net.Quic.QuicListenerOptions.ListenEndPoint>: IP address and port on which the listener will accept new connections. Due to underlying implementation, `MsQuic`, the listener will always bind to dual-stack wildcard socket regardless to what is specified here. This can lead to some unexpected behaviors, especially in comparison with ordinary TCP sockets like in HTTP/1.1 and HTTP/2 cases. Please see [QUIC Troubleshooting Guide](quic-troubleshooting.md) for more details. **This property is mandatory.**

docs/fundamentals/toc.yml

@@ -1152,6 +1152,8 @@ items:
             items:
               - name: QUIC support
                 href: networking/quic/quic-overview.md
+              - name: QUIC configuration options
+                href: networking/quic/quic-options.md
               - name: QUIC troubleshooting
                 href: networking/quic/quic-troubleshooting.md
           - name: Telemetry