Consider a capsule API

[huitema]

The capsule API is defined in the "datagram" extension, and as part of the "extended connect" process. After an extended connect, the control stream is upgraded and can only be used to carry "capsules". There is limited support for capsules in the current h3zero code:

int h3zero_send_capsule(picoquic_cnx_t* cnx, h3zero_stream_ctx_t* control_stream_ctx,
	uint64_t capsule_type, size_t capsule_length, uint8_t* capsule_data, int set_fin);
const uint8_t* h3zero_accumulate_capsule(const uint8_t* bytes, const uint8_t* bytes_max, h3zero_capsule_t* capsule, 
        h3zero_stream_ctx_t * stream_ctx);
void h3zero_release_capsule(h3zero_capsule_t* capsule);
void h3zero_receive_datagram_capsule(picoquic_cnx_t* cnx, h3zero_stream_ctx_t* stream_ctx, h3zero_capsule_t* capsule,
        h3zero_callback_ctx_t* h3_ctx);

The sending API is simple, but the receiving is complicated. The receiving application is supposed to receive data through the path callback "picohttp_callback_post_data", notice that this refers to the control stream, reserve a capsule buffer, call h3zero_accumulate_capsule to fill the capsule buffer, and finally release the capsule buffer at the end of the connection. The "accumulate" API does not actually provide the capsule to the application, it merely logs it.

Applications would be simpler to write if they could simply subscribe to the "capsule" protocol when opening the control stream, and receive a capsule callback when a capsule is received. The callback would provide the capsule type, length and value.

For web transport applications, this could be simplified further. Web transport defines several types of capsules: close, drain, and various flow control actions. The implementation of web transport could intercept these known types and process them, for example replacing a "close" capsule notification by a "close" callback that would parallel the "close" callback in the raw QUIC API.