xref: /freebsd/crypto/openssl/include/internal/quic_stream_map.h (revision e7be843b4a162e68651d3911f0357ed464915629)
1 /*
2 * Copyright 2022-2025 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_MAP_H
11 # define OSSL_INTERNAL_QUIC_STREAM_MAP_H
12 # pragma once
13 
14 # include "internal/e_os.h"
15 # include "internal/time.h"
16 # include "internal/common.h"
17 # include "internal/quic_types.h"
18 # include "internal/quic_predef.h"
19 # include "internal/quic_stream.h"
20 # include "internal/quic_fc.h"
21 # include <openssl/lhash.h>
22 
23 # ifndef OPENSSL_NO_QUIC
24 
25 /*
26  * QUIC Stream
27  * ===========
28  *
29  * Logical QUIC stream composing all relevant send and receive components.
30  */
31 
32 typedef struct quic_stream_list_node_st QUIC_STREAM_LIST_NODE;
33 
34 struct quic_stream_list_node_st {
35     QUIC_STREAM_LIST_NODE *prev, *next;
36 };
37 
38 /*
39  * QUIC Send Stream States
40  * -----------------------
41  *
42  * These correspond to the states defined in RFC 9000 s. 3.1, with the
43  * exception of the NONE state which represents the absence of a send stream
44  * part.
45  *
46  * Invariants in each state are noted in comments below. In particular, once all
47  * data has been acknowledged received, or we have reset the stream, we don't
48  * need to keep the QUIC_SSTREAM and data buffers around. Of course, we also
49  * don't have a QUIC_SSTREAM on a receive-only stream.
50  */
51 #define QUIC_SSTREAM_STATE_NONE         0   /* --- sstream == NULL  */
52 #define QUIC_SSTREAM_STATE_READY        1   /* \                    */
53 #define QUIC_SSTREAM_STATE_SEND         2   /* |-- sstream != NULL  */
54 #define QUIC_SSTREAM_STATE_DATA_SENT    3   /* /                    */
55 #define QUIC_SSTREAM_STATE_DATA_RECVD   4   /* \                    */
56 #define QUIC_SSTREAM_STATE_RESET_SENT   5   /* |-- sstream == NULL  */
57 #define QUIC_SSTREAM_STATE_RESET_RECVD  6   /* /                    */
58 
59 /*
60  * QUIC Receive Stream States
61  * --------------------------
62  *
63  * These correspond to the states defined in RFC 9000 s. 3.2, with the exception
64  * of the NONE state which represents the absence of a receive stream part.
65  *
66  * Invariants in each state are noted in comments below. In particular, once all
67  * data has been read by the application, we don't need to keep the QUIC_RSTREAM
68  * and data buffers around. If the receive part is instead reset before it is
69  * finished, we also don't need to keep the QUIC_RSTREAM around. Finally, we
70  * don't need a QUIC_RSTREAM on a send-only stream.
71  */
72 #define QUIC_RSTREAM_STATE_NONE         0   /* --- rstream == NULL  */
73 #define QUIC_RSTREAM_STATE_RECV         1   /* \                    */
74 #define QUIC_RSTREAM_STATE_SIZE_KNOWN   2   /* |-- rstream != NULL  */
75 #define QUIC_RSTREAM_STATE_DATA_RECVD   3   /* /                    */
76 #define QUIC_RSTREAM_STATE_DATA_READ    4   /* \                    */
77 #define QUIC_RSTREAM_STATE_RESET_RECVD  5   /* |-- rstream == NULL  */
78 #define QUIC_RSTREAM_STATE_RESET_READ   6   /* /                    */
79 
80 struct quic_stream_st {
81     QUIC_STREAM_LIST_NODE active_node; /* for use by QUIC_STREAM_MAP */
82     QUIC_STREAM_LIST_NODE accept_node; /* accept queue of remotely-created streams */
83     QUIC_STREAM_LIST_NODE ready_for_gc_node; /* queue of streams now ready for GC */
84 
85     /* Temporary link used by TXP. */
86     QUIC_STREAM    *txp_next;
87 
88     /*
89      * QUIC Stream ID. Do not assume that this encodes a type as this is a
90      * version-specific property and may change between QUIC versions; instead,
91      * use the type field.
92      */
93     uint64_t        id;
94 
95     /*
96      * Application Error Code (AEC) used for STOP_SENDING frame.
97      * This is only valid if stop_sending is 1.
98      */
99     uint64_t        stop_sending_aec;
100 
101     /*
102      * Application Error Code (AEC) used for RESET_STREAM frame.
103      * This is only valid if reset_stream is 1.
104      */
105     uint64_t        reset_stream_aec;
106 
107     /*
108      * Application Error Code (AEC) for incoming STOP_SENDING frame.
109      * This is only valid if peer_stop_sending is 1.
110      */
111     uint64_t        peer_stop_sending_aec;
112 
113     /*
114      * Application Error Code (AEC) for incoming RESET_STREAM frame.
115      * This is only valid if peer_reset_stream is 1.
116      */
117     uint64_t        peer_reset_stream_aec;
118 
119     /* Temporary value used by TXP. */
120     uint64_t        txp_txfc_new_credit_consumed;
121 
122     /*
123      * The final size of the send stream. Although this information can be
124      * discerned from a QUIC_SSTREAM, it is stored separately as we need to keep
125      * track of this even if we have thrown away the QUIC_SSTREAM. Use
126      * ossl_quic_stream_send_get_final_size to determine if this contain a
127      * valid value or if there is no final size yet for a sending part.
128      *
129      * For the receive part, the final size is tracked by the stream-level RXFC;
130      * use ossl_quic_stream_recv_get_final_size or
131      * ossl_quic_rxfc_get_final_size.
132      */
133     uint64_t        send_final_size;
134 
135     /*
136      * Send stream part and receive stream part buffer management objects.
137      *
138      * DO NOT test these pointers (sstream, rstream) for NULL. Determine the
139      * state of the send or receive stream part first using the appropriate
140      * function; then the invariant of that state guarantees that sstream or
141      * rstream either is or is not NULL respectively, therefore there is no
142      * valid use case for testing these pointers for NULL. In particular, a
143      * stream with a send part can still have sstream as NULL, and a stream with
144      * a receive part can still have rstream as NULL. QUIC_SSTREAM and
145      * QUIC_RSTREAM are stream buffer resource management objects which exist
146      * only when they need to for buffer management purposes. The existence or
147      * non-existence of a QUIC_SSTREAM or QUIC_RSTREAM object does not
148      * correspond with whether a stream's respective send or receive part
149      * logically exists or not.
150      */
151     QUIC_SSTREAM    *sstream;   /* NULL if RX-only */
152     QUIC_RSTREAM    *rstream;   /* NULL if TX only */
153 
154     /* Stream-level flow control managers. */
155     QUIC_TXFC       txfc;       /* NULL if RX-only */
156     QUIC_RXFC       rxfc;       /* NULL if TX-only */
157 
158     unsigned int    type : 8; /* QUIC_STREAM_INITIATOR_*, QUIC_STREAM_DIR_* */
159 
160     unsigned int    send_state : 8; /* QUIC_SSTREAM_STATE_* */
161     unsigned int    recv_state : 8; /* QUIC_RSTREAM_STATE_* */
162 
163     /* 1 iff this QUIC_STREAM is on the active queue (invariant). */
164     unsigned int    active : 1;
165 
166     /*
167      * This is a copy of the QUIC connection as_server value, indicating
168      * whether we are locally operating as a server or not. Having this
169      * significantly simplifies stream type determination relative to our
170      * perspective. It never changes after a QUIC_STREAM is created and is the
171      * same for all QUIC_STREAMS under a QUIC_STREAM_MAP.
172      */
173     unsigned int    as_server : 1;
174 
175     /*
176      * Has STOP_SENDING been requested (by us)? Note that this is not the same
177      * as want_stop_sending below, as a STOP_SENDING frame may already have been
178      * sent and fully acknowledged.
179      */
180     unsigned int    stop_sending            : 1;
181 
182     /*
183      * Has RESET_STREAM been requested (by us)? Works identically to
184      * STOP_SENDING for transmission purposes.
185      */
186     /* Has our peer sent a STOP_SENDING frame? */
187     unsigned int    peer_stop_sending       : 1;
188 
189     /* Temporary flags used by TXP. */
190     unsigned int    txp_sent_fc             : 1;
191     unsigned int    txp_sent_stop_sending   : 1;
192     unsigned int    txp_sent_reset_stream   : 1;
193     unsigned int    txp_drained             : 1;
194     unsigned int    txp_blocked             : 1;
195 
196     /* Frame regeneration flags. */
197     unsigned int    want_max_stream_data    : 1; /* used for regen only */
198     unsigned int    want_stop_sending       : 1; /* used for gen or regen */
199     unsigned int    want_reset_stream       : 1; /* used for gen or regen */
200 
201     /* Flags set when frames *we* sent were acknowledged. */
202     unsigned int    acked_stop_sending      : 1;
203 
204     /*
205      * The stream's XSO has been deleted. Pending GC.
206      *
207      * Here is how stream deletion works:
208      *
209      *   - A QUIC_STREAM cannot be deleted until it is neither in the accept
210      *     queue nor has an associated XSO. This condition occurs when and only
211      *     when deleted is true.
212      *
213      *   - Once this is the case (i.e., no user-facing API object exposing the
214      *     stream), we can delete the stream once we determine that all of our
215      *     protocol obligations requiring us to keep the QUIC_STREAM around have
216      *     been met.
217      *
218      *     The following frames relate to the streams layer for a specific
219      *     stream:
220      *
221      *          STREAM
222      *
223      *              RX Obligations:
224      *                  Ignore for a deleted stream.
225      *
226      *                  (This is different from our obligation for a
227      *                  locally-initiated stream ID we have not created yet,
228      *                  which we must treat as a protocol error. This can be
229      *                  distinguished via a simple monotonic counter.)
230      *
231      *              TX Obligations:
232      *                  None, once we've decided to (someday) delete the stream.
233      *
234      *          STOP_SENDING
235      *
236      *              We cannot delete the stream until we have finished informing
237      *              the peer that we are not going to be listening to it
238      *              anymore.
239      *
240      *              RX Obligations:
241      *                  When we delete a stream we must have already had a FIN
242      *                  or RESET_STREAM we transmitted acknowledged by the peer.
243      *                  Thus we can ignore STOP_SENDING frames for deleted
244      *                  streams (if they occur, they are probably just
245      *                  retransmissions).
246      *
247      *              TX Obligations:
248      *                  _Acknowledged_ receipt of a STOP_SENDING frame by the
249      *                  peer (unless the peer's send part has already FIN'd).
250      *
251      *          RESET_STREAM
252      *
253      *              We cannot delete the stream until we have finished informing
254      *              the peer that we are not going to be transmitting on it
255      *              anymore.
256      *
257      *              RX Obligations:
258      *                  This indicates the peer is not going to send any more
259      *                  data on the stream. We don't need to care about this
260      *                  since once a stream is marked for deletion we don't care
261      *                  about any data it does send. We can ignore this for
262      *                  deleted streams. The important criterion is that the
263      *                  peer has been successfully delivered our STOP_SENDING
264      *                  frame.
265      *
266      *              TX Obligations:
267      *                  _Acknowledged_ receipt of a RESET_STREAM frame or FIN by
268      *                  the peer.
269      *
270      *          MAX_STREAM_DATA
271      *
272      *              RX Obligations:
273      *                 Ignore. Since we are not going to be sending any more
274      *                 data on a stream once it has been marked for deletion,
275      *                 we don't need to care about flow control information.
276      *
277      *              TX Obligations:
278      *                  None.
279      *
280      *     In other words, our protocol obligation is simply:
281      *
282      *       - either:
283      *         - the peer has acknowledged receipt of a STOP_SENDING frame sent
284      *            by us; -or-
285      *         - we have received a FIN and all preceding segments from the peer
286      *
287      *            [NOTE: The actual criterion required here is simply 'we have
288      *            received a FIN from the peer'. However, due to reordering and
289      *            retransmissions we might subsequently receive non-FIN segments
290      *            out of order. The FIN means we know the peer will stop
291      *            transmitting on the stream at *some* point, but by sending
292      *            STOP_SENDING we can avoid these needless retransmissions we
293      *            will just ignore anyway. In actuality we could just handle all
294      *            cases by sending a STOP_SENDING. The strategy we choose is to
295      *            only avoid sending a STOP_SENDING and rely on a received FIN
296      *            when we have received all preceding data, as this makes it
297      *            reasonably certain no benefit would be gained by sending
298      *            STOP_SENDING.]
299      *
300      *            TODO(QUIC FUTURE): Implement the latter case (currently we
301                                      just always do STOP_SENDING).
302      *
303      *         and;
304      *
305      *       - we have drained our send stream (for a finished send stream)
306      *         and got acknowledgement all parts of it including the FIN, or
307      *         sent a RESET_STREAM frame and got acknowledgement of that frame.
308      *
309      *      Once these conditions are met, we can GC the QUIC_STREAM.
310      *
311      */
312     unsigned int    deleted                 : 1;
313     /* Set to 1 once the above conditions are actually met. */
314     unsigned int    ready_for_gc            : 1;
315     /* Set to 1 if this is currently counted in the shutdown flush stream count. */
316     unsigned int    shutdown_flush          : 1;
317 };
318 
319 #define QUIC_STREAM_INITIATOR_CLIENT        0
320 #define QUIC_STREAM_INITIATOR_SERVER        1
321 #define QUIC_STREAM_INITIATOR_MASK          1
322 
323 #define QUIC_STREAM_DIR_BIDI                0
324 #define QUIC_STREAM_DIR_UNI                 2
325 #define QUIC_STREAM_DIR_MASK                2
326 
327 void ossl_quic_stream_check(const QUIC_STREAM *s);
328 
329 /*
330  * Returns 1 if the QUIC_STREAM was initiated by the endpoint with the server
331  * role.
332  */
ossl_quic_stream_is_server_init(const QUIC_STREAM * s)333 static ossl_inline ossl_unused int ossl_quic_stream_is_server_init(const QUIC_STREAM *s)
334 {
335     return (s->type & QUIC_STREAM_INITIATOR_MASK) == QUIC_STREAM_INITIATOR_SERVER;
336 }
337 
338 /*
339  * Returns 1 if the QUIC_STREAM is bidirectional and 0 if it is unidirectional.
340  */
ossl_quic_stream_is_bidi(const QUIC_STREAM * s)341 static ossl_inline ossl_unused int ossl_quic_stream_is_bidi(const QUIC_STREAM *s)
342 {
343     return (s->type & QUIC_STREAM_DIR_MASK) == QUIC_STREAM_DIR_BIDI;
344 }
345 
346 /* Returns 1 if the QUIC_STREAM was locally initiated. */
ossl_quic_stream_is_local_init(const QUIC_STREAM * s)347 static ossl_inline ossl_unused int ossl_quic_stream_is_local_init(const QUIC_STREAM *s)
348 {
349     return ossl_quic_stream_is_server_init(s) == s->as_server;
350 }
351 
352 /*
353  * Returns 1 if the QUIC_STREAM has a sending part, based on its stream type.
354  *
355  * Do NOT use (s->sstream != NULL) to test this; use this function. Note that
356  * even if this function returns 1, s->sstream might be NULL if the QUIC_SSTREAM
357  * has been deemed no longer needed, for example due to a RESET_STREAM.
358  */
ossl_quic_stream_has_send(const QUIC_STREAM * s)359 static ossl_inline ossl_unused int ossl_quic_stream_has_send(const QUIC_STREAM *s)
360 {
361     return s->send_state != QUIC_SSTREAM_STATE_NONE;
362 }
363 
364 /*
365  * Returns 1 if the QUIC_STREAM has a receiving part, based on its stream type.
366  *
367  * Do NOT use (s->rstream != NULL) to test this; use this function. Note that
368  * even if this function returns 1, s->rstream might be NULL if the QUIC_RSTREAM
369  * has been deemed no longer needed, for example if the receive stream is
370  * completely finished with.
371  */
ossl_quic_stream_has_recv(const QUIC_STREAM * s)372 static ossl_inline ossl_unused int ossl_quic_stream_has_recv(const QUIC_STREAM *s)
373 {
374     return s->recv_state != QUIC_RSTREAM_STATE_NONE;
375 }
376 
377 /*
378  * Returns 1 if the QUIC_STREAM has a QUIC_SSTREAM send buffer associated with
379  * it. If this returns 1, s->sstream is guaranteed to be non-NULL. The converse
380  * is not necessarily true; erasure of a send stream buffer which is no longer
381  * required is an optimisation which the QSM may, but is not obliged, to
382  * perform.
383  *
384  * This call should be used where it is desired to do something with the send
385  * stream buffer but there is no more specific send state restriction which is
386  * applicable.
387  *
388  * Note: This does NOT indicate whether it is suitable to allow an application
389  * to append to the buffer. DATA_SENT indicates all data (including FIN) has
390  * been *sent*; the absence of DATA_SENT does not mean a FIN has not been queued
391  * (meaning no more application data can be appended). This is enforced by
392  * QUIC_SSTREAM.
393  */
ossl_quic_stream_has_send_buffer(const QUIC_STREAM * s)394 static ossl_inline ossl_unused int ossl_quic_stream_has_send_buffer(const QUIC_STREAM *s)
395 {
396     switch (s->send_state) {
397     case QUIC_SSTREAM_STATE_READY:
398     case QUIC_SSTREAM_STATE_SEND:
399     case QUIC_SSTREAM_STATE_DATA_SENT:
400         return 1;
401     default:
402         return 0;
403     }
404 }
405 
406 /*
407  * Returns 1 if the QUIC_STREAM has a sending part which is in one of the reset
408  * states.
409  */
ossl_quic_stream_send_is_reset(const QUIC_STREAM * s)410 static ossl_inline ossl_unused int ossl_quic_stream_send_is_reset(const QUIC_STREAM *s)
411 {
412     return s->send_state == QUIC_SSTREAM_STATE_RESET_SENT
413         || s->send_state == QUIC_SSTREAM_STATE_RESET_RECVD;
414 }
415 
416 /*
417  * Returns 1 if the QUIC_STREAM has a QUIC_RSTREAM receive buffer associated
418  * with it. If this returns 1, s->rstream is guaranteed to be non-NULL. The
419  * converse is not necessarily true; erasure of a receive stream buffer which is
420  * no longer required is an optimisation which the QSM may, but is not obliged,
421  * to perform.
422  *
423  * This call should be used where it is desired to do something with the receive
424  * stream buffer but there is no more specific receive state restriction which is
425  * applicable.
426  */
ossl_quic_stream_has_recv_buffer(const QUIC_STREAM * s)427 static ossl_inline ossl_unused int ossl_quic_stream_has_recv_buffer(const QUIC_STREAM *s)
428 {
429     switch (s->recv_state) {
430     case QUIC_RSTREAM_STATE_RECV:
431     case QUIC_RSTREAM_STATE_SIZE_KNOWN:
432     case QUIC_RSTREAM_STATE_DATA_RECVD:
433         return 1;
434     default:
435         return 0;
436     }
437 }
438 
439 /*
440  * Returns 1 if the QUIC_STREAM has a receiving part which is in one of the
441  * reset states.
442  */
ossl_quic_stream_recv_is_reset(const QUIC_STREAM * s)443 static ossl_inline ossl_unused int ossl_quic_stream_recv_is_reset(const QUIC_STREAM *s)
444 {
445     return s->recv_state == QUIC_RSTREAM_STATE_RESET_RECVD
446         || s->recv_state == QUIC_RSTREAM_STATE_RESET_READ;
447 }
448 
449 /*
450  * Returns 1 if the stream has a send part and that part has a final size.
451  *
452  * If final_size is non-NULL, *final_size is the final size (on success) or an
453  * undefined value otherwise.
454  */
ossl_quic_stream_send_get_final_size(const QUIC_STREAM * s,uint64_t * final_size)455 static ossl_inline ossl_unused int ossl_quic_stream_send_get_final_size(const QUIC_STREAM *s,
456                                                                         uint64_t *final_size)
457 {
458     switch (s->send_state) {
459     default:
460     case QUIC_SSTREAM_STATE_NONE:
461         return 0;
462     case QUIC_SSTREAM_STATE_SEND:
463         /*
464          * SEND may or may not have had a FIN - even if we have a FIN we do not
465          * move to DATA_SENT until we have actually sent all the data. So
466          * ask the QUIC_SSTREAM.
467          */
468         return ossl_quic_sstream_get_final_size(s->sstream, final_size);
469     case QUIC_SSTREAM_STATE_DATA_SENT:
470     case QUIC_SSTREAM_STATE_DATA_RECVD:
471     case QUIC_SSTREAM_STATE_RESET_SENT:
472     case QUIC_SSTREAM_STATE_RESET_RECVD:
473         if (final_size != NULL)
474             *final_size = s->send_final_size;
475         return 1;
476     }
477 }
478 
479 /*
480  * Returns 1 if the stream has a receive part and that part has a final size.
481  *
482  * If final_size is non-NULL, *final_size is the final size (on success) or an
483  * undefined value otherwise.
484  */
ossl_quic_stream_recv_get_final_size(const QUIC_STREAM * s,uint64_t * final_size)485 static ossl_inline ossl_unused int ossl_quic_stream_recv_get_final_size(const QUIC_STREAM *s,
486                                                                         uint64_t *final_size)
487 {
488     switch (s->recv_state) {
489     default:
490         assert(0);
491     case QUIC_RSTREAM_STATE_NONE:
492     case QUIC_RSTREAM_STATE_RECV:
493         return 0;
494 
495     case QUIC_RSTREAM_STATE_SIZE_KNOWN:
496     case QUIC_RSTREAM_STATE_DATA_RECVD:
497     case QUIC_RSTREAM_STATE_DATA_READ:
498     case QUIC_RSTREAM_STATE_RESET_RECVD:
499     case QUIC_RSTREAM_STATE_RESET_READ:
500         if (!ossl_assert(ossl_quic_rxfc_get_final_size(&s->rxfc, final_size)))
501             return 0;
502 
503         return 1;
504     }
505 }
506 
507 /*
508  * Determines the number of bytes available still to be read, and (if
509  * include_fin is 1) whether a FIN or reset has yet to be read.
510  */
ossl_quic_stream_recv_pending(const QUIC_STREAM * s,int include_fin)511 static ossl_inline ossl_unused int ossl_quic_stream_recv_pending(const QUIC_STREAM *s,
512                                                                  int include_fin)
513 {
514     size_t avail;
515     int fin = 0;
516 
517     switch (s->recv_state) {
518     default:
519         assert(0);
520     case QUIC_RSTREAM_STATE_NONE:
521         return 0;
522 
523     case QUIC_RSTREAM_STATE_RECV:
524     case QUIC_RSTREAM_STATE_SIZE_KNOWN:
525     case QUIC_RSTREAM_STATE_DATA_RECVD:
526         if (!ossl_quic_rstream_available(s->rstream, &avail, &fin))
527             avail = 0;
528 
529         if (avail == 0 && include_fin && fin)
530             avail = 1;
531 
532         return avail;
533 
534     case QUIC_RSTREAM_STATE_RESET_RECVD:
535         return include_fin;
536 
537     case QUIC_RSTREAM_STATE_DATA_READ:
538     case QUIC_RSTREAM_STATE_RESET_READ:
539         return 0;
540     }
541 }
542 
543 /*
544  * QUIC Stream Map
545  * ===============
546  *
547  * The QUIC stream map:
548  *
549  *   - maps stream IDs to QUIC_STREAM objects;
550  *   - tracks which streams are 'active' (currently have data for transmission);
551  *   - allows iteration over the active streams only.
552  *
553  */
554 struct quic_stream_map_st {
555     LHASH_OF(QUIC_STREAM)   *map;
556     QUIC_STREAM_LIST_NODE   active_list;
557     QUIC_STREAM_LIST_NODE   accept_list;
558     QUIC_STREAM_LIST_NODE   ready_for_gc_list;
559     size_t                  rr_stepping, rr_counter;
560     size_t                  num_accept_bidi, num_accept_uni, num_shutdown_flush;
561     QUIC_STREAM             *rr_cur;
562     uint64_t                (*get_stream_limit_cb)(int uni, void *arg);
563     void                    *get_stream_limit_cb_arg;
564     QUIC_RXFC               *max_streams_bidi_rxfc;
565     QUIC_RXFC               *max_streams_uni_rxfc;
566     int                     is_server;
567 };
568 
569 /*
570  * get_stream_limit is a callback which is called to retrieve the current stream
571  * limit for streams created by us. This mechanism is not used for
572  * peer-initiated streams. If a stream's stream ID is x, a stream is allowed if
573  * (x >> 2) < returned limit value; i.e., the returned value is exclusive.
574  *
575  * If uni is 1, get the limit for locally-initiated unidirectional streams, else
576  * get the limit for locally-initiated bidirectional streams.
577  *
578  * If the callback is NULL, stream limiting is not applied.
579  * Stream limiting is used to determine if frames can currently be produced for
580  * a stream.
581  */
582 int ossl_quic_stream_map_init(QUIC_STREAM_MAP *qsm,
583                               uint64_t (*get_stream_limit_cb)(int uni, void *arg),
584                               void *get_stream_limit_cb_arg,
585                               QUIC_RXFC *max_streams_bidi_rxfc,
586                               QUIC_RXFC *max_streams_uni_rxfc,
587                               int is_server);
588 
589 /*
590  * Any streams still in the map will be released as though
591  * ossl_quic_stream_map_release was called on them.
592  */
593 void ossl_quic_stream_map_cleanup(QUIC_STREAM_MAP *qsm);
594 
595 /*
596  * Allocate a new stream. type is a combination of one QUIC_STREAM_INITIATOR_*
597  * value and one QUIC_STREAM_DIR_* value. Note that clients can e.g. allocate
598  * server-initiated streams as they will need to allocate a QUIC_STREAM
599  * structure to track any stream created by the server, etc.
600  *
601  * stream_id must be a valid value. Returns NULL if a stream already exists
602  * with the given ID.
603  */
604 QUIC_STREAM *ossl_quic_stream_map_alloc(QUIC_STREAM_MAP *qsm,
605                                         uint64_t stream_id,
606                                         int type);
607 
608 /*
609  * Releases a stream object. Note that this must only be done once the teardown
610  * process is entirely complete and the object will never be referenced again.
611  */
612 void ossl_quic_stream_map_release(QUIC_STREAM_MAP *qsm, QUIC_STREAM *stream);
613 
614 /*
615  * Calls visit_cb() for each stream in the map. visit_cb_arg is an opaque
616  * argument which is passed through.
617  */
618 void ossl_quic_stream_map_visit(QUIC_STREAM_MAP *qsm,
619                                 void (*visit_cb)(QUIC_STREAM *stream, void *arg),
620                                 void *visit_cb_arg);
621 
622 /*
623  * Retrieves a stream by stream ID. Returns NULL if it does not exist.
624  */
625 QUIC_STREAM *ossl_quic_stream_map_get_by_id(QUIC_STREAM_MAP *qsm,
626                                             uint64_t stream_id);
627 
628 /*
629  * Marks the given stream as active or inactive based on its state. Idempotent.
630  *
631  * When a stream is marked active, it becomes available in the iteration list,
632  * and when a stream is marked inactive, it no longer appears in the iteration
633  * list.
634  *
635  * Calling this function invalidates any iterator currently pointing at the
636  * given stream object, but iterators not currently pointing at the given stream
637  * object are not invalidated.
638  */
639 void ossl_quic_stream_map_update_state(QUIC_STREAM_MAP *qsm, QUIC_STREAM *s);
640 
641 /*
642  * Sets the RR stepping value, n. The RR rotation will be advanced every n
643  * packets. The default value is 1.
644  */
645 void ossl_quic_stream_map_set_rr_stepping(QUIC_STREAM_MAP *qsm, size_t stepping);
646 
647 /*
648  * Returns 1 if the stream ordinal given is allowed by the current stream count
649  * flow control limit, assuming a locally initiated stream of a type described
650  * by is_uni.
651  *
652  * Note that stream_ordinal is a stream ordinal, not a stream ID.
653  */
654 int ossl_quic_stream_map_is_local_allowed_by_stream_limit(QUIC_STREAM_MAP *qsm,
655                                                           uint64_t stream_ordinal,
656                                                           int is_uni);
657 
658 /*
659  * Stream Send Part
660  * ================
661  */
662 
663 /*
664  * Ensures that the sending part has transitioned out of the READY state (i.e.,
665  * to SEND, or a subsequent state). This function is named as it is because,
666  * while on paper the distinction between READY and SEND is whether we have
667  * started transmitting application data, in practice the meaningful distinction
668  * between the two states is whether we have allocated a stream ID to the stream
669  * or not. QUIC permits us to defer stream ID allocation until first STREAM (or
670  * STREAM_DATA_BLOCKED) frame transmission for locally-initiated streams.
671  *
672  * Our implementation does not currently do this and we allocate stream IDs up
673  * front, however we may revisit this in the future. Calling this represents a
674  * demand for a stream ID by the caller and ensures one has been allocated to
675  * the stream, and causes us to transition to SEND if we are still in the READY
676  * state.
677  *
678  * Returns 0 if there is no send part (caller error) and 1 otherwise.
679  */
680 int ossl_quic_stream_map_ensure_send_part_id(QUIC_STREAM_MAP *qsm,
681                                              QUIC_STREAM *qs);
682 
683 /*
684  * Transitions from SEND to the DATA_SENT state. Note that this is NOT the same
685  * as the point in time at which the final size of the stream becomes known
686  * (i.e., the time at which ossl_quic_sstream_fin()) is called as it occurs when
687  * we have SENT all data on a given stream send part, not merely buffered it.
688  * Note that this transition is NOT reversed in the event of some of that data
689  * being lost.
690  *
691  * Returns 1 if the state transition was successfully taken. Returns 0 if there
692  * is no send part (caller error) or if the state transition cannot be taken
693  * because the send part is not in the SEND state.
694  */
695 int ossl_quic_stream_map_notify_all_data_sent(QUIC_STREAM_MAP *qsm,
696                                               QUIC_STREAM *qs);
697 
698 /*
699  * Transitions from the DATA_SENT to DATA_RECVD state; should be called
700  * when all transmitted stream data is ACKed by the peer.
701  *
702  * Returns 1 if the state transition was successfully taken. Returns 0 if there
703  * is no send part (caller error) or the state transition cannot be taken
704  * because the send part is not in the DATA_SENT state. Because
705  * ossl_quic_stream_map_notify_all_data_sent() should always be called prior to
706  * this function, the send state must already be in DATA_SENT in order for this
707  * function to succeed.
708  */
709 int ossl_quic_stream_map_notify_totally_acked(QUIC_STREAM_MAP *qsm,
710                                               QUIC_STREAM *qs);
711 
712 /*
713  * Resets the sending part of a stream. This is a transition from the READY,
714  * SEND or DATA_SENT send stream states to the RESET_SENT state.
715  *
716  * This function returns 1 if the transition is taken (i.e., if the send stream
717  * part was in one of the states above), or if it is already in the RESET_SENT
718  * state (idempotent operation), or if it has reached the RESET_RECVD state.
719  *
720  * It returns 0 if in the DATA_RECVD state, as a send stream cannot be reset
721  * in this state. It also returns 0 if there is no send part (caller error).
722  */
723 int ossl_quic_stream_map_reset_stream_send_part(QUIC_STREAM_MAP *qsm,
724                                                 QUIC_STREAM *qs,
725                                                 uint64_t aec);
726 
727 /*
728  * Transitions from the RESET_SENT to the RESET_RECVD state. This should be
729  * called when a sent RESET_STREAM frame has been acknowledged by the peer.
730  *
731  * This function returns 1 if the transition is taken (i.e., if the send stream
732  * part was in one of the states above) or if it is already in the RESET_RECVD
733  * state (idempotent operation).
734  *
735  * It returns 0 if not in the RESET_SENT or RESET_RECVD states, as this function
736  * should only be called after we have already sent a RESET_STREAM frame and
737  * entered the RESET_SENT state. It also returns 0 if there is no send part
738  * (caller error).
739  */
740 int ossl_quic_stream_map_notify_reset_stream_acked(QUIC_STREAM_MAP *qsm,
741                                                    QUIC_STREAM *qs);
742 
743 
744 /*
745  * Stream Receive Part
746  * ===================
747  */
748 
749 /*
750  * Transitions from the RECV receive stream state to the SIZE_KNOWN state. This
751  * should be called once a STREAM frame is received for the stream with the FIN
752  * bit set. final_size should be the final size of the stream in bytes.
753  *
754  * Returns 1 if the transition was taken.
755  */
756 int ossl_quic_stream_map_notify_size_known_recv_part(QUIC_STREAM_MAP *qsm,
757                                                      QUIC_STREAM *qs,
758                                                      uint64_t final_size);
759 
760 /*
761  * Transitions from the SIZE_KNOWN receive stream state to the DATA_RECVD state.
762  * This should be called once all data for a receive stream is received.
763  *
764  * Returns 1 if the transition was taken.
765  */
766 int ossl_quic_stream_map_notify_totally_received(QUIC_STREAM_MAP *qsm,
767                                                  QUIC_STREAM *qs);
768 
769 /*
770  * Transitions from the DATA_RECVD receive stream state to the DATA_READ state.
771  * This should be called once all data for a receive stream is read by the
772  * application.
773  *
774  * Returns 1 if the transition was taken.
775  */
776 int ossl_quic_stream_map_notify_totally_read(QUIC_STREAM_MAP *qsm,
777                                              QUIC_STREAM *qs);
778 
779 /*
780  * Transitions from the RECV, SIZE_KNOWN or DATA_RECVD receive stream state to
781  * the RESET_RECVD state. This should be called on RESET_STREAM.
782  *
783  * Returns 1 if the transition was taken.
784  */
785 int ossl_quic_stream_map_notify_reset_recv_part(QUIC_STREAM_MAP *qsm,
786                                                 QUIC_STREAM *qs,
787                                                 uint64_t app_error_code,
788                                                 uint64_t final_size);
789 
790 /*
791  * Transitions from the RESET_RECVD receive stream state to the RESET_READ
792  * receive stream state. This should be called when the application is notified
793  * of a stream reset.
794  */
795 int ossl_quic_stream_map_notify_app_read_reset_recv_part(QUIC_STREAM_MAP *qsm,
796                                                          QUIC_STREAM *qs);
797 
798 /*
799  * Marks the receiving part of a stream for STOP_SENDING. This is orthogonal to
800  * receive stream state as it does not affect it directly.
801  *
802  * Returns 1 if the receiving part of a stream was not already marked for
803  * STOP_SENDING.
804  * Returns 0 otherwise, which need not be considered an error.
805  */
806 int ossl_quic_stream_map_stop_sending_recv_part(QUIC_STREAM_MAP *qsm,
807                                                 QUIC_STREAM *qs,
808                                                 uint64_t aec);
809 
810 /*
811  * Marks the stream as wanting a STOP_SENDING frame transmitted. It is not valid
812  * to call this if ossl_quic_stream_map_stop_sending_recv_part() has not been
813  * called. For TXP use.
814  */
815 int ossl_quic_stream_map_schedule_stop_sending(QUIC_STREAM_MAP *qsm,
816                                                QUIC_STREAM *qs);
817 
818 
819 /*
820  * Accept Queue Management
821  * =======================
822  */
823 
824 /*
825  * Adds a stream to the accept queue.
826  */
827 void ossl_quic_stream_map_push_accept_queue(QUIC_STREAM_MAP *qsm,
828                                             QUIC_STREAM *s);
829 
830 /*
831  * Returns the next item to be popped from the accept queue, or NULL if it is
832  * empty.
833  */
834 QUIC_STREAM *ossl_quic_stream_map_peek_accept_queue(QUIC_STREAM_MAP *qsm);
835 
836 /*
837  * Removes a stream from the accept queue. rtt is the estimated connection RTT.
838  * The stream is retired for the purposes of MAX_STREAMS RXFC.
839  *
840  * Precondition: s is in the accept queue.
841  */
842 void ossl_quic_stream_map_remove_from_accept_queue(QUIC_STREAM_MAP *qsm,
843                                                    QUIC_STREAM *s,
844                                                    OSSL_TIME rtt);
845 
846 /* Returns the length of the accept queue for the given stream type. */
847 size_t ossl_quic_stream_map_get_accept_queue_len(QUIC_STREAM_MAP *qsm, int is_uni);
848 
849 /* Returns the total length of the accept queues for all stream types. */
850 size_t ossl_quic_stream_map_get_total_accept_queue_len(QUIC_STREAM_MAP *qsm);
851 
852 /*
853  * Shutdown Flush and GC
854  * =====================
855  */
856 
857 /*
858  * Delete streams ready for GC. Pointers to those QUIC_STREAM objects become
859  * invalid.
860  */
861 void ossl_quic_stream_map_gc(QUIC_STREAM_MAP *qsm);
862 
863 /*
864  * Begins shutdown stream flush triage. Analyses all streams, including deleted
865  * but not yet GC'd streams, to determine if we should wait for that stream to
866  * be fully flushed before shutdown. After calling this, call
867  * ossl_quic_stream_map_is_shutdown_flush_finished() to determine if all
868  * shutdown flush eligible streams have been flushed.
869  */
870 void ossl_quic_stream_map_begin_shutdown_flush(QUIC_STREAM_MAP *qsm);
871 
872 /*
873  * Returns 1 if all shutdown flush eligible streams have finished flushing,
874  * or if ossl_quic_stream_map_begin_shutdown_flush() has not been called.
875  */
876 int ossl_quic_stream_map_is_shutdown_flush_finished(QUIC_STREAM_MAP *qsm);
877 
878 /*
879  * QUIC Stream Iterator
880  * ====================
881  *
882  * Allows the current set of active streams to be walked using a RR-based
883  * algorithm. Each time ossl_quic_stream_iter_init is called, the RR algorithm
884  * is stepped. The RR algorithm rotates the iteration order such that the next
885  * active stream is returned first after n calls to ossl_quic_stream_iter_init,
886  * where n is the stepping value configured via
887  * ossl_quic_stream_map_set_rr_stepping.
888  *
889  * Suppose there are three active streams and the configured stepping is n:
890  *
891  *   Iteration 0n:  [Stream 1] [Stream 2] [Stream 3]
892  *   Iteration 1n:  [Stream 2] [Stream 3] [Stream 1]
893  *   Iteration 2n:  [Stream 3] [Stream 1] [Stream 2]
894  *
895  */
896 typedef struct quic_stream_iter_st {
897     QUIC_STREAM_MAP     *qsm;
898     QUIC_STREAM         *first_stream, *stream;
899 } QUIC_STREAM_ITER;
900 
901 /*
902  * Initialise an iterator, advancing the RR algorithm as necessary (if
903  * advance_rr is 1). After calling this, it->stream will be the first stream in
904  * the iteration sequence, or NULL if there are no active streams.
905  */
906 void ossl_quic_stream_iter_init(QUIC_STREAM_ITER *it, QUIC_STREAM_MAP *qsm,
907                                 int advance_rr);
908 
909 /*
910  * Advances to next stream in iteration sequence. You do not need to call this
911  * immediately after calling ossl_quic_stream_iter_init(). If the end of the
912  * list is reached, it->stream will be NULL after calling this.
913  */
914 void ossl_quic_stream_iter_next(QUIC_STREAM_ITER *it);
915 
916 # endif
917 
918 #endif
919