include/internal/quic_fc.h

   1 /*
   2  * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #ifndef OSSL_QUIC_FC_H
  11 # define OSSL_QUIC_FC_H
  12
  13 # include <openssl/ssl.h>
  14 # include "internal/time.h"
  15
  16 /*
  17  * TX Flow Controller (TXFC)
  18  * =========================
  19  *
  20  * For discussion, see doc/designs/quic-design/quic-fc.md.
  21  */
  22 typedef struct quic_txfc_st QUIC_TXFC;
  23
  24 struct quic_txfc_st {
  25     QUIC_TXFC   *parent; /* stream-level iff non-NULL */
  26     uint64_t    swm, cwm;
  27     char        has_become_blocked;
  28 };
  29
  30 /*
  31  * Initialises a TX flow controller. conn_txfc should be non-NULL and point to
  32  * the connection-level flow controller if the TXFC is for stream-level flow
  33  * control, and NULL otherwise.
  34  */
  35 int ossl_quic_txfc_init(QUIC_TXFC *txfc, QUIC_TXFC *conn_txfc);
  36
  37 /*
  38  * Gets the parent (i.e., connection-level) TX flow controller. Returns NULL if
  39  * called on a connection-level TX flow controller.
  40  */
  41 QUIC_TXFC *ossl_quic_txfc_get_parent(QUIC_TXFC *txfc);
  42
  43 /*
  44  * Bump the credit watermark (CWM) value. This is the 'On TX Window Updated'
  45  * operation. This function is a no-op if it has already been called with an
  46  * equal or higher CWM value.
  47  *
  48  * It returns 1 iff the call resulted in the CWM being bumped and 0 if it was
  49  * not increased because it has already been called with an equal or higher CWM
  50  * value. This is not an error per se but may indicate a local programming error
  51  * or a protocol error in a remote peer.
  52  */
  53 int ossl_quic_txfc_bump_cwm(QUIC_TXFC *txfc, uint64_t cwm);
  54
  55 /*
  56  * Get the number of bytes by which we are in credit. This is the number of
  57  * controlled bytes we are allowed to send. (Thus if this function returns 0, we
  58  * are currently blocked.)
  59  *
  60  * If called on a stream-level TXFC, ossl_quic_txfc_get_credit is called on
  61  * the connection-level TXFC as well, and the lesser of the two values is
  62  * returned.
  63  */
  64 uint64_t ossl_quic_txfc_get_credit(QUIC_TXFC *txfc);
  65
  66 /*
  67  * Like ossl_quic_txfc_get_credit(), but when called on a stream-level TXFC,
  68  * retrieves only the stream-level credit value and does not clamp it based on
  69  * connection-level flow control.
  70  */
  71 uint64_t ossl_quic_txfc_get_credit_local(QUIC_TXFC *txfc);
  72
  73 /*
  74  * Consume num_bytes of credit. This is the 'On TX' operation. This should be
  75  * called when we transmit any controlled bytes. Calling this with an argument
  76  * of 0 is a no-op.
  77  *
  78  * We must never transmit more controlled bytes than we are in credit for (see
  79  * the return value of ossl_quic_txfc_get_credit()). If you call this function
  80  * with num_bytes greater than our current credit, this function consumes the
  81  * remainder of the credit and returns 0. This indicates a serious programming
  82  * error on the caller's part. Otherwise, the function returns 1.
  83  *
  84  * If called on a stream-level TXFC, ossl_quic_txfc_consume_credit() is called
  85  * on the connection-level TXFC also. If the call to that function on the
  86  * connection-level TXFC returns zero, this function will also return zero.
  87  */
  88 int ossl_quic_txfc_consume_credit(QUIC_TXFC *txfc, uint64_t num_bytes);
  89
  90 /*
  91  * Like ossl_quic_txfc_consume_credit(), but when called on a stream-level TXFC,
  92  * consumes only from the stream-level credit and does not inform the
  93  * connection-level TXFC.
  94  */
  95 int ossl_quic_txfc_consume_credit_local(QUIC_TXFC *txfc, uint64_t num_bytes);
  96
  97 /*
  98  * This flag is provided for convenience. A caller is not required to use it. It
  99  * is a boolean flag set whenever our credit drops to zero. If clear is 1, the
 100  * flag is cleared. The old value of the flag is returned. Callers may use this
 101  * to determine if they need to send a DATA_BLOCKED or STREAM_DATA_BLOCKED
 102  * frame, which should contain the value returned by ossl_quic_txfc_get_cwm().
 103  */
 104 int ossl_quic_txfc_has_become_blocked(QUIC_TXFC *txfc, int clear);
 105
 106 /*
 107  * Get the current CWM value. This is mainly only needed when generating a
 108  * DATA_BLOCKED or STREAM_DATA_BLOCKED frame, or for diagnostic purposes.
 109  */
 110 uint64_t ossl_quic_txfc_get_cwm(QUIC_TXFC *txfc);
 111
 112 /*
 113  * Get the current spent watermark (SWM) value. This is purely for diagnostic
 114  * use and should not be needed in normal circumstances.
 115  */
 116 uint64_t ossl_quic_txfc_get_swm(QUIC_TXFC *txfc);
 117
 118 /*
 119  * RX Flow Controller (RXFC)
 120  * =========================
 121  */
 122 typedef struct quic_rxfc_st QUIC_RXFC;
 123
 124 struct quic_rxfc_st {
 125     /*
 126      * swm is the sent/received watermark, which tracks how much we have
 127      * received from the peer. rwm is the retired watermark, which tracks how
 128      * much has been passed to the application. esrwm is the rwm value at which
 129      * the current auto-tuning epoch started. hwm is the highest stream length
 130      * (STREAM frame offset + payload length) we have seen from a STREAM frame
 131      * yet.
 132      */
 133     uint64_t        cwm, swm, rwm, esrwm, hwm, cur_window_size, max_window_size;
 134     OSSL_TIME       epoch_start;
 135     OSSL_TIME       (*now)(void *arg);
 136     void            *now_arg;
 137     QUIC_RXFC       *parent;
 138     unsigned char   error_code, has_cwm_changed, is_fin;
 139 };
 140
 141 /*
 142  * Initialises an RX flow controller. conn_rxfc should be non-NULL and point to
 143  * a connection-level RXFC if the RXFC is for stream-level flow control, and
 144  * NULL otherwise. initial_window_size and max_window_size specify the initial
 145  * and absolute maximum window sizes, respectively. Window size values are
 146  * expressed in bytes and determine how much credit the RXFC extends to the peer
 147  * to transmit more data at a time.
 148  */
 149 int ossl_quic_rxfc_init(QUIC_RXFC *rxfc, QUIC_RXFC *conn_rxfc,
 150                         uint64_t initial_window_size,
 151                         uint64_t max_window_size,
 152                         OSSL_TIME (*now)(void *arg),
 153                         void *now_arg);
 154
 155 /*
 156  * Gets the parent (i.e., connection-level) RXFC. Returns NULL if called on a
 157  * connection-level RXFC.
 158  */
 159 QUIC_RXFC *ossl_quic_rxfc_get_parent(QUIC_RXFC *rxfc);
 160
 161 /*
 162  * Changes the current maximum window size value.
 163  */
 164 void ossl_quic_rxfc_set_max_window_size(QUIC_RXFC *rxfc,
 165                                         size_t max_window_size);
 166
 167 /*
 168  * To be called whenever a STREAM frame is received.
 169  *
 170  * end is the value (offset + len), where offset is the offset field of the
 171  * STREAM frame and len is the length of the STREAM frame's payload in bytes.
 172  *
 173  * is_fin should be 1 if the STREAM frame had the FIN flag set and 0 otherwise.
 174  *
 175  * conn_rxfc should point to a connection-level RXFC, which will have its state
 176  * updated correctly by the stream-level RXFC.
 177  *
 178  * This function may be used on a stream-level RXFC only.
 179  *
 180  * You should check ossl_quic_rxfc_has_error() on both connection-level and
 181  * stream-level RXFCs after calling this function, as an incoming STREAM frame
 182  * may cause flow control limits to be exceeded by an errant peer. This
 183  * function still returns 1 in this case, as this is not a caller error.
 184  *
 185  * Returns 1 on success or 0 on failure.
 186  */
 187 int ossl_quic_rxfc_on_rx_stream_frame(QUIC_RXFC *rxfc,
 188                                       uint64_t end, int is_fin);
 189
 190 /*
 191  * To be called whenever controlled bytes are retired, i.e. when bytes are
 192  * dequeued from a QUIC stream and passed to the application. num_bytes
 193  * is the number of bytes which were passed to the application.
 194  *
 195  * You should call this only on a stream-level RXFC. This function will update
 196  * the connection-level RXFC automatically.
 197  *
 198  * rtt should be the current best understanding of the RTT to the peer, as
 199  * offered by the Statistics Manager.
 200  *
 201  * You should check ossl_quic_rxfc_has_cwm_changed() after calling this
 202  * function, as it may have caused the RXFC to decide to grant more flow control
 203  * credit to the peer.
 204  *
 205  * Returns 1 on success and 0 on failure.
 206  */
 207 int ossl_quic_rxfc_on_retire(QUIC_RXFC *rxfc,
 208                              uint64_t num_bytes,
 209                              OSSL_TIME rtt);
 210
 211 /*
 212  * Returns the current CWM which the RXFC thinks the peer should have.
 213  *
 214  * Note that the RXFC will increase this value in response to events, at which
 215  * time a MAX_DATA or MAX_STREAM_DATA frame must be generated. Use
 216  * ossl_quic_rxfc_has_cwm_changed() to detect this condition.
 217  *
 218  * This value increases monotonically.
 219  */
 220 uint64_t ossl_quic_rxfc_get_cwm(QUIC_RXFC *rxfc);
 221
 222 /*
 223  * Returns the current SWM. This is the total number of bytes the peer has
 224  * transmitted to us. This is intended for diagnostic use only; you should
 225  * not need it.
 226  */
 227 uint64_t ossl_quic_rxfc_get_swm(QUIC_RXFC *rxfc);
 228
 229 /*
 230  * Returns the current RWM. This is the total number of bytes that has been
 231  * retired. This is intended for diagnostic use only; you should not need it.
 232  */
 233 uint64_t ossl_quic_rxfc_get_rwm(QUIC_RXFC *rxfc);
 234
 235 /*
 236  * Returns the CWM changed flag. If clear is 1, the flag is cleared and the old
 237  * value is returned.
 238  */
 239 int ossl_quic_rxfc_has_cwm_changed(QUIC_RXFC *rxfc, int clear);
 240
 241 /*
 242  * Returns a QUIC_ERR_* error code if a flow control error has been detected.
 243  * Otherwise, returns QUIC_ERR_NO_ERROR. If clear is 1, the error is cleared
 244  * and the old value is returned.
 245  *
 246  * May return one of the following values:
 247  *
 248  * QUIC_ERR_FLOW_CONTROL_ERROR:
 249  *   This indicates a flow control protocol violation by the remote peer; the
 250  *   connection should be terminated in this event.
 251  * QUIC_ERR_FINAL_SIZE:
 252  *   The peer attempted to change the stream length after ending the stream.
 253  */
 254 int ossl_quic_rxfc_get_error(QUIC_RXFC *rxfc, int clear);
 255
 256 #endif