path: root/include/internal/quic_stream_map.h

/*
* Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
*
* Licensed under the Apache License 2.0 (the "License").  You may not use
* this file except in compliance with the License.  You can obtain a copy
* in the file LICENSE in the source distribution or at
* https://www.openssl.org/source/license.html
*/

#ifndef OSSL_INTERNAL_QUIC_STREAM_MAP_H
# define OSSL_INTERNAL_QUIC_STREAM_MAP_H
# pragma once

# include "internal/e_os.h"
# include "internal/time.h"
# include "internal/common.h"
# include "internal/quic_types.h"
# include "internal/quic_stream.h"
# include "internal/quic_fc.h"
# include <openssl/lhash.h>

# ifndef OPENSSL_NO_QUIC

/*
 * QUIC Stream
 * ===========
 *
 * Logical QUIC stream composing all relevant send and receive components.
 */
typedef struct quic_stream_st QUIC_STREAM;

typedef struct quic_stream_list_node_st QUIC_STREAM_LIST_NODE;

struct quic_stream_list_node_st {
    QUIC_STREAM_LIST_NODE *prev, *next;
};

/*
 * QUIC Send Stream States
 * -----------------------
 *
 * These correspond to the states defined in RFC 9000 s. 3.1, with the
 * exception of the NONE state which represents the absence of a send stream
 * part.
 *
 * Invariants in each state are noted in comments below. In particular, once all
 * data has been acknowledged received, or we have reset the stream, we don't
 * need to keep the QUIC_SSTREAM and data buffers around. Of course, we also
 * don't have a QUIC_SSTREAM on a receive-only stream.
 */
#define QUIC_SSTREAM_STATE_NONE         0   /* --- sstream == NULL  */
#define QUIC_SSTREAM_STATE_READY        1   /* \                    */
#define QUIC_SSTREAM_STATE_SEND         2   /* |-- sstream != NULL  */
#define QUIC_SSTREAM_STATE_DATA_SENT    3   /* /                    */
#define QUIC_SSTREAM_STATE_DATA_RECVD   4   /* \                    */
#define QUIC_SSTREAM_STATE_RESET_SENT   5   /* |-- sstream == NULL  */
#define QUIC_SSTREAM_STATE_RESET_RECVD  6   /* /                    */

/*
 * QUIC Receive Stream States
 * --------------------------
 *
 * These correspond to the states defined in RFC 9000 s. 3.2, with the exception
 * of the NONE state which represents the absence of a receive stream part.
 *
 * Invariants in each state are noted in comments below. In particular, once all
 * data has been read by the application, we don't need to keep the QUIC_RSTREAM
 * and data buffers around. If the receive part is instead reset before it is
 * finished, we also don't need to keep the QUIC_RSTREAM around. Finally, we
 * don't need a QUIC_RSTREAM on a send-only stream.
 */
#define QUIC_RSTREAM_STATE_NONE         0   /* --- rstream == NULL  */
#define QUIC_RSTREAM_STATE_RECV         1   /* \                    */
#define QUIC_RSTREAM_STATE_SIZE_KNOWN   2   /* |-- rstream != NULL  */
#define QUIC_RSTREAM_STATE_DATA_RECVD   3   /* /                    */
#define QUIC_RSTREAM_STATE_DATA_READ    4   /* \                    */
#define QUIC_RSTREAM_STATE_RESET_RECVD  5   /* |-- rstream == NULL  */
#define QUIC_RSTREAM_STATE_RESET_READ   6   /* /                    */

struct quic_stream_st {
    QUIC_STREAM_LIST_NODE active_node; /* for use by QUIC_STREAM_MAP */
    QUIC_STREAM_LIST_NODE accept_node; /* accept queue of remotely-created streams */
    QUIC_STREAM_LIST_NODE ready_for_gc_node; /* queue of streams now ready for GC */

    /* Temporary link used by TXP. */
    QUIC_STREAM    *txp_next;

    /*
     * QUIC Stream ID. Do not assume that this encodes a type as this is a
     * version-specific property and may change between QUIC versions; instead,
     * use the type field.
     */
    uint64_t        id;

    /*
     * Application Error Code (AEC) used for STOP_SENDING frame.
     * This is only valid if stop_sending is 1.
     */
    uint64_t        stop_sending_aec;

    /*
     * Application Error Code (AEC) used for RESET_STREAM frame.
     * This is only valid if reset_stream is 1.
     */
    uint64_t        reset_stream_aec;

    /*
     * Application Error Code (AEC) for incoming STOP_SENDING frame.
     * This is only valid if peer_stop_sending is 1.
     */
    uint64_t        peer_stop_sending_aec;

    /*
     * Application Error Code (AEC) for incoming RESET_STREAM frame.
     * This is only valid if peer_reset_stream is 1.
     */
    uint64_t        peer_reset_stream_aec;

    /* Temporary value used by TXP. */
    uint64_t        txp_txfc_new_credit_consumed;

    /*
     * The final size of the send stream. Although this information can be
     * discerned from a QUIC_SSTREAM, it is stored separately as we need to keep
     * track of this even if we have thrown away the QUIC_SSTREAM. Use
     * ossl_quic_stream_send_get_final_size to determine if this contain a
     * valid value or if there is no final size yet for a sending part.
     *
     * For the receive part, the final size is tracked by the stream-level RXFC;
     * use ossl_quic_stream_recv_get_final_size or
     * ossl_quic_rxfc_get_final_size.
     */
    uint64_t        send_final_size;

    /*
     * Send stream part and receive stream part buffer management objects.
     *
     * DO NOT test these pointers (sstream, rstream) for NULL. Determine the
     * state of the send or receive stream part first using the appropriate
     * function; then the invariant of that state guarantees that sstream or
     * rstream either is or is not NULL respectively, therefore there is no
     * valid use case for testing these pointers for NULL. In particular, a
     * stream with a send part can still have sstream as NULL, and a stream with
     * a receive part can still have rstream as NULL. QUIC_SSTREAM and
     * QUIC_RSTREAM are stream buffer resource management objects which exist
     * only when they need to for buffer management purposes. The existence or
     * non-existence of a QUIC_SSTREAM or QUIC_RSTREAM object does not
     * correspond with whether a stream's respective send or receive part
     * logically exists or not.
     */
    QUIC_SSTREAM    *sstream;   /* NULL if RX-only */
    QUIC_RSTREAM    *rstream;   /* NULL if TX only */

    /* Stream-level flow control managers. */
    QUIC_TXFC       txfc;       /* NULL if RX-only */
    QUIC_RXFC       rxfc;       /* NULL if TX-only */

    unsigned int    type : 8; /* QUIC_STREAM_INITIATOR_*, QUIC_STREAM_DIR_* */

    unsigned int    send_state : 8; /* QUIC_SSTREAM_STATE_* */
    unsigned int    recv_state : 8; /* QUIC_RSTREAM_STATE_* */

    /* 1 iff this QUIC_STREAM is on the active queue (invariant). */
    unsigned int    active : 1;

    /*
     * This is a copy of the QUIC connection as_server value, indicating
     * whether we are locally operating as a server or not. Having this
     * significantly simplifies stream type determination relative to our
     * perspective. It never changes after a QUIC_STREAM is created and is the
     * same for all QUIC_STREAMS under a QUIC_STREAM_MAP.
     */
    unsigned int    as_server : 1;

    /*
     * Has STOP_SENDING been requested (by us)? Note that this is not the same
     * as want_stop_sending below, as a STOP_SENDING frame may already have been
     * sent and fully acknowledged.
     */
    unsigned int    stop_sending            : 1;

    /*
     * Has RESET_STREAM been requested (by us)? Works identically to
     * STOP_SENDING for transmission purposes.
     */
    /* Has our peer sent a STOP_SENDING frame? */
    unsigned int    peer_stop_sending       : 1;

    /* Temporary flags used by TXP. */
    unsigned int    txp_sent_fc             : 1;
    unsigned int    txp_sent_stop_sending   : 1;
    unsigned int    txp_sent_reset_stream   : 1;
    unsigned int    txp_drained             : 1;
    unsigned int    txp_blocked             : 1;

    /* Frame regeneration flags. */
    unsigned int    want_max_stream_data    : 1; /* used for regen only */
    unsigned int    want_stop_sending       : 1; /* used for gen or regen */
    unsigned int    want_reset_stream       : 1; /* used for gen or regen */

    /* Flags set when frames *we* sent were acknowledged. */
    unsigned int    acked_stop_sending      : 1;

    /*
     * The stream's XSO has been deleted. Pending GC.
     *
     * Here is how stream deletion works:
     *
     *   - A QUIC_STREAM cannot be deleted until it is neither in the accept
     *     queue nor has an associated XSO. This condition occurs when and only
     *     when deleted is true.
     *
     *   - Once this is the case (i.e., no user-facing API object exposing the
     *     stream), we can delete the stream once we determine that all of our
     *     protocol obligations requiring us to keep the QUIC_STREAM around have
     *     been met.
     *
     *     The following frames relate to the streams layer for a specific
     *     stream:
     *
     *          STREAM
     *
     *              RX Obligations:
     *                  Ignore for a deleted stream.
     *
     *                  (This is different from our obligation for a
     *                  locally-initiated stream ID we have not created yet,
     *                  which we must treat as a protocol error. This can be
     *                  distinguished via a simple monotonic counter.)
     *
     *              TX Obligations:
     *                  None, once we've decided to (someday) delete the stream.
     *
     *          STOP_SENDING
     *
     *              We cannot delete the stream until we have finished informing
     *              the peer that we are not going to be listening to it
     *              anymore.
     *
     *              RX Obligations:
     *                  When we delete a stream we must have already had a FIN
     *                  or RESET_STREAM we transmitted acknowledged by the peer.
     *                  Thus we can ignore STOP_SENDING frames for deleted
     *                  streams (if they occur, they are probably just
     *                  retransmissions).
     *
     *              TX Obligations:
     *                  _Acknowledged_ receipt of a STOP_SENDING frame by the
     *                  peer (unless the peer's send part has already FIN'd).
     *
     *          RESET_STREAM
     *
     *              We cannot delete the stream until we have finished informing
     *              the peer that we are not going to be transmitting on it
     *              anymore.
     *
     *              RX Obligations:
     *