include/internal/quic_stream.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_INTERNAL_QUIC_STREAM_H
  11 # define OSSL_INTERNAL_QUIC_STREAM_H
  12 # pragma once
  13
  14 #include "internal/e_os.h"
  15 #include "internal/time.h"
  16 #include "internal/quic_types.h"
  17 #include "internal/quic_wire.h"
  18 #include "internal/quic_record_tx.h"
  19 #include "internal/quic_record_rx.h"
  20 #include "internal/quic_fc.h"
  21 #include "internal/quic_statm.h"
  22
  23 # ifndef OPENSSL_NO_QUIC
  24
  25 /*
  26  * QUIC Send Stream
  27  * ================
  28  *
  29  * The QUIC Send Stream Manager (QUIC_SSTREAM) is responsible for:
  30  *
  31  *   - accepting octet strings of stream data;
  32  *
  33  *   - generating corresponding STREAM frames;
  34  *
  35  *   - receiving notifications of lost frames, in order to generate new STREAM
  36  *     frames for the lost data;
  37  *
  38  *   - receiving notifications of acknowledged frames, in order to internally
  39  *     reuse memory used to store acknowledged stream data;
  40  *
  41  *   - informing the caller of how much more stream data it can accept into
  42  *     its internal buffers, so as to ensure that the amount of unacknowledged
  43  *     data which can be written to a stream is not infinite and to allow the
  44  *     caller to manifest backpressure conditions to the user.
  45  *
  46  * The QUIC_SSTREAM is instantiated once for every stream with a send component
  47  * (i.e., for a unidirectional send stream or for the send component of a
  48  * bidirectional stream).
  49  *
  50  * Note: The terms 'TX' and 'RX' are used when referring to frames, packets and
  51  * datagrams. The terms 'send' and 'receive' are used when referring to the
  52  * stream abstraction. Applications send; we transmit.
  53  */
  54 typedef struct quic_sstream_st QUIC_SSTREAM;
  55
  56 /*
  57  * Instantiates a new QUIC_SSTREAM. init_buf_size specifies the initial size of
  58  * the stream data buffer in bytes, which must be positive.
  59  */
  60 QUIC_SSTREAM *ossl_quic_sstream_new(size_t init_buf_size);
  61
  62 /*
  63  * Frees a QUIC_SSTREAM and associated stream data storage.
  64  *
  65  * Any iovecs returned by ossl_quic_sstream_get_stream_frame cease to be valid after
  66  * calling this function.
  67  */
  68 void ossl_quic_sstream_free(QUIC_SSTREAM *qss);
  69
  70 /*
  71  * (For TX packetizer use.) Retrieves information about application stream data
  72  * which is ready for transmission.
  73  *
  74  * *hdr is filled with the logical offset, maximum possible length of stream
  75  * data which can be transmitted, and a pointer to the stream data to be
  76  * transmitted. is_fin is set to 1 if hdr->offset + hdr->len is the final size
  77  * of the stream and 0 otherwise. hdr->stream_id is not set; the caller must set
  78  * it.
  79  *
  80  * The caller is not obligated to send all of the data. If the caller does not
  81  * send all of the data, the caller must reduce hdr->len before serializing the
  82  * header structure and must ensure that hdr->is_fin is cleared.
  83  *
  84  * hdr->has_explicit_len is always set. It is the caller's responsibility to
  85  * clear this if it wants to use the optimization of omitting the length field,
  86  * as only the caller can know when this optimization can be performed.
  87  *
  88  * *num_iov must be set to the size of the iov array at call time. When this
  89  * function returns successfully, it is updated to the number of iov entries
  90  * which have been written.
  91  *
  92  * The stream data may be split across up to two IOVs due to internal ring
  93  * buffer organisation. The sum of the lengths of the IOVs and the value written
  94  * to hdr->len will always match. If the caller decides to send less than
  95  * hdr->len of stream data, it must adjust the IOVs accordingly. This may be
  96  * done by updating hdr->len and then calling the utility function
  97  * ossl_quic_sstream_adjust_iov().
  98  *
  99  * After committing one or more bytes returned by ossl_quic_sstream_get_stream_frame to a
 100  * packet, call ossl_quic_sstream_mark_transmitted with the inclusive range of logical
 101  * byte numbers of the transmitted bytes (i.e., hdr->offset, hdr->offset +
 102  * hdr->len - 1). If you do not call ossl_quic_sstream_mark_transmitted, the next call to
 103  * ossl_quic_sstream_get_stream_frame will return the same data (or potentially the same
 104  * and more, if more data has been appended by the application).
 105  *
 106  * It is the caller's responsibility to clamp the length of data which this
 107  * function indicates is available according to other concerns, such as
 108  * stream-level flow control, connection-level flow control, or the applicable
 109  * maximum datagram payload length (MDPL) for a packet under construction.
 110  *
 111  * The skip argument can usually be given as zero. If it is non-zero, this
 112  * function outputs a range which would be output if it were called again after
 113  * calling ossl_quic_sstream_mark_transmitted() with the returned range, repeated 'skip'
 114  * times, and so on. This may be useful for callers which wish to enumerate
 115  * available stream frames and batch their calls to ossl_quic_sstream_mark_transmitted at
 116  * a later time.
 117  *
 118  * On success, this function will never write *num_iov with a value other than
 119  * 0, 1 or 2. A *num_iov value of 0 can only occurs when hdr->is_fin is set (for
 120  * example, when a stream is closed after all existing data has been sent, and
 121  * without sending any more data); otherwise the function returns 0 as there is
 122  * nothing useful to report.
 123  *
 124  * Returns 1 on success and 0 if there is no stream data available for
 125  * transmission, or on other error (such as if the caller provides fewer
 126  * than two IOVs.)
 127  */
 128 int ossl_quic_sstream_get_stream_frame(QUIC_SSTREAM *qss,
 129                                        size_t skip,
 130                                        OSSL_QUIC_FRAME_STREAM *hdr,
 131                                        OSSL_QTX_IOVEC *iov,
 132                                        size_t *num_iov);
 133
 134 /*
 135  * Returns 1 if there is data pending transmission. Equivalent to calling
 136  * ossl_quic_sstream_get_stream_frame and seeing if it succeeds.
 137  */
 138 int ossl_quic_sstream_has_pending(QUIC_SSTREAM *qss);
 139
 140 /*
 141  * Returns the current size of the stream; i.e., the number of bytes which have
 142  * been appended to the stream so far.
 143  */
 144 uint64_t ossl_quic_sstream_get_cur_size(QUIC_SSTREAM *qss);
 145
 146 /*
 147  * (For TX packetizer use.) Marks a logical range of the send stream as having
 148  * been transmitted.
 149  *
 150  * 0 denotes the first byte ever sent on the stream. The start and end values
 151  * are both inclusive, therefore all calls to this function always mark at least
 152  * one byte as being transmitted; if no bytes have been transmitted, do not call
 153  * this function.
 154  *
 155  * If the STREAM frame sent had the FIN bit set, you must also call
 156  * ossl_quic_sstream_mark_transmitted_fin() after calling this function.
 157  *
 158  * If you sent a zero-length STREAM frame with the FIN bit set, you need only
 159  * call ossl_quic_sstream_mark_transmitted_fin() and must not call this function.
 160  *
 161  * Returns 1 on success and 0 on error (e.g. if end < start).
 162  */
 163 int ossl_quic_sstream_mark_transmitted(QUIC_SSTREAM *qss,
 164                                        uint64_t start,
 165                                        uint64_t end);
 166
 167 /*
 168  * (For TX packetizer use.) Marks a STREAM frame with the FIN bit set as having
 169  * been transmitted. final_size is the final size of the stream (i.e., the value
 170  * offset + len of the transmitted STREAM frame).
 171  *
 172  * This function fails returning 0 if ossl_quic_sstream_fin() has not been called or if
 173  * final_size is not correct. The final_size argument is not strictly needed by
 174  * the QUIC_SSTREAM but is required as a sanity check.
 175  */
 176 int ossl_quic_sstream_mark_transmitted_fin(QUIC_SSTREAM *qss,
 177                                            uint64_t final_size);
 178
 179 /*
 180  * (RX/ACKM use.) Marks a logical range of the send stream as having been lost.
 181  * The send stream will return the lost data for retransmission on a future call
 182  * to ossl_quic_sstream_get_stream_frame. The start and end values denote logical byte
 183  * numbers and are inclusive.
 184  *
 185  * If the lost frame had the FIN bit set, you must also call
 186  * ossl_quic_sstream_mark_lost_fin() after calling this function.
 187  *
 188  * Returns 1 on success and 0 on error (e.g. if end < start).
 189  */
 190 int ossl_quic_sstream_mark_lost(QUIC_SSTREAM *qss,
 191                                 uint64_t start,
 192                                 uint64_t end);
 193
 194 /*
 195  * (RX/ACKM use.) Informs the QUIC_SSTREAM that a STREAM frame with the FIN bit
 196  * set was lost.
 197  *
 198  * Returns 1 on success and 0 on error.
 199  */
 200 int ossl_quic_sstream_mark_lost_fin(QUIC_SSTREAM *qss);
 201
 202 /*
 203  * (RX/ACKM use.) Marks a logical range of the send stream as having been
 204  * acknowledged, meaning that the storage for the data in that range of the
 205  * stream can be now recycled and neither that logical range of the stream nor
 206  * any subset of it can be retransmitted again. The start and end values are
 207  * inclusive.
 208  *
 209  * If the acknowledged frame had the FIN bit set, you must also call
 210  * ossl_quic_sstream_mark_acked_fin() after calling this function.
 211  *
 212  * Returns 1 on success and 0 on error (e.g. if end < start).
 213  */
 214 int ossl_quic_sstream_mark_acked(QUIC_SSTREAM *qss,
 215                                  uint64_t start,
 216                                  uint64_t end);
 217
 218 /*
 219  * (RX/ACKM use.) Informs the QUIC_SSTREAM that a STREAM frame with the FIN bit
 220  * set was acknowledged.
 221  *
 222  * Returns 1 on success and 0 on error.
 223  */
 224 int ossl_quic_sstream_mark_acked_fin(QUIC_SSTREAM *qss);
 225
 226 /*
 227  * (Front end use.) Appends user data to the stream. The data is copied into the
 228  * stream. The amount of data consumed from buf is written to *consumed on
 229  * success (short writes are possible). The amount of data which can be written
 230  * can be determined in advance by calling the ossl_quic_sstream_get_buffer_avail()
 231  * function; data is copied into an internal ring buffer of finite size.
 232  *
 233  * If the buffer is full, this should be materialised as a backpressure
 234  * condition by the front end. This is not considered a failure condition;
 235  * *consumed is written as 0 and the function returns 1.
 236  *
 237  * Returns 1 on success or 0 on failure.
 238  */
 239 int ossl_quic_sstream_append(QUIC_SSTREAM *qss,
 240                              const unsigned char *buf,
 241                              size_t buf_len,
 242                              size_t *consumed);
 243
 244 /*
 245  * Marks a stream as finished. ossl_quic_sstream_append() may not be called anymore
 246  * after calling this.
 247  */
 248 void ossl_quic_sstream_fin(QUIC_SSTREAM *qss);
 249
 250 /*
 251  * If the stream has had ossl_quic_sstream_fin() called, returns 1 and writes
 252  * the final size to *final_size. Otherwise, returns 0.
 253  */
 254 int ossl_quic_sstream_get_final_size(QUIC_SSTREAM *qss, uint64_t *final_size);
 255
 256 /*
 257  * Resizes the internal ring buffer. All stream data is preserved safely.
 258  *
 259  * This can be used to expand or contract the ring buffer, but not to contract
 260  * the ring buffer below the amount of stream data currently stored in it.
 261  * Returns 1 on success and 0 on failure.
 262  *
 263  * IMPORTANT: Any buffers referenced by iovecs output by
 264  * ossl_quic_sstream_get_stream_frame() cease to be valid after calling this function.
 265  */
 266 int ossl_quic_sstream_set_buffer_size(QUIC_SSTREAM *qss, size_t num_bytes);
 267
 268 /*
 269  * Gets the internal ring buffer size in bytes.
 270  */
 271 size_t ossl_quic_sstream_get_buffer_size(QUIC_SSTREAM *qss);
 272
 273 /*
 274  * Gets the number of bytes used in the internal ring buffer.
 275  */
 276 size_t ossl_quic_sstream_get_buffer_used(QUIC_SSTREAM *qss);
 277
 278 /*
 279  * Gets the number of bytes free in the internal ring buffer.
 280  */
 281 size_t ossl_quic_sstream_get_buffer_avail(QUIC_SSTREAM *qss);
 282
 283 /*
 284  * Utility function to ensure the length of an array of iovecs matches the
 285  * length given as len. Trailing iovecs have their length values reduced or set
 286  * to 0 as necessary.
 287  */
 288 void ossl_quic_sstream_adjust_iov(size_t len,
 289                                   OSSL_QTX_IOVEC *iov,
 290                                   size_t num_iov);
 291
 292 /*
 293  * QUIC Receive Stream Manager
 294  * ===========================
 295  *
 296  * The QUIC Receive Stream Manager (QUIC_RSTREAM) is responsible for
 297  * storing the received stream data frames until the application
 298  * is able to read the data.
 299  *
 300  * The QUIC_RSTREAM is instantiated once for every stream that can receive data.
 301  * (i.e., for a unidirectional receiving stream or for the receiving component
 302  * of a bidirectional stream).
 303  */
 304 typedef struct quic_rstream_st QUIC_RSTREAM;
 305
 306 /*
 307  * Create a new instance of QUIC_RSTREAM with pointers to the flow
 308  * controller and statistics module. They can be NULL for unit testing.
 309  * If they are non-NULL, the `rxfc` is called when receive stream data
 310  * is read by application. `statm` is queried for current rtt.
 311  */
 312 QUIC_RSTREAM *ossl_quic_rstream_new(QUIC_RXFC *rxfc,
 313                                     OSSL_STATM *statm);
 314
 315 /*
 316  * Frees a QUIC_RSTREAM and any associated storage.
 317  */
 318 void ossl_quic_rstream_free(QUIC_RSTREAM *qrs);
 319
 320 /*
 321  * Adds received stream frame data to `qrs`. The `pkt_wrap` refcount is
 322  * incremented if the `data` is queued directly without copying.
 323  * It can be NULL for unit-testing purposes, i.e. if `data` is static or
 324  * never released before calling ossl_quic_rstream_free().
 325  * The `offset` is the absolute offset of the data in the stream.
 326  * `data_len` can be 0 - can be useful for indicating `fin` for empty stream.
 327  * Or to indicate `fin` without any further data added to the stream.
 328  */
 329
 330 int ossl_quic_rstream_queue_data(QUIC_RSTREAM *qrs, OSSL_QRX_PKT *pkt,
 331                                  uint64_t offset,
 332                                  const unsigned char *data, uint64_t data_len,
 333                                  int fin);
 334
 335 /*
 336  * Copies the data from the stream storage to buffer `buf` of size `size`.
 337  * `readbytes` is set to the number of bytes actually copied.
 338  * `fin` is set to 1 if all the data from the stream were read so the
 339  * stream is finished. It is set to 0 otherwise.
 340  */
 341 int ossl_quic_rstream_read(QUIC_RSTREAM *qrs, unsigned char *buf, size_t size,
 342                            size_t *readbytes, int *fin);
 343
 344 /*
 345  * Peeks at the data in the stream storage. It copies them to buffer `buf`
 346  * of size `size` and sets `readbytes` to the number of bytes actually copied.
 347  * `fin` is set to 1 if the copied data reach end of the stream.
 348  * It is set to 0 otherwise.
 349  */
 350 int ossl_quic_rstream_peek(QUIC_RSTREAM *qrs, unsigned char *buf, size_t size,
 351                            size_t *readbytes, int *fin);
 352
 353 /*
 354  * Returns the size of the data available for reading. `fin` is set to 1 if
 355  * after reading all the available data the stream will be finished,
 356  * set to 0 otherwise.
 357  */
 358 int ossl_quic_rstream_available(QUIC_RSTREAM *qrs, size_t *avail, int *fin);
 359
 360 # endif
 361
 362 #endif