1 /* 2 * nghttp2 - HTTP/2 C Library 3 * 4 * Copyright (c) 2012 Tatsuhiro Tsujikawa 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining 7 * a copy of this software and associated documentation files (the 8 * "Software"), to deal in the Software without restriction, including 9 * without limitation the rights to use, copy, modify, merge, publish, 10 * distribute, sublicense, and/or sell copies of the Software, and to 11 * permit persons to whom the Software is furnished to do so, subject to 12 * the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be 15 * included in all copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 20 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 21 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 22 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 23 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 24 */ 25 #ifndef NGHTTP2_SESSION_H 26 #define NGHTTP2_SESSION_H 27 28 #ifdef HAVE_CONFIG_H 29 # include <config.h> 30 #endif /* HAVE_CONFIG_H */ 31 32 #include <nghttp2/nghttp2.h> 33 #include "nghttp2_map.h" 34 #include "nghttp2_frame.h" 35 #include "nghttp2_hd.h" 36 #include "nghttp2_stream.h" 37 #include "nghttp2_outbound_item.h" 38 #include "nghttp2_int.h" 39 #include "nghttp2_buf.h" 40 #include "nghttp2_callbacks.h" 41 #include "nghttp2_mem.h" 42 43 /* The global variable for tests where we want to disable strict 44 preface handling. */ 45 extern int nghttp2_enable_strict_preface; 46 47 /* 48 * Option flags. 49 */ 50 typedef enum { 51 NGHTTP2_OPTMASK_NO_AUTO_WINDOW_UPDATE = 1 << 0, 52 NGHTTP2_OPTMASK_NO_RECV_CLIENT_MAGIC = 1 << 1, 53 NGHTTP2_OPTMASK_NO_HTTP_MESSAGING = 1 << 2, 54 NGHTTP2_OPTMASK_NO_AUTO_PING_ACK = 1 << 3, 55 NGHTTP2_OPTMASK_NO_CLOSED_STREAMS = 1 << 4 56 } nghttp2_optmask; 57 58 /* 59 * bitmask for built-in type to enable the default handling for that 60 * type of the frame. 61 */ 62 typedef enum { 63 NGHTTP2_TYPEMASK_NONE = 0, 64 NGHTTP2_TYPEMASK_ALTSVC = 1 << 0, 65 NGHTTP2_TYPEMASK_ORIGIN = 1 << 1 66 } nghttp2_typemask; 67 68 typedef enum { 69 NGHTTP2_OB_POP_ITEM, 70 NGHTTP2_OB_SEND_DATA, 71 NGHTTP2_OB_SEND_NO_COPY, 72 NGHTTP2_OB_SEND_CLIENT_MAGIC 73 } nghttp2_outbound_state; 74 75 typedef struct { 76 nghttp2_outbound_item *item; 77 nghttp2_bufs framebufs; 78 nghttp2_outbound_state state; 79 } nghttp2_active_outbound_item; 80 81 /* Buffer length for inbound raw byte stream used in 82 nghttp2_session_recv(). */ 83 #define NGHTTP2_INBOUND_BUFFER_LENGTH 16384 84 85 /* The default maximum number of incoming reserved streams */ 86 #define NGHTTP2_MAX_INCOMING_RESERVED_STREAMS 200 87 88 /* Even if we have less SETTINGS_MAX_CONCURRENT_STREAMS than this 89 number, we keep NGHTTP2_MIN_IDLE_STREAMS streams in idle state */ 90 #define NGHTTP2_MIN_IDLE_STREAMS 16 91 92 /* The maximum number of items in outbound queue, which is considered 93 as flooding caused by peer. All frames are not considered here. 94 We only consider PING + ACK and SETTINGS + ACK. This is because 95 they both are response to the frame initiated by peer and peer can 96 send as many of them as they want. If peer does not read network, 97 response frames are stacked up, which leads to memory exhaustion. 98 The value selected here is arbitrary, but safe value and if we have 99 these frames in this number, it is considered suspicious. */ 100 #define NGHTTP2_DEFAULT_MAX_OBQ_FLOOD_ITEM 1000 101 102 /* The default value of maximum number of concurrent streams. */ 103 #define NGHTTP2_DEFAULT_MAX_CONCURRENT_STREAMS 0xffffffffu 104 105 /* Internal state when receiving incoming frame */ 106 typedef enum { 107 /* Receiving frame header */ 108 NGHTTP2_IB_READ_CLIENT_MAGIC, 109 NGHTTP2_IB_READ_FIRST_SETTINGS, 110 NGHTTP2_IB_READ_HEAD, 111 NGHTTP2_IB_READ_NBYTE, 112 NGHTTP2_IB_READ_HEADER_BLOCK, 113 NGHTTP2_IB_IGN_HEADER_BLOCK, 114 NGHTTP2_IB_IGN_PAYLOAD, 115 NGHTTP2_IB_FRAME_SIZE_ERROR, 116 NGHTTP2_IB_READ_SETTINGS, 117 NGHTTP2_IB_READ_GOAWAY_DEBUG, 118 NGHTTP2_IB_EXPECT_CONTINUATION, 119 NGHTTP2_IB_IGN_CONTINUATION, 120 NGHTTP2_IB_READ_PAD_DATA, 121 NGHTTP2_IB_READ_DATA, 122 NGHTTP2_IB_IGN_DATA, 123 NGHTTP2_IB_IGN_ALL, 124 NGHTTP2_IB_READ_ALTSVC_PAYLOAD, 125 NGHTTP2_IB_READ_ORIGIN_PAYLOAD, 126 NGHTTP2_IB_READ_EXTENSION_PAYLOAD 127 } nghttp2_inbound_state; 128 129 typedef struct { 130 nghttp2_frame frame; 131 /* Storage for extension frame payload. frame->ext.payload points 132 to this structure to avoid frequent memory allocation. */ 133 nghttp2_ext_frame_payload ext_frame_payload; 134 /* The received SETTINGS entry. For the standard settings entries, 135 we only keep the last seen value. For 136 SETTINGS_HEADER_TABLE_SIZE, we also keep minimum value in the 137 last index. */ 138 nghttp2_settings_entry *iv; 139 /* buffer pointers to small buffer, raw_sbuf */ 140 nghttp2_buf sbuf; 141 /* buffer pointers to large buffer, raw_lbuf */ 142 nghttp2_buf lbuf; 143 /* Large buffer, malloced on demand */ 144 uint8_t *raw_lbuf; 145 /* The number of entry filled in |iv| */ 146 size_t niv; 147 /* The number of entries |iv| can store. */ 148 size_t max_niv; 149 /* How many bytes we still need to receive for current frame */ 150 size_t payloadleft; 151 /* padding length for the current frame */ 152 size_t padlen; 153 nghttp2_inbound_state state; 154 /* Small buffer. Currently the largest contiguous chunk to buffer 155 is frame header. We buffer part of payload, but they are smaller 156 than frame header. */ 157 uint8_t raw_sbuf[NGHTTP2_FRAME_HDLEN]; 158 } nghttp2_inbound_frame; 159 160 typedef struct { 161 uint32_t header_table_size; 162 uint32_t enable_push; 163 uint32_t max_concurrent_streams; 164 uint32_t initial_window_size; 165 uint32_t max_frame_size; 166 uint32_t max_header_list_size; 167 uint32_t enable_connect_protocol; 168 } nghttp2_settings_storage; 169 170 typedef enum { 171 NGHTTP2_GOAWAY_NONE = 0, 172 /* Flag means that connection should be terminated after sending GOAWAY. */ 173 NGHTTP2_GOAWAY_TERM_ON_SEND = 0x1, 174 /* Flag means GOAWAY to terminate session has been sent */ 175 NGHTTP2_GOAWAY_TERM_SENT = 0x2, 176 /* Flag means GOAWAY was sent */ 177 NGHTTP2_GOAWAY_SENT = 0x4, 178 /* Flag means GOAWAY was received */ 179 NGHTTP2_GOAWAY_RECV = 0x8 180 } nghttp2_goaway_flag; 181 182 /* nghttp2_inflight_settings stores the SETTINGS entries which local 183 endpoint has sent to the remote endpoint, and has not received ACK 184 yet. */ 185 struct nghttp2_inflight_settings { 186 struct nghttp2_inflight_settings *next; 187 nghttp2_settings_entry *iv; 188 size_t niv; 189 }; 190 191 typedef struct nghttp2_inflight_settings nghttp2_inflight_settings; 192 193 struct nghttp2_session { 194 nghttp2_map /* <nghttp2_stream*> */ streams; 195 /* root of dependency tree*/ 196 nghttp2_stream root; 197 /* Queue for outbound urgent frames (PING and SETTINGS) */ 198 nghttp2_outbound_queue ob_urgent; 199 /* Queue for non-DATA frames */ 200 nghttp2_outbound_queue ob_reg; 201 /* Queue for outbound stream-creating HEADERS (request or push 202 response) frame, which are subject to 203 SETTINGS_MAX_CONCURRENT_STREAMS limit. */ 204 nghttp2_outbound_queue ob_syn; 205 nghttp2_active_outbound_item aob; 206 nghttp2_inbound_frame iframe; 207 nghttp2_hd_deflater hd_deflater; 208 nghttp2_hd_inflater hd_inflater; 209 nghttp2_session_callbacks callbacks; 210 /* Memory allocator */ 211 nghttp2_mem mem; 212 void *user_data; 213 /* Points to the latest incoming closed stream. NULL if there is no 214 closed stream. Only used when session is initialized as 215 server. */ 216 nghttp2_stream *closed_stream_head; 217 /* Points to the oldest incoming closed stream. NULL if there is no 218 closed stream. Only used when session is initialized as 219 server. */ 220 nghttp2_stream *closed_stream_tail; 221 /* Points to the latest idle stream. NULL if there is no idle 222 stream. Only used when session is initialized as server .*/ 223 nghttp2_stream *idle_stream_head; 224 /* Points to the oldest idle stream. NULL if there is no idle 225 stream. Only used when session is initialized as erver. */ 226 nghttp2_stream *idle_stream_tail; 227 /* Queue of In-flight SETTINGS values. SETTINGS bearing ACK is not 228 considered as in-flight. */ 229 nghttp2_inflight_settings *inflight_settings_head; 230 /* The number of outgoing streams. This will be capped by 231 remote_settings.max_concurrent_streams. */ 232 size_t num_outgoing_streams; 233 /* The number of incoming streams. This will be capped by 234 local_settings.max_concurrent_streams. */ 235 size_t num_incoming_streams; 236 /* The number of incoming reserved streams. This is the number of 237 streams in reserved (remote) state. RFC 7540 does not limit this 238 number. nghttp2 offers 239 nghttp2_option_set_max_reserved_remote_streams() to achieve this. 240 If it is used, num_incoming_streams is capped by 241 max_incoming_reserved_streams. Client application should 242 consider to set this because without that server can send 243 arbitrary number of PUSH_PROMISE, and exhaust client's memory. */ 244 size_t num_incoming_reserved_streams; 245 /* The maximum number of incoming reserved streams (reserved 246 (remote) state). RST_STREAM will be sent for the pushed stream 247 which exceeds this limit. */ 248 size_t max_incoming_reserved_streams; 249 /* The number of closed streams still kept in |streams| hash. The 250 closed streams can be accessed through single linked list 251 |closed_stream_head|. The current implementation only keeps 252 incoming streams and session is initialized as server. */ 253 size_t num_closed_streams; 254 /* The number of idle streams kept in |streams| hash. The idle 255 streams can be accessed through doubly linked list 256 |idle_stream_head|. The current implementation only keeps idle 257 streams if session is initialized as server. */ 258 size_t num_idle_streams; 259 /* The number of bytes allocated for nvbuf */ 260 size_t nvbuflen; 261 /* Counter for detecting flooding in outbound queue. If it exceeds 262 max_outbound_ack, session will be closed. */ 263 size_t obq_flood_counter_; 264 /* The maximum number of outgoing SETTINGS ACK and PING ACK in 265 outbound queue. */ 266 size_t max_outbound_ack; 267 /* The maximum length of header block to send. Calculated by the 268 same way as nghttp2_hd_deflate_bound() does. */ 269 size_t max_send_header_block_length; 270 /* The maximum number of settings accepted per SETTINGS frame. */ 271 size_t max_settings; 272 /* Next Stream ID. Made unsigned int to detect >= (1 << 31). */ 273 uint32_t next_stream_id; 274 /* The last stream ID this session initiated. For client session, 275 this is the last stream ID it has sent. For server session, it 276 is the last promised stream ID sent in PUSH_PROMISE. */ 277 int32_t last_sent_stream_id; 278 /* The largest stream ID received so far */ 279 int32_t last_recv_stream_id; 280 /* The largest stream ID which has been processed in some way. This 281 value will be used as last-stream-id when sending GOAWAY 282 frame. */ 283 int32_t last_proc_stream_id; 284 /* Counter of unique ID of PING. Wraps when it exceeds 285 NGHTTP2_MAX_UNIQUE_ID */ 286 uint32_t next_unique_id; 287 /* This is the last-stream-ID we have sent in GOAWAY */ 288 int32_t local_last_stream_id; 289 /* This is the value in GOAWAY frame received from remote endpoint. */ 290 int32_t remote_last_stream_id; 291 /* Current sender window size. This value is computed against the 292 current initial window size of remote endpoint. */ 293 int32_t remote_window_size; 294 /* Keep track of the number of bytes received without 295 WINDOW_UPDATE. This could be negative after submitting negative 296 value to WINDOW_UPDATE. */ 297 int32_t recv_window_size; 298 /* The number of bytes consumed by the application and now is 299 subject to WINDOW_UPDATE. This is only used when auto 300 WINDOW_UPDATE is turned off. */ 301 int32_t consumed_size; 302 /* The amount of recv_window_size cut using submitting negative 303 value to WINDOW_UPDATE */ 304 int32_t recv_reduction; 305 /* window size for local flow control. It is initially set to 306 NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE and could be 307 increased/decreased by submitting WINDOW_UPDATE. See 308 nghttp2_submit_window_update(). */ 309 int32_t local_window_size; 310 /* This flag is used to indicate that the local endpoint received initial 311 SETTINGS frame from the remote endpoint. */ 312 uint8_t remote_settings_received; 313 /* Settings value received from the remote endpoint. */ 314 nghttp2_settings_storage remote_settings; 315 /* Settings value of the local endpoint. */ 316 nghttp2_settings_storage local_settings; 317 /* Option flags. This is bitwise-OR of 0 or more of nghttp2_optmask. */ 318 uint32_t opt_flags; 319 /* Unacked local SETTINGS_MAX_CONCURRENT_STREAMS value. We use this 320 to refuse the incoming stream if it exceeds this value. */ 321 uint32_t pending_local_max_concurrent_stream; 322 /* The bitwise OR of zero or more of nghttp2_typemask to indicate 323 that the default handling of extension frame is enabled. */ 324 uint32_t builtin_recv_ext_types; 325 /* Unacked local ENABLE_PUSH value. We use this to refuse 326 PUSH_PROMISE before SETTINGS ACK is received. */ 327 uint8_t pending_enable_push; 328 /* Unacked local ENABLE_CONNECT_PROTOCOL value. We use this to 329 accept :protocol header field before SETTINGS_ACK is received. */ 330 uint8_t pending_enable_connect_protocol; 331 /* Nonzero if the session is server side. */ 332 uint8_t server; 333 /* Flags indicating GOAWAY is sent and/or received. The flags are 334 composed by bitwise OR-ing nghttp2_goaway_flag. */ 335 uint8_t goaway_flags; 336 /* This flag is used to reduce excessive queuing of WINDOW_UPDATE to 337 this session. The nonzero does not necessarily mean 338 WINDOW_UPDATE is not queued. */ 339 uint8_t window_update_queued; 340 /* Bitfield of extension frame types that application is willing to 341 receive. To designate the bit of given frame type i, use 342 user_recv_ext_types[i / 8] & (1 << (i & 0x7)). First 10 frame 343 types are standard frame types and not used in this bitfield. If 344 bit is set, it indicates that incoming frame with that type is 345 passed to user defined callbacks, otherwise they are ignored. */ 346 uint8_t user_recv_ext_types[32]; 347 }; 348 349 /* Struct used when updating initial window size of each active 350 stream. */ 351 typedef struct { 352 nghttp2_session *session; 353 int32_t new_window_size, old_window_size; 354 } nghttp2_update_window_size_arg; 355 356 typedef struct { 357 nghttp2_session *session; 358 /* linked list of streams to close */ 359 nghttp2_stream *head; 360 int32_t last_stream_id; 361 /* nonzero if GOAWAY is sent to peer, which means we are going to 362 close incoming streams. zero if GOAWAY is received from peer and 363 we are going to close outgoing streams. */ 364 int incoming; 365 } nghttp2_close_stream_on_goaway_arg; 366 367 /* TODO stream timeout etc */ 368 369 /* 370 * Returns nonzero value if |stream_id| is initiated by local 371 * endpoint. 372 */ 373 int nghttp2_session_is_my_stream_id(nghttp2_session *session, 374 int32_t stream_id); 375 376 /* 377 * Adds |item| to the outbound queue in |session|. When this function 378 * succeeds, it takes ownership of |item|. So caller must not free it 379 * on success. 380 * 381 * This function returns 0 if it succeeds, or one of the following 382 * negative error codes: 383 * 384 * NGHTTP2_ERR_NOMEM 385 * Out of memory. 386 * NGHTTP2_ERR_STREAM_CLOSED 387 * Stream already closed (DATA and PUSH_PROMISE frame only) 388 */ 389 int nghttp2_session_add_item(nghttp2_session *session, 390 nghttp2_outbound_item *item); 391 392 /* 393 * Adds RST_STREAM frame for the stream |stream_id| with the error 394 * code |error_code|. This is a convenient function built on top of 395 * nghttp2_session_add_frame() to add RST_STREAM easily. 396 * 397 * This function simply returns 0 without adding RST_STREAM frame if 398 * given stream is in NGHTTP2_STREAM_CLOSING state, because multiple 399 * RST_STREAM for a stream is redundant. 400 * 401 * This function returns 0 if it succeeds, or one of the following 402 * negative error codes: 403 * 404 * NGHTTP2_ERR_NOMEM 405 * Out of memory. 406 */ 407 int nghttp2_session_add_rst_stream(nghttp2_session *session, int32_t stream_id, 408 uint32_t error_code); 409 410 /* 411 * Adds PING frame. This is a convenient functin built on top of 412 * nghttp2_session_add_frame() to add PING easily. 413 * 414 * If the |opaque_data| is not NULL, it must point to 8 bytes memory 415 * region of data. The data pointed by |opaque_data| is copied. It can 416 * be NULL. In this case, 8 bytes NULL is used. 417 * 418 * This function returns 0 if it succeeds, or one of the following 419 * negative error codes: 420 * 421 * NGHTTP2_ERR_NOMEM 422 * Out of memory. 423 * NGHTTP2_ERR_FLOODED 424 * There are too many items in outbound queue; this only happens 425 * if NGHTTP2_FLAG_ACK is set in |flags| 426 */ 427 int nghttp2_session_add_ping(nghttp2_session *session, uint8_t flags, 428 const uint8_t *opaque_data); 429 430 /* 431 * Adds GOAWAY frame with the last-stream-ID |last_stream_id| and the 432 * error code |error_code|. This is a convenient function built on top 433 * of nghttp2_session_add_frame() to add GOAWAY easily. The 434 * |aux_flags| are bitwise-OR of one or more of 435 * nghttp2_goaway_aux_flag. 436 * 437 * This function returns 0 if it succeeds, or one of the following 438 * negative error codes: 439 * 440 * NGHTTP2_ERR_NOMEM 441 * Out of memory. 442 * NGHTTP2_ERR_INVALID_ARGUMENT 443 * The |opaque_data_len| is too large. 444 */ 445 int nghttp2_session_add_goaway(nghttp2_session *session, int32_t last_stream_id, 446 uint32_t error_code, const uint8_t *opaque_data, 447 size_t opaque_data_len, uint8_t aux_flags); 448 449 /* 450 * Adds WINDOW_UPDATE frame with stream ID |stream_id| and 451 * window-size-increment |window_size_increment|. This is a convenient 452 * function built on top of nghttp2_session_add_frame() to add 453 * WINDOW_UPDATE easily. 454 * 455 * This function returns 0 if it succeeds, or one of the following 456 * negative error codes: 457 * 458 * NGHTTP2_ERR_NOMEM 459 * Out of memory. 460 */ 461 int nghttp2_session_add_window_update(nghttp2_session *session, uint8_t flags, 462 int32_t stream_id, 463 int32_t window_size_increment); 464 465 /* 466 * Adds SETTINGS frame. 467 * 468 * This function returns 0 if it succeeds, or one of the following 469 * negative error codes: 470 * 471 * NGHTTP2_ERR_NOMEM 472 * Out of memory. 473 * NGHTTP2_ERR_FLOODED 474 * There are too many items in outbound queue; this only happens 475 * if NGHTTP2_FLAG_ACK is set in |flags| 476 */ 477 int nghttp2_session_add_settings(nghttp2_session *session, uint8_t flags, 478 const nghttp2_settings_entry *iv, size_t niv); 479 480 /* 481 * Creates new stream in |session| with stream ID |stream_id|, 482 * priority |pri_spec| and flags |flags|. The |flags| is bitwise OR 483 * of nghttp2_stream_flag. Since this function is called when initial 484 * HEADERS is sent or received, these flags are taken from it. The 485 * state of stream is set to |initial_state|. The |stream_user_data| 486 * is a pointer to the arbitrary user supplied data to be associated 487 * to this stream. 488 * 489 * If |initial_state| is NGHTTP2_STREAM_RESERVED, this function sets 490 * NGHTTP2_STREAM_FLAG_PUSH flag set. 491 * 492 * This function returns a pointer to created new stream object, or 493 * NULL. 494 * 495 * This function adjusts neither the number of closed streams or idle 496 * streams. The caller should manually call 497 * nghttp2_session_adjust_closed_stream() or 498 * nghttp2_session_adjust_idle_stream() respectively. 499 */ 500 nghttp2_stream *nghttp2_session_open_stream(nghttp2_session *session, 501 int32_t stream_id, uint8_t flags, 502 nghttp2_priority_spec *pri_spec, 503 nghttp2_stream_state initial_state, 504 void *stream_user_data); 505 506 /* 507 * Closes stream whose stream ID is |stream_id|. The reason of closure 508 * is indicated by the |error_code|. When closing the stream, 509 * on_stream_close_callback will be called. 510 * 511 * If the session is initialized as server and |stream| is incoming 512 * stream, stream is just marked closed and this function calls 513 * nghttp2_session_keep_closed_stream() with |stream|. Otherwise, 514 * |stream| will be deleted from memory. 515 * 516 * This function returns 0 if it succeeds, or one the following 517 * negative error codes: 518 * 519 * NGHTTP2_ERR_NOMEM 520 * Out of memory 521 * NGHTTP2_ERR_INVALID_ARGUMENT 522 * The specified stream does not exist. 523 * NGHTTP2_ERR_CALLBACK_FAILURE 524 * The callback function failed. 525 */ 526 int nghttp2_session_close_stream(nghttp2_session *session, int32_t stream_id, 527 uint32_t error_code); 528 529 /* 530 * Deletes |stream| from memory. After this function returns, stream 531 * cannot be accessed. 532 * 533 * This function returns 0 if it succeeds, or one the following 534 * negative error codes: 535 * 536 * NGHTTP2_ERR_NOMEM 537 * Out of memory 538 */ 539 int nghttp2_session_destroy_stream(nghttp2_session *session, 540 nghttp2_stream *stream); 541 542 /* 543 * Tries to keep incoming closed stream |stream|. Due to the 544 * limitation of maximum number of streams in memory, |stream| is not 545 * closed and just deleted from memory (see 546 * nghttp2_session_destroy_stream). 547 */ 548 void nghttp2_session_keep_closed_stream(nghttp2_session *session, 549 nghttp2_stream *stream); 550 551 /* 552 * Appends |stream| to linked list |session->idle_stream_head|. We 553 * apply fixed limit for list size. To fit into that limit, one or 554 * more oldest streams are removed from list as necessary. 555 */ 556 void nghttp2_session_keep_idle_stream(nghttp2_session *session, 557 nghttp2_stream *stream); 558 559 /* 560 * Detaches |stream| from idle streams linked list. 561 */ 562 void nghttp2_session_detach_idle_stream(nghttp2_session *session, 563 nghttp2_stream *stream); 564 565 /* 566 * Deletes closed stream to ensure that number of incoming streams 567 * including active and closed is in the maximum number of allowed 568 * stream. 569 * 570 * This function returns 0 if it succeeds, or one the following 571 * negative error codes: 572 * 573 * NGHTTP2_ERR_NOMEM 574 * Out of memory 575 */ 576 int nghttp2_session_adjust_closed_stream(nghttp2_session *session); 577 578 /* 579 * Deletes idle stream to ensure that number of idle streams is in 580 * certain limit. 581 * 582 * This function returns 0 if it succeeds, or one the following 583 * negative error codes: 584 * 585 * NGHTTP2_ERR_NOMEM 586 * Out of memory 587 */ 588 int nghttp2_session_adjust_idle_stream(nghttp2_session *session); 589 590 /* 591 * If further receptions and transmissions over the stream |stream_id| 592 * are disallowed, close the stream with error code NGHTTP2_NO_ERROR. 593 * 594 * This function returns 0 if it 595 * succeeds, or one of the following negative error codes: 596 * 597 * NGHTTP2_ERR_INVALID_ARGUMENT 598 * The specified stream does not exist. 599 */ 600 int nghttp2_session_close_stream_if_shut_rdwr(nghttp2_session *session, 601 nghttp2_stream *stream); 602 603 int nghttp2_session_on_request_headers_received(nghttp2_session *session, 604 nghttp2_frame *frame); 605 606 int nghttp2_session_on_response_headers_received(nghttp2_session *session, 607 nghttp2_frame *frame, 608 nghttp2_stream *stream); 609 610 int nghttp2_session_on_push_response_headers_received(nghttp2_session *session, 611 nghttp2_frame *frame, 612 nghttp2_stream *stream); 613 614 /* 615 * Called when HEADERS is received, assuming |frame| is properly 616 * initialized. This function does first validate received frame and 617 * then open stream and call callback functions. 618 * 619 * This function returns 0 if it succeeds, or one of the following 620 * negative error codes: 621 * 622 * NGHTTP2_ERR_NOMEM 623 * Out of memory. 624 * NGHTTP2_ERR_IGN_HEADER_BLOCK 625 * Frame was rejected and header block must be decoded but 626 * result must be ignored. 627 * NGHTTP2_ERR_CALLBACK_FAILURE 628 * The read_callback failed 629 */ 630 int nghttp2_session_on_headers_received(nghttp2_session *session, 631 nghttp2_frame *frame, 632 nghttp2_stream *stream); 633 634 /* 635 * Called when PRIORITY is received, assuming |frame| is properly 636 * initialized. 637 * 638 * This function returns 0 if it succeeds, or one of the following 639 * negative error codes: 640 * 641 * NGHTTP2_ERR_NOMEM 642 * Out of memory. 643 * NGHTTP2_ERR_CALLBACK_FAILURE 644 * The read_callback failed 645 */ 646 int nghttp2_session_on_priority_received(nghttp2_session *session, 647 nghttp2_frame *frame); 648 649 /* 650 * Called when RST_STREAM is received, assuming |frame| is properly 651 * initialized. 652 * 653 * This function returns 0 if it succeeds, or one the following 654 * negative error codes: 655 * 656 * NGHTTP2_ERR_NOMEM 657 * Out of memory 658 * NGHTTP2_ERR_CALLBACK_FAILURE 659 * The read_callback failed 660 */ 661 int nghttp2_session_on_rst_stream_received(nghttp2_session *session, 662 nghttp2_frame *frame); 663 664 /* 665 * Called when SETTINGS is received, assuming |frame| is properly 666 * initialized. If |noack| is non-zero, SETTINGS with ACK will not be 667 * submitted. If |frame| has NGHTTP2_FLAG_ACK flag set, no SETTINGS 668 * with ACK will not be submitted regardless of |noack|. 669 * 670 * This function returns 0 if it succeeds, or one the following 671 * negative error codes: 672 * 673 * NGHTTP2_ERR_NOMEM 674 * Out of memory 675 * NGHTTP2_ERR_CALLBACK_FAILURE 676 * The read_callback failed 677 * NGHTTP2_ERR_FLOODED 678 * There are too many items in outbound queue, and this is most 679 * likely caused by misbehaviour of peer. 680 */ 681 int nghttp2_session_on_settings_received(nghttp2_session *session, 682 nghttp2_frame *frame, int noack); 683 684 /* 685 * Called when PUSH_PROMISE is received, assuming |frame| is properly 686 * initialized. 687 * 688 * This function returns 0 if it succeeds, or one of the following 689 * negative error codes: 690 * 691 * NGHTTP2_ERR_NOMEM 692 * Out of memory. 693 * NGHTTP2_ERR_IGN_HEADER_BLOCK 694 * Frame was rejected and header block must be decoded but 695 * result must be ignored. 696 * NGHTTP2_ERR_CALLBACK_FAILURE 697 * The read_callback failed 698 */ 699 int nghttp2_session_on_push_promise_received(nghttp2_session *session, 700 nghttp2_frame *frame); 701 702 /* 703 * Called when PING is received, assuming |frame| is properly 704 * initialized. 705 * 706 * This function returns 0 if it succeeds, or one of the following 707 * negative error codes: 708 * 709 * NGHTTP2_ERR_NOMEM 710 * Out of memory. 711 * NGHTTP2_ERR_CALLBACK_FAILURE 712 * The callback function failed. 713 * NGHTTP2_ERR_FLOODED 714 * There are too many items in outbound queue, and this is most 715 * likely caused by misbehaviour of peer. 716 */ 717 int nghttp2_session_on_ping_received(nghttp2_session *session, 718 nghttp2_frame *frame); 719 720 /* 721 * Called when GOAWAY is received, assuming |frame| is properly 722 * initialized. 723 * 724 * This function returns 0 if it succeeds, or one of the following 725 * negative error codes: 726 * 727 * NGHTTP2_ERR_NOMEM 728 * Out of memory. 729 * NGHTTP2_ERR_CALLBACK_FAILURE 730 * The callback function failed. 731 */ 732 int nghttp2_session_on_goaway_received(nghttp2_session *session, 733 nghttp2_frame *frame); 734 735 /* 736 * Called when WINDOW_UPDATE is received, assuming |frame| is properly 737 * initialized. 738 * 739 * This function returns 0 if it succeeds, or one of the following 740 * negative error codes: 741 * 742 * NGHTTP2_ERR_NOMEM 743 * Out of memory. 744 * NGHTTP2_ERR_CALLBACK_FAILURE 745 * The callback function failed. 746 */ 747 int nghttp2_session_on_window_update_received(nghttp2_session *session, 748 nghttp2_frame *frame); 749 750 /* 751 * Called when ALTSVC is received, assuming |frame| is properly 752 * initialized. 753 * 754 * This function returns 0 if it succeeds, or one of the following 755 * negative error codes: 756 * 757 * NGHTTP2_ERR_CALLBACK_FAILURE 758 * The callback function failed. 759 */ 760 int nghttp2_session_on_altsvc_received(nghttp2_session *session, 761 nghttp2_frame *frame); 762 763 /* 764 * Called when ORIGIN is received, assuming |frame| is properly 765 * initialized. 766 * 767 * This function returns 0 if it succeeds, or one of the following 768 * negative error codes: 769 * 770 * NGHTTP2_ERR_CALLBACK_FAILURE 771 * The callback function failed. 772 */ 773 int nghttp2_session_on_origin_received(nghttp2_session *session, 774 nghttp2_frame *frame); 775 776 /* 777 * Called when DATA is received, assuming |frame| is properly 778 * initialized. 779 * 780 * This function returns 0 if it succeeds, or one of the following 781 * negative error codes: 782 * 783 * NGHTTP2_ERR_NOMEM 784 * Out of memory. 785 * NGHTTP2_ERR_CALLBACK_FAILURE 786 * The callback function failed. 787 */ 788 int nghttp2_session_on_data_received(nghttp2_session *session, 789 nghttp2_frame *frame); 790 791 /* 792 * Returns nghttp2_stream* object whose stream ID is |stream_id|. It 793 * could be NULL if such stream does not exist. This function returns 794 * NULL if stream is marked as closed. 795 */ 796 nghttp2_stream *nghttp2_session_get_stream(nghttp2_session *session, 797 int32_t stream_id); 798 799 /* 800 * This function behaves like nghttp2_session_get_stream(), but it 801 * returns stream object even if it is marked as closed or in 802 * NGHTTP2_STREAM_IDLE state. 803 */ 804 nghttp2_stream *nghttp2_session_get_stream_raw(nghttp2_session *session, 805 int32_t stream_id); 806 807 /* 808 * Packs DATA frame |frame| in wire frame format and stores it in 809 * |bufs|. Payload will be read using |aux_data->data_prd|. The 810 * length of payload is at most |datamax| bytes. 811 * 812 * This function returns 0 if it succeeds, or one of the following 813 * negative error codes: 814 * 815 * NGHTTP2_ERR_DEFERRED 816 * The DATA frame is postponed. 817 * NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE 818 * The read_callback failed (stream error). 819 * NGHTTP2_ERR_NOMEM 820 * Out of memory. 821 * NGHTTP2_ERR_CALLBACK_FAILURE 822 * The read_callback failed (session error). 823 */ 824 int nghttp2_session_pack_data(nghttp2_session *session, nghttp2_bufs *bufs, 825 size_t datamax, nghttp2_frame *frame, 826 nghttp2_data_aux_data *aux_data, 827 nghttp2_stream *stream); 828 829 /* 830 * Pops and returns next item to send. If there is no such item, 831 * returns NULL. This function takes into account max concurrent 832 * streams. That means if session->ob_syn has item and max concurrent 833 * streams is reached, the even if other queues contain items, then 834 * this function returns NULL. 835 */ 836 nghttp2_outbound_item * 837 nghttp2_session_pop_next_ob_item(nghttp2_session *session); 838 839 /* 840 * Returns next item to send. If there is no such item, this function 841 * returns NULL. This function takes into account max concurrent 842 * streams. That means if session->ob_syn has item and max concurrent 843 * streams is reached, the even if other queues contain items, then 844 * this function returns NULL. 845 */ 846 nghttp2_outbound_item * 847 nghttp2_session_get_next_ob_item(nghttp2_session *session); 848 849 /* 850 * Updates local settings with the |iv|. The number of elements in the 851 * array pointed by the |iv| is given by the |niv|. This function 852 * assumes that the all settings_id member in |iv| are in range 1 to 853 * NGHTTP2_SETTINGS_MAX, inclusive. 854 * 855 * While updating individual stream's local window size, if the window 856 * size becomes strictly larger than NGHTTP2_MAX_WINDOW_SIZE, 857 * RST_STREAM is issued against such a stream. 858 * 859 * This function returns 0 if it succeeds, or one of the following 860 * negative error codes: 861 * 862 * NGHTTP2_ERR_NOMEM 863 * Out of memory 864 */ 865 int nghttp2_session_update_local_settings(nghttp2_session *session, 866 nghttp2_settings_entry *iv, 867 size_t niv); 868 869 /* 870 * Re-prioritize |stream|. The new priority specification is 871 * |pri_spec|. Caller must ensure that stream->hd.stream_id != 872 * pri_spec->stream_id. 873 * 874 * This function does not adjust the number of idle streams. The 875 * caller should call nghttp2_session_adjust_idle_stream() later. 876 * 877 * This function returns 0 if it succeeds, or one of the following 878 * negative error codes: 879 * 880 * NGHTTP2_ERR_NOMEM 881 * Out of memory 882 */ 883 int nghttp2_session_reprioritize_stream(nghttp2_session *session, 884 nghttp2_stream *stream, 885 const nghttp2_priority_spec *pri_spec); 886 887 /* 888 * Terminates current |session| with the |error_code|. The |reason| 889 * is NULL-terminated debug string. 890 * 891 * This function returns 0 if it succeeds, or one of the following 892 * negative error codes: 893 * 894 * NGHTTP2_ERR_NOMEM 895 * Out of memory. 896 * NGHTTP2_ERR_INVALID_ARGUMENT 897 * The |reason| is too long. 898 */ 899 int nghttp2_session_terminate_session_with_reason(nghttp2_session *session, 900 uint32_t error_code, 901 const char *reason); 902 903 /* 904 * Accumulates received bytes |delta_size| for connection-level flow 905 * control and decides whether to send WINDOW_UPDATE to the 906 * connection. If NGHTTP2_OPT_NO_AUTO_WINDOW_UPDATE is set, 907 * WINDOW_UPDATE will not be sent. 908 * 909 * This function returns 0 if it succeeds, or one of the following 910 * negative error codes: 911 * 912 * NGHTTP2_ERR_NOMEM 913 * Out of memory. 914 */ 915 int nghttp2_session_update_recv_connection_window_size(nghttp2_session *session, 916 size_t delta_size); 917 918 /* 919 * Accumulates received bytes |delta_size| for stream-level flow 920 * control and decides whether to send WINDOW_UPDATE to that stream. 921 * If NGHTTP2_OPT_NO_AUTO_WINDOW_UPDATE is set, WINDOW_UPDATE will not 922 * be sent. 923 * 924 * This function returns 0 if it succeeds, or one of the following 925 * negative error codes: 926 * 927 * NGHTTP2_ERR_NOMEM 928 * Out of memory. 929 */ 930 int nghttp2_session_update_recv_stream_window_size(nghttp2_session *session, 931 nghttp2_stream *stream, 932 size_t delta_size, 933 int send_window_update); 934 935 #endif /* NGHTTP2_SESSION_H */ 936