quic_fc.h 9.3 KB

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