Serial-Studio/lib/OpenSSL/include/internal/quic_stream_map.h

/*
 * Copyright 2022 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/quic_types.h"
#include "internal/quic_stream.h"
#include "internal/quic_fc.h"
#include <openssl/lhash.h>

/*
 * 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;
};

struct quic_stream_st
{
  QUIC_STREAM_LIST_NODE active_node; /* for use by QUIC_STREAM_MAP */

  /* 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;

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

  QUIC_SSTREAM *sstream; /* NULL if RX-only */
  void *rstream;         /* NULL if TX only (placeholder) */
  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 active : 1;

  /*
   * Has STOP_SENDING been requested? 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? Works identically to STOP_SENDING for
   * transmission purposes.
   */
  unsigned int reset_stream : 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 */
};

/*
 * Marks a stream for STOP_SENDING. aec is the application error code (AEC).
 * This can only fail if it has already been called.
 */
int ossl_quic_stream_stop_sending(QUIC_STREAM *s, uint64_t aec);

/*
 * Marks a stream for reset. aec is the application error code (AEC).
 * This can only fail if it has already been called.
 */
int ossl_quic_stream_reset(QUIC_STREAM *s, uint64_t aec);

/*
 * QUIC Stream Map
 * ===============
 *
 * The QUIC stream map:
 *
 *   - maps stream IDs to QUIC_STREAM objects;
 *   - tracks which streams are 'active' (currently have data for transmission);
 *   - allows iteration over the active streams only.
 *
 */
typedef struct quic_stream_map_st
{
  LHASH_OF(QUIC_STREAM) * map;
  QUIC_STREAM_LIST_NODE active_list;
  size_t rr_stepping, rr_counter;
  QUIC_STREAM *rr_cur;
} QUIC_STREAM_MAP;

int ossl_quic_stream_map_init(QUIC_STREAM_MAP *qsm);

/*
 * Any streams still in the map will be released as though
 * ossl_quic_stream_map_release was called on them.
 */
void ossl_quic_stream_map_cleanup(QUIC_STREAM_MAP *qsm);

#define QUIC_STREAM_INITIATOR_CLIENT 0
#define QUIC_STREAM_INITIATOR_SERVER 1
#define QUIC_STREAM_INITIATOR_MASK 1

#define QUIC_STREAM_DIR_BIDI 0
#define QUIC_STREAM_DIR_UNI 2
#define QUIC_STREAM_DIR_MASK 2

/*
 * Allocate a new stream. type is a combination of one QUIC_STREAM_INITIATOR_*
 * value and one QUIC_STREAM_DIR_* value. Note that clients can e.g. allocate
 * server-initiated streams as they will need to allocate a QUIC_STREAM
 * structure to track any stream created by the server, etc.
 *
 * stream_id must be a valid value. Returns NULL if a stream already exists
 * with the given ID.
 */
QUIC_STREAM *ossl_quic_stream_map_alloc(QUIC_STREAM_MAP *qsm,
                                        uint64_t stream_id, int type);

/*
 * Releases a stream object. Note that this must only be done once the teardown
 * process is entirely complete and the object will never be referenced again.
 */
void ossl_quic_stream_map_release(QUIC_STREAM_MAP *qsm, QUIC_STREAM *stream);

/*
 * Calls visit_cb() for each stream in the map. visit_cb_arg is an opaque
 * argument which is passed through.
 */
void ossl_quic_stream_map_visit(QUIC_STREAM_MAP *qsm,
                                void (*visit_cb)(QUIC_STREAM *stream,
                                                 void *arg),
                                void *visit_cb_arg);

/*
 * Retrieves a stream by stream ID. Returns NULL if it does not exist.
 */
QUIC_STREAM *ossl_quic_stream_map_get_by_id(QUIC_STREAM_MAP *qsm,
                                            uint64_t stream_id);

/*
 * Marks the given stream as active or inactive based on its state. Idempotent.
 *
 * When a stream is marked active, it becomes available in the iteration list,
 * and when a stream is marked inactive, it no longer appears in the iteration
 * list.
 *
 * Calling this function invalidates any iterator currently pointing at the
 * given stream object, but iterators not currently pointing at the given stream
 * object are not invalidated.
 */
void ossl_quic_stream_map_update_state(QUIC_STREAM_MAP *qsm, QUIC_STREAM *s);

/*
 * Sets the RR stepping value, n. The RR rotation will be advanced every n
 * packets. The default value is 1.
 */
void ossl_quic_stream_map_set_rr_stepping(QUIC_STREAM_MAP *qsm,
                                          size_t stepping);

/*
 * QUIC Stream Iterator
 * ====================
 *
 * Allows the current set of active streams to be walked using a RR-based
 * algorithm. Each time ossl_quic_stream_iter_init is called, the RR algorithm
 * is stepped. The RR algorithm rotates the iteration order such that the next
 * active stream is returned first after n calls to ossl_quic_stream_iter_init,
 * where n is the stepping value configured via
 * ossl_quic_stream_map_set_rr_stepping.
 *
 * Suppose there are three active streams and the configured stepping is n:
 *
 *   Iteration 0n:  [Stream 1] [Stream 2] [Stream 3]
 *   Iteration 1n:  [Stream 2] [Stream 3] [Stream 1]
 *   Iteration 2n:  [Stream 3] [Stream 1] [Stream 2]
 *
 */
typedef struct quic_stream_iter_st
{
  QUIC_STREAM_MAP *qsm;
  QUIC_STREAM *first_stream, *stream;
} QUIC_STREAM_ITER;

/*
 * Initialise an iterator, advancing the RR algorithm as necessary (if
 * advance_rr is 1). After calling this, it->stream will be the first stream in
 * the iteration sequence, or NULL if there are no active streams.
 */
void ossl_quic_stream_iter_init(QUIC_STREAM_ITER *it, QUIC_STREAM_MAP *qsm,
                                int advance_rr);

/*
 * Advances to next stream in iteration sequence. You do not need to call this
 * immediately after calling ossl_quic_stream_iter_init(). If the end of the
 * list is reached, it->stream will be NULL after calling this.
 */
void ossl_quic_stream_iter_next(QUIC_STREAM_ITER *it);

#endif