]>
Commit | Line | Data |
---|---|---|
83022590 HL |
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" | |
bbf902c3 | 19 | #include "internal/quic_record_rx.h" |
e77396f6 TM |
20 | #include "internal/quic_fc.h" |
21 | #include "internal/quic_statm.h" | |
83022590 | 22 | |
6292519c HL |
23 | # ifndef OPENSSL_NO_QUIC |
24 | ||
83022590 HL |
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 | ||
05f97354 HL |
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 | ||
a73078b7 HL |
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 | ||
83022590 HL |
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 | ||
a9979965 HL |
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 | ||
83022590 HL |
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 | ||
bbf902c3 TM |
292 | /* |
293 | * QUIC Receive Stream Manager | |
294 | * =========================== | |
295 | * | |
e77396f6 TM |
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. | |
bbf902c3 TM |
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 | /* | |
e77396f6 TM |
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 | |
a17c713a | 310 | * is read by application. `statm` is queried for current rtt. |
bbf902c3 | 311 | */ |
6d5d5fc9 | 312 | QUIC_RSTREAM *ossl_quic_rstream_new(QUIC_RXFC *rxfc, |
e77396f6 | 313 | OSSL_STATM *statm); |
bbf902c3 TM |
314 | |
315 | /* | |
316 | * Frees a QUIC_RSTREAM and any associated storage. | |
317 | */ | |
318 | void ossl_quic_rstream_free(QUIC_RSTREAM *qrs); | |
319 | ||
320 | /* | |
e77396f6 TM |
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. | |
bbf902c3 TM |
328 | */ |
329 | ||
6d5d5fc9 | 330 | int ossl_quic_rstream_queue_data(QUIC_RSTREAM *qrs, OSSL_QRX_PKT *pkt, |
bbf902c3 TM |
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); | |
83022590 | 359 | |
6292519c HL |
360 | # endif |
361 | ||
83022590 | 362 | #endif |