Developing Apps for Native and Web Transport

[huitema]

There are two broad ways to use QUIC: develop a native application, or describe the application as a web transport application. The main advantage of the "web transport" approach is that a version of the application's client can be developed using java script or equivalents, proposed via a web page, and run inside a browser. On the other hand, native clients will typically consume fewer resource or have better performance than if they were running in a web page. Given that, there will be many cases in which the applications' server will need to support both native clients and clients running over web transport.

The application code interfaces with the stack using Native or Web transport APIs, and are notified of stack events using either a native QUIC callback and an HTTP3/Web transport callback.

The callbacks of the two stacks are somewhat equivalent, but they are different. The first step in our design is to see whether they could be unified.

There is some equivalence between the callbacks for sending and receiving data. Some of the callbacks are not defined yet, such as "stop sending", but they make sense and could be added.

Native call back	Web transport	Description
picoquic_callback_stream_data	picohttp_callback_post_data	Data received from peer on stream N
picoquic_callback_stream_fin	picohttp_callback_post_fin	Fin received from peer on stream N; data is optional
picoquic_callback_prepare_to_send	picohttp_callback_provide_data	Ask application to send data in frame
picoquic_callback_datagram	picohttp_callback_post_datagram	Datagram frame has been received
picoquic_callback_prepare_datagram	picohttp_callback_provide_datagram	Prepare the next datagram
picoquic_callback_datagram_acked		Ack for packet carrying datagram-frame received from peer
picoquic_callback_datagram_lost		Packet carrying datagram-frame probably lost
picoquic_callback_datagram_spurious		Packet carrying datagram-frame was not really lost
picoquic_callback_stream_reset	picohttp_callback_reset	Reset Stream received from peer on stream N
picoquic_callback_stop_sending		Stop sending received from peer on stream N
picoquic_callback_app_wakeup		wakeup timer set by application has expired

The two variants have different connection management callbacks. It might be possible to unify them,
since for example "Get" and "Post" are not used for Web Transport, and we might find rough equivalence in others.
Or, we might define additional "native" callbacks as part of unification.

Native call back	Web transport	Description
picoquic_callback_almost_ready		Data can be sent, but the connection is not fully established
picoquic_callback_ready		Data can be sent and received
picoquic_callback_stateless_reset		Stateless reset received from peer
picoquic_callback_close		Connection close.
picoquic_callback_application_close		Application closed by peer
picoquic_callback_version_negotiation		version negotiation requested
	picohttp_callback_get	Received a get command
	picohttp_callback_post	Received a post command
	picohttp_callback_connecting	Sending out a connect command
	picohttp_callback_connect	Received a connect command
	picohttp_callback_connect_refused	Connection request was refused by peer
	picohttp_callback_connect_accepted	Connection request was accepted by peer
	picohttp_callback_deregister	Context has been deregistered
	picohttp_callback_free

Some native callbacks have no obvious equivalent, may just get unused if doing web transport.

Native call back	Web transport	Description
picoquic_callback_request_alpn_list		Provide the list of supported ALPN
picoquic_callback_set_alpn		Set ALPN to negotiated value
picoquic_callback_stream_gap		Not used

The path management APIs are mostly used for multipath, which is not really used with web transport, but the pathh quality reporting could be used for web transport just as well/

Native call back	Web transport	Description
picoquic_callback_pacing_changed		Pacing rate for the connection changed
picoquic_callback_path_available		A new path is available, or a suspended path is available again
picoquic_callback_path_deleted		An existing path has been deleted
picoquic_callback_path_quality_changed		Some path quality parameters have changed
picoquic_callback_path_address_observed		The peer has reported an address for the path
picoquic_callback_next_path_allowed		There are enough path_id and connection ID available for the next path

[huitema]

Let's take a look at the initial connection management. When the application starts on the client, we have slightly different actions:

• the native client creates a connection context,
• the web transport client has to create contexts for the QUIC connection, for H3, and for the web transport.

For the native client, the application state is contained in the picoquic callback context, which will be updated as the application progresses. For the web client, the picoquic callback context is set by H3, and the application state is contained in the web transport context.

On the server side, we have other differences.

• the native application context is created on the first call to the callback, typically picoquic_callback_almost_ready
• the web transport context is created after the callback picohttp_callback_connect.

On the server, we could try mapping picoquic_callback_almost_ready and picohttp_callback_connect, but there are differences. The native call has no parameter, it is just a signal to start sending 0.5RTT data if appropriate. The web transport call passes the incoming "path" parameters -- for example, in the devious baton sample, the application will read how many rounds of the baton are expected. The application will have to parse that. If it needs to refuse the call, it does that by returning an error code, otherwise the call is automatically accepted. An application that does not parse path parameters can treat picoquic_callback_almost_ready and picohttp_callback_connect the same way.

The native client will receive the picoquic_callback_almost_ready callback when the session keys have been negotiated, and then the picoquic_callback_almost_ready callback when the server has completed the handshake (handshake done) and the keys have been verified. The web transport client receives the picohttp_callback_connecting callback when the connect request has been sent, and the picohttp_callback_connect_accepted callback when the response to the connect request arrives.

On the client side, the picohttp_callback_connecting web transport callback plays the same role as the picoquic_callback_almost_ready: from that point, it is possible to start and receive datagrams and streams. Possible but risky: most of the time, data sent after the "connect" request will arrive after it, but given packet losses or other issues could cause out of order delivery. If the streams or datagrams arrive at the server before the connect request, they will most probably be lost. This is a different level of risk than what happens with the native callback. It might be safer to just wait for picohttp_callback_connect_accepted.