LSQUIC Documentation

Each frame written to the po_data buffer of an outgoing packet has an associated frame record stored in po_frecs.

Frame records serve two primary purposes:

1. Tracking Acknowledgments: They track the number of unacknowledged stream frames for a stream. When a packet is acknowledged, the frame records are iterated over to call lsquic_stream_acked().
2. Packet Resizing: They record the type, position, and size of a frame to speed up resizing operations.

In optimized use cases where a packet contains only a single frame (such as a single STREAM frame from a sender or a single ACK frame from a receiver), the frame record is stored directly in the packet struct via a union to save space.

struct frame_rec {
    union {
        struct lsquic_stream   *stream;
        uintptr_t               data;
    }                        fe_u;
    unsigned short           fe_off, 
                                 fe_len;
    enum quic_frame_type     fe_frame_type;
};

LSQUIC batches outgoing packets to improve efficiency. The send_packets_out function iterates over connections in the Outgoing queue, encrypts their packets, and adds them to an out_batch.

Key Batching Concepts:

• Fairness: Packets from different connections are interleaved in the batch (e.g., A1, B1, C1, A2, B2, C2) to ensure no single connection starves others.
• Packet Coalescing: For IETF QUIC connections during the handshake, multiple packets can be coalesced into a single UDP datagram to reduce overhead. This is controlled by the ENG_COALESCE flag.
• Batch Resizing: The batch size is dynamic. It grows (up to MAX_OUT_BATCH_SIZE) if all datagrams are sent successfully, and shrinks if not.
• User Callback: When a batch is full, it is passed to the user-supplied callback. The user must call ci_packet_sent for successful packets or ci_packet_not_sent for failed ones.

An lsquic_stream is the primary conduit for data in the library. It is a bidirectional object that represents the data flow for a specific request/response pair (e.g., an HTTP request from a client and its corresponding response from a server).

Key Characteristics:

• Bidirectional: Both clients and servers use the same stream object to read and write data.
• Abstraction: The stream abstracts away the underlying QUIC protocol details. Whether using gQUIC (HANDSHAKE/HEADERS streams) or IETF QUIC (up to four HANDSHAKE streams), or HTTP/3 (Settings, QPACK encoder/decoder streams), the user interacts with the stream via the same lsquic_stream_* API.
• Lifecycle: Streams are managed by a full connection and are identified by a unique id used for hashing.
• Event-Driven: Streams use "on stream read" and "on stream write" callbacks. Users register interest in reading or writing, and the library dispatches these events when possible.

LSQUIC uses an event-driven model for stream I/O. To receive notifications when a stream is ready for I/O, you must use the following mechanism:

1. Register Interest: Call lsquic_stream_wantwrite or lsquic_stream_wantread. This places the stream on the corresponding "want to write" or "want to read" list.
2. Connection Tick: When the connection is "ticked" (processed), it iterates through these lists.
3. Dispatch: The connection calls internal dispatch functions (lsquic_stream_dispatch_read_events or lsquic_stream_dispatch_write_events) which trigger your registered user callbacks.

Read Dispatch Behavior:

• If es_rw_once is set, the "on stream read" callback is called exactly once if the stream is readable.
• Otherwise, the callback is called in a loop as long as the stream is readable, the user still wants to read, and progress is being made.

Write Dispatch Behavior:

• The "on stream write" callback is called, and the library also utilizes a flushing mechanism via the "want to write" list.

Writing to a stream is handled by several user-facing functions (wrappers around stream_write).

Buffering and Packetization:

• Small Writes: Small amounts of data are buffered in sm_buf.
• Thresholds: If the buffered data plus the new write exceeds a specific threshold (the size of the largest STREAM frame that fits in a single packet), the data is immediately packetized.
• Efficiency: This thresholding prevents "jagged" STREAM frames, ensuring bandwidth is used effectively by allowing larger, more efficient frames.
• Flushing: When explicitly flushing data, the threshold is ignored, and even a 1-byte write will trigger packetization.

HTTP/3 Specifics: In HTTP/3 mode, framing (HEADERS and DATA frames) is added transparently. The user code does not need to manually manage HTTP/3 frame headers; the library generates them on-the-fly during the packetization process.