QuicStream default error code API limitation

[PatrikTrefil]

Currently, we can set a default stream error code for all QuicStream instances associated with a QuicConnection. This default value must be set using QuicConnectionOptions.DefaultStreamErrorCode.

In some scenarios, it may be useful to be able to set default stream error codes per stream and also to be able to modify the value during the lifetime of the object. The following paragraph will explain why.

The QuicConnectionOptions.DefaultStreamErrorCode is used by System.Net.Http when setting up a QUIC connection for HTTP/3. It uses the value (long)Http3ErrorCode.RequestCancelled. This is built on the assumption, that when the stream's read/write side needs to be closed internally, it always means an HTTP/3 request is cancelled. This assumption is true now, but we might not be able to rely on it the future. If support for WebTransport over HTTP/3 is added, we run into problems. The way the protocol works is that a QUIC connection is shared between the HTTP/3 protocol and the WebTransport over HTTP/3 protocol. If we have a QUIC stream that is used by WebTransport over HTTP/3 and we need to close the read/write side internally, the HTTP/3 error code is used, which is an invalid stream error code in the WebTransport over HTTP/3 protocol. Currently, there are two scenarios when this might happen. The first one is during disposal of a WebTransport stream, which works as a wrapper around a QUIC stream. In this scenario the solution is simple - we just call QuicStream.Abort with the desired error code before we call QuicStream.Dispose. The second scenario when the default error code is applied is during operation cancellations. Consider the following code:

WebTransportStream stream = ...;
byte[] data = ...;
CancellationTokenSource cts = new();
ValueTask writeTask = stream.WriteAsync(data, cts.Token);
cts.Cancel();

If WebTransportStream.WriteAsync just passed the cancellation token to QuicStream.WriteAsync, the result would be that the write side is closed using the HTTP/3 error code. This behavior is invalid in WebTransport over HTTP/3. Therefore, the WebTransport over HTTP/3 implementation must work around this as follows:

class WebTransportStream : Stream {
    public override ValueTask WriteAsync(byte[] data, CancellationToken cancellationToken) {
        CancellationTokenRegistration ctr? = null;
        if (cancellationToken.CanBeCanceled)
        {
            ctr = cancellationToken.Register(() =>
            {
                _quicStream.Abort(abortDirection, _remappedDefaultStreamErrorCode);
            });
        }
        try
        {
            await _quicStream.WriteAsync(buffer.AsMemory(offset, count)).ConfigureAwait(false);
        }
        catch (QuicException ex)
        {
            / * exception handling * /
        }
        finally
        {
            if (ctr.HasValue)
            {
                await ctr.Value.DisposeAsync().ConfigureAwait(false);
            }
        }
    }
}

The same handling of the cancellation token is required for all async operations that support a cancellation token. If we were able to assign a default stream error code for every instance of a QuicStream, the code would be much simpler.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/ncl
See info in area-owners.md if you want to be subscribed.

[ManickaP]

Thanks for filing, I've spoken to @CarnaViire about this so I have some background and understand the need for it.
However, it's not that easy to do. If we expose a mutable property on the stream, what happens if there's already cancelable operation in progress; what if someone tries to change it concurrently; etc...
I can imagine changing the code before we hand out the stream instance (while we still have full control over it) via:

• AcceptInboundStreamAsync
• OpenOutboundStreamAsync

But AFAIU this is not enough for your case, right? Could you please also include the description for this scenario as well?

[rzikm]

If WebTransportStream.WriteAsync just passed the cancellation token to QuicStream.WriteAsync, the result would be that the write side is closed using the HTTP/3 error code. This behavior is invalid in WebTransport over HTTP/3.

Is default stream error code required at the WebTransport level? Webtransport layer still needs to deal with any and all HTTP/3 level errors that can happen on the stream/connection errors (e.g. H3_ID_ERROR is a HTTP/3 error, not a "WebTransport over HTTP/3 error").

I am not opposed to an API change to provide more flexibility, but from casual reading of the WebTransport over HTTP/3 RFC I don't see anything prohibiting a teardown of a stream with a HTTP/3 error code, it just means that when receiving a STOP_SENDING or STREAM_RESET QUIC frame, the receiver needs to distinguish whether the error occured at

• Application level
• Webtransport level
• Http/3 level

[ManickaP]

Hmm, reading the RFC, seems like WebTransport is supposed to use a different QUIC Frame for RESET_STREAM_AT: https://www.ietf.org/archive/id/draft-ietf-webtrans-http3-14.html#name-resetting-data-streams

I'm gonna push this to future, this seems to be still evolving and becoming more and more convoluted.

[PatrikTrefil]

TL;DR

But AFAIU this is not enough for your case, right?

Changing the code before the stream instance is handed out would not be sufficient.

Is default stream error code required at the WebTransport level?

As I understand it, we always need to send a valid WebTransport stream error code.

Detailed explanation

In WebTransport, there are 2 types of streams - the CONNECT stream and data streams. The CONNECT stream is used to exchange configuration data about the session. This stream is created during the initial handshake. The client makes an extended CONNECT request and if successful, the stream is then used as a CONNECT stream for the session. In other words, this stream is first used as an HTTP stream and later as a CONNECT stream. This stream can use the default stream error code for HTTP, because WebTransport does not use the stream error code in any way. Once a session is established, the client may open/receive new streams (data streams) that are used only for WebTransport and their error codes have a strictly defined meaning. Here is the excerpt from the RFC (draft version 14) about error codes of data streams:

A WebTransport endpoint may send a RESET_STREAM or a STOP_SENDING frame for a WebTransport data stream. Those signals are propagated by the WebTransport implementation to the application.
A WebTransport application MUST provide an error code for those operations. Since WebTransport shares the error code space with HTTP/3, WebTransport application errors for streams are limited to an unsigned 32-bit integer, assuming values between 0x00000000 and 0xffffffff. WebTransport implementations MUST remap those error codes into the error range reserved for WT_APPLICATION_ERROR...
...
WebTransport endpoints MUST forward the error code for a stream associated with a known session to the application that owns that session. ...

My interpretation of this is that all implementations are required to always send valid WebTransport error codes.

If the user could only open new outbound WebTransport streams, the API that allows to specify the default stream error code per stream could be sufficient, because we know in advance that stream will be used as a WebTransport stream. But, the user can also receive inbound WebTransport streams, and this API would not be sufficient for receiving streams.
Let me explain how the receiving of streams works. When an HTTP/3 connection is established, a QUIC connection is created. Every WebTransport session is associated with the HTTP connection that was used for the initial extended CONNECT request. The WebTransport session shares the QUIC connection with the HTTP connection. When HttpClient receives a new QUIC stream, we do not know for which protocol the stream is intended. Only after reading the first couple of bytes, we find out if the stream is intended for HTTP, or WebTransport, or any other traffic. Only after that, we can identify if we need to change the default stream error code. Therefore, we would need it to be a mutable property.