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 /* Next Stream ID. Made unsigned int to detect >= (1 << 31). */ 271 uint32_t next_stream_id; 272 /* The last stream ID this session initiated. For client session, 273 this is the last stream ID it has sent. For server session, it 274 is the last promised stream ID sent in PUSH_PROMISE. */ 275 int32_t last_sent_stream_id; 276 /* The largest stream ID received so far */ 277 int32_t last_recv_stream_id; 278 /* The largest stream ID which has been processed in some way. This 279 value will be used as last-stream-id when sending GOAWAY 280 frame. */ 281 int32_t last_proc_stream_id; 282 /* Counter of unique ID of PING. Wraps when it exceeds 283 NGHTTP2_MAX_UNIQUE_ID */ 284 uint32_t next_unique_id; 285 /* This is the last-stream-ID we have sent in GOAWAY */ 286 int32_t local_last_stream_id; 287 /* This is the value in GOAWAY frame received from remote endpoint. */ 288 int32_t remote_last_stream_id; 289 /* Current sender window size. This value is computed against the 290 current initial window size of remote endpoint. */ 291 int32_t remote_window_size; 292 /* Keep track of the number of bytes received without 293 WINDOW_UPDATE. This could be negative after submitting negative 294 value to WINDOW_UPDATE. */ 295 int32_t recv_window_size; 296 /* The number of bytes consumed by the application and now is 297 subject to WINDOW_UPDATE. This is only used when auto 298 WINDOW_UPDATE is turned off. */ 299 int32_t consumed_size; 300 /* The amount of recv_window_size cut using submitting negative 301 value to WINDOW_UPDATE */ 302 int32_t recv_reduction; 303 /* window size for local flow control. It is initially set to 304 NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE and could be 305 increased/decreased by submitting WINDOW_UPDATE. See 306 nghttp2_submit_window_update(). */ 307 int32_t local_window_size; 308 /* This flag is used to indicate that the local endpoint received initial 309 SETTINGS frame from the remote endpoint. */ 310 uint8_t remote_settings_received; 311 /* Settings value received from the remote endpoint. */ 312 nghttp2_settings_storage remote_settings; 313 /* Settings value of the local endpoint. */ 314 nghttp2_settings_storage local_settings; 315 /* Option flags. This is bitwise-OR of 0 or more of nghttp2_optmask. */ 316 uint32_t opt_flags; 317 /* Unacked local SETTINGS_MAX_CONCURRENT_STREAMS value. We use this 318 to refuse the incoming stream if it exceeds this value. */ 319 uint32_t pending_local_max_concurrent_stream; 320 /* The bitwise OR of zero or more of nghttp2_typemask to indicate 321 that the default handling of extension frame is enabled. */ 322 uint32_t builtin_recv_ext_types; 323 /* Unacked local ENABLE_PUSH value. We use this to refuse 324 PUSH_PROMISE before SETTINGS ACK is received. */ 325 uint8_t pending_enable_push; 326 /* Unacked local ENABLE_CONNECT_PROTOCOL value. We use this to 327 accept :protocol header field before SETTINGS_ACK is received. */ 328 uint8_t pending_enable_connect_protocol; 329 /* Nonzero if the session is server side. */ 330 uint8_t server; 331 /* Flags indicating GOAWAY is sent and/or received. The flags are 332 composed by bitwise OR-ing nghttp2_goaway_flag. */ 333 uint8_t goaway_flags; 334 /* This flag is used to reduce excessive queuing of WINDOW_UPDATE to 335 this session. The nonzero does not necessarily mean 336 WINDOW_UPDATE is not queued. */ 337 uint8_t window_update_queued; 338 /* Bitfield of extension frame types that application is willing to 339 receive. To designate the bit of given frame type i, use 340 user_recv_ext_types[i / 8] & (1 << (i & 0x7)). First 10 frame 341 types are standard frame types and not used in this bitfield. If 342 bit is set, it indicates that incoming frame with that type is 343 passed to user defined callbacks, otherwise they are ignored. */ 344 uint8_t user_recv_ext_types[32]; 345 }; 346 347 /* Struct used when updating initial window size of each active 348 stream. */ 349 typedef struct { 350 nghttp2_session *session; 351 int32_t new_window_size, old_window_size; 352 } nghttp2_update_window_size_arg; 353 354 typedef struct { 355 nghttp2_session *session; 356 /* linked list of streams to close */ 357 nghttp2_stream *head; 358 int32_t last_stream_id; 359 /* nonzero if GOAWAY is sent to peer, which means we are going to 360 close incoming streams. zero if GOAWAY is received from peer and 361 we are going to close outgoing streams. */ 362 int incoming; 363 } nghttp2_close_stream_on_goaway_arg; 364 365 /* TODO stream timeout etc */ 366 367 /* 368 * Returns nonzero value if |stream_id| is initiated by local 369 * endpoint. 370 */ 371 int nghttp2_session_is_my_stream_id(nghttp2_session *session, 372 int32_t stream_id); 373 374 /* 375 * Adds |item| to the outbound queue in |session|. When this function 376 * succeeds, it takes ownership of |item|. So caller must not free it 377 * on success. 378 * 379 * This function returns 0 if it succeeds, or one of the following 380 * negative error codes: 381 * 382 * NGHTTP2_ERR_NOMEM 383 * Out of memory. 384 * NGHTTP2_ERR_STREAM_CLOSED 385 * Stream already closed (DATA and PUSH_PROMISE frame only) 386 */ 387 int nghttp2_session_add_item(nghttp2_session *session, 388 nghttp2_outbound_item *item); 389 390 /* 391 * Adds RST_STREAM frame for the stream |stream_id| with the error 392 * code |error_code|. This is a convenient function built on top of 393 * nghttp2_session_add_frame() to add RST_STREAM easily. 394 * 395 * This function simply returns 0 without adding RST_STREAM frame if 396 * given stream is in NGHTTP2_STREAM_CLOSING state, because multiple 397 * RST_STREAM for a stream is redundant. 398 * 399 * This function returns 0 if it succeeds, or one of the following 400 * negative error codes: 401 * 402 * NGHTTP2_ERR_NOMEM 403 * Out of memory. 404 */ 405 int nghttp2_session_add_rst_stream(nghttp2_session *session, int32_t stream_id, 406 uint32_t error_code); 407 408 /* 409 * Adds PING frame. This is a convenient functin built on top of 410 * nghttp2_session_add_frame() to add PING easily. 411 * 412 * If the |opaque_data| is not NULL, it must point to 8 bytes memory 413 * region of data. The data pointed by |opaque_data| is copied. It can 414 * be NULL. In this case, 8 bytes NULL is used. 415 * 416 * This function returns 0 if it succeeds, or one of the following 417 * negative error codes: 418 * 419 * NGHTTP2_ERR_NOMEM 420 * Out of memory. 421 * NGHTTP2_ERR_FLOODED 422 * There are too many items in outbound queue; this only happens 423 * if NGHTTP2_FLAG_ACK is set in |flags| 424 */ 425 int nghttp2_session_add_ping(nghttp2_session *session, uint8_t flags, 426 const uint8_t *opaque_data); 427 428 /* 429 * Adds GOAWAY frame with the last-stream-ID |last_stream_id| and the 430 * error code |error_code|. This is a convenient function built on top 431 * of nghttp2_session_add_frame() to add GOAWAY easily. The 432 * |aux_flags| are bitwise-OR of one or more of 433 * nghttp2_goaway_aux_flag. 434 * 435 * This function returns 0 if it succeeds, or one of the following 436 * negative error codes: 437 * 438 * NGHTTP2_ERR_NOMEM 439 * Out of memory. 440 * NGHTTP2_ERR_INVALID_ARGUMENT 441 * The |opaque_data_len| is too large. 442 */ 443 int nghttp2_session_add_goaway(nghttp2_session *session, int32_t last_stream_id, 444 uint32_t error_code, const uint8_t *opaque_data, 445 size_t opaque_data_len, uint8_t aux_flags); 446 447 /* 448 * Adds WINDOW_UPDATE frame with stream ID |stream_id| and 449 * window-size-increment |window_size_increment|. This is a convenient 450 * function built on top of nghttp2_session_add_frame() to add 451 * WINDOW_UPDATE easily. 452 * 453 * This function returns 0 if it succeeds, or one of the following 454 * negative error codes: 455 * 456 * NGHTTP2_ERR_NOMEM 457 * Out of memory. 458 */ 459 int nghttp2_session_add_window_update(nghttp2_session *session, uint8_t flags, 460 int32_t stream_id, 461 int32_t window_size_increment); 462 463 /* 464 * Adds SETTINGS frame. 465 * 466 * This function returns 0 if it succeeds, or one of the following 467 * negative error codes: 468 * 469 * NGHTTP2_ERR_NOMEM 470 * Out of memory. 471 * NGHTTP2_ERR_FLOODED 472 * There are too many items in outbound queue; this only happens 473 * if NGHTTP2_FLAG_ACK is set in |flags| 474 */ 475 int nghttp2_session_add_settings(nghttp2_session *session, uint8_t flags, 476 const nghttp2_settings_entry *iv, size_t niv); 477 478 /* 479 * Creates new stream in |session| with stream ID |stream_id|, 480 * priority |pri_spec| and flags |flags|. The |flags| is bitwise OR 481 * of nghttp2_stream_flag. Since this function is called when initial 482 * HEADERS is sent or received, these flags are taken from it. The 483 * state of stream is set to |initial_state|. The |stream_user_data| 484 * is a pointer to the arbitrary user supplied data to be associated 485 * to this stream. 486 * 487 * If |initial_state| is NGHTTP2_STREAM_RESERVED, this function sets 488 * NGHTTP2_STREAM_FLAG_PUSH flag set. 489 * 490 * This function returns a pointer to created new stream object, or 491 * NULL. 492 * 493 * This function adjusts neither the number of closed streams or idle 494 * streams. The caller should manually call 495 * nghttp2_session_adjust_closed_stream() or 496 * nghttp2_session_adjust_idle_stream() respectively. 497 */ 498 nghttp2_stream *nghttp2_session_open_stream(nghttp2_session *session, 499 int32_t stream_id, uint8_t flags, 500 nghttp2_priority_spec *pri_spec, 501 nghttp2_stream_state initial_state, 502 void *stream_user_data); 503 504 /* 505 * Closes stream whose stream ID is |stream_id|. The reason of closure 506 * is indicated by the |error_code|. When closing the stream, 507 * on_stream_close_callback will be called. 508 * 509 * If the session is initialized as server and |stream| is incoming 510 * stream, stream is just marked closed and this function calls 511 * nghttp2_session_keep_closed_stream() with |stream|. Otherwise, 512 * |stream| will be deleted from memory. 513 * 514 * This function returns 0 if it succeeds, or one the following 515 * negative error codes: 516 * 517 * NGHTTP2_ERR_NOMEM 518 * Out of memory 519 * NGHTTP2_ERR_INVALID_ARGUMENT 520 * The specified stream does not exist. 521 * NGHTTP2_ERR_CALLBACK_FAILURE 522 * The callback function failed. 523 */ 524 int nghttp2_session_close_stream(nghttp2_session *session, int32_t stream_id, 525 uint32_t error_code); 526 527 /* 528 * Deletes |stream| from memory. After this function returns, stream 529 * cannot be accessed. 530 * 531 * This function returns 0 if it succeeds, or one the following 532 * negative error codes: 533 * 534 * NGHTTP2_ERR_NOMEM 535 * Out of memory 536 */ 537 int nghttp2_session_destroy_stream(nghttp2_session *session, 538 nghttp2_stream *stream); 539 540 /* 541 * Tries to keep incoming closed stream |stream|. Due to the 542 * limitation of maximum number of streams in memory, |stream| is not 543 * closed and just deleted from memory (see 544 * nghttp2_session_destroy_stream). 545 */ 546 void nghttp2_session_keep_closed_stream(nghttp2_session *session, 547 nghttp2_stream *stream); 548 549 /* 550 * Appends |stream| to linked list |session->idle_stream_head|. We 551 * apply fixed limit for list size. To fit into that limit, one or 552 * more oldest streams are removed from list as necessary. 553 */ 554 void nghttp2_session_keep_idle_stream(nghttp2_session *session, 555 nghttp2_stream *stream); 556 557 /* 558 * Detaches |stream| from idle streams linked list. 559 */ 560 void nghttp2_session_detach_idle_stream(nghttp2_session *session, 561 nghttp2_stream *stream); 562 563 /* 564 * Deletes closed stream to ensure that number of incoming streams 565 * including active and closed is in the maximum number of allowed 566 * stream. 567 * 568 * This function returns 0 if it succeeds, or one the following 569 * negative error codes: 570 * 571 * NGHTTP2_ERR_NOMEM 572 * Out of memory 573 */ 574 int nghttp2_session_adjust_closed_stream(nghttp2_session *session); 575 576 /* 577 * Deletes idle stream to ensure that number of idle streams is in 578 * certain limit. 579 * 580 * This function returns 0 if it succeeds, or one the following 581 * negative error codes: 582 * 583 * NGHTTP2_ERR_NOMEM 584 * Out of memory 585 */ 586 int nghttp2_session_adjust_idle_stream(nghttp2_session *session); 587 588 /* 589 * If further receptions and transmissions over the stream |stream_id| 590 * are disallowed, close the stream with error code NGHTTP2_NO_ERROR. 591 * 592 * This function returns 0 if it 593 * succeeds, or one of the following negative error codes: 594 * 595 * NGHTTP2_ERR_INVALID_ARGUMENT 596 * The specified stream does not exist. 597 */ 598 int nghttp2_session_close_stream_if_shut_rdwr(nghttp2_session *session, 599 nghttp2_stream *stream); 600 601 int nghttp2_session_on_request_headers_received(nghttp2_session *session, 602 nghttp2_frame *frame); 603 604 int nghttp2_session_on_response_headers_received(nghttp2_session *session, 605 nghttp2_frame *frame, 606 nghttp2_stream *stream); 607 608 int nghttp2_session_on_push_response_headers_received(nghttp2_session *session, 609 nghttp2_frame *frame, 610 nghttp2_stream *stream); 611 612 /* 613 * Called when HEADERS is received, assuming |frame| is properly 614 * initialized. This function does first validate received frame and 615 * then open stream and call callback functions. 616 * 617 * This function returns 0 if it succeeds, or one of the following 618 * negative error codes: 619 * 620 * NGHTTP2_ERR_NOMEM 621 * Out of memory. 622 * NGHTTP2_ERR_IGN_HEADER_BLOCK 623 * Frame was rejected and header block must be decoded but 624 * result must be ignored. 625 * NGHTTP2_ERR_CALLBACK_FAILURE 626 * The read_callback failed 627 */ 628 int nghttp2_session_on_headers_received(nghttp2_session *session, 629 nghttp2_frame *frame, 630 nghttp2_stream *stream); 631 632 /* 633 * Called when PRIORITY is received, assuming |frame| is properly 634 * initialized. 635 * 636 * This function returns 0 if it succeeds, or one of the following 637 * negative error codes: 638 * 639 * NGHTTP2_ERR_NOMEM 640 * Out of memory. 641 * NGHTTP2_ERR_CALLBACK_FAILURE 642 * The read_callback failed 643 */ 644 int nghttp2_session_on_priority_received(nghttp2_session *session, 645 nghttp2_frame *frame); 646 647 /* 648 * Called when RST_STREAM is received, assuming |frame| is properly 649 * initialized. 650 * 651 * This function returns 0 if it succeeds, or one the following 652 * negative error codes: 653 * 654 * NGHTTP2_ERR_NOMEM 655 * Out of memory 656 * NGHTTP2_ERR_CALLBACK_FAILURE 657 * The read_callback failed 658 */ 659 int nghttp2_session_on_rst_stream_received(nghttp2_session *session, 660 nghttp2_frame *frame); 661 662 /* 663 * Called when SETTINGS is received, assuming |frame| is properly 664 * initialized. If |noack| is non-zero, SETTINGS with ACK will not be 665 * submitted. If |frame| has NGHTTP2_FLAG_ACK flag set, no SETTINGS 666 * with ACK will not be submitted regardless of |noack|. 667 * 668 * This function returns 0 if it succeeds, or one the following 669 * negative error codes: 670 * 671 * NGHTTP2_ERR_NOMEM 672 * Out of memory 673 * NGHTTP2_ERR_CALLBACK_FAILURE 674 * The read_callback failed 675 * NGHTTP2_ERR_FLOODED 676 * There are too many items in outbound queue, and this is most 677 * likely caused by misbehaviour of peer. 678 */ 679 int nghttp2_session_on_settings_received(nghttp2_session *session, 680 nghttp2_frame *frame, int noack); 681 682 /* 683 * Called when PUSH_PROMISE is received, assuming |frame| is properly 684 * initialized. 685 * 686 * This function returns 0 if it succeeds, or one of the following 687 * negative error codes: 688 * 689 * NGHTTP2_ERR_NOMEM 690 * Out of memory. 691 * NGHTTP2_ERR_IGN_HEADER_BLOCK 692 * Frame was rejected and header block must be decoded but 693 * result must be ignored. 694 * NGHTTP2_ERR_CALLBACK_FAILURE 695 * The read_callback failed 696 */ 697 int nghttp2_session_on_push_promise_received(nghttp2_session *session, 698 nghttp2_frame *frame); 699 700 /* 701 * Called when PING is received, assuming |frame| is properly 702 * initialized. 703 * 704 * This function returns 0 if it succeeds, or one of the following 705 * negative error codes: 706 * 707 * NGHTTP2_ERR_NOMEM 708 * Out of memory. 709 * NGHTTP2_ERR_CALLBACK_FAILURE 710 * The callback function failed. 711 * NGHTTP2_ERR_FLOODED 712 * There are too many items in outbound queue, and this is most 713 * likely caused by misbehaviour of peer. 714 */ 715 int nghttp2_session_on_ping_received(nghttp2_session *session, 716 nghttp2_frame *frame); 717 718 /* 719 * Called when GOAWAY is received, assuming |frame| is properly 720 * initialized. 721 * 722 * This function returns 0 if it succeeds, or one of the following 723 * negative error codes: 724 * 725 * NGHTTP2_ERR_NOMEM 726 * Out of memory. 727 * NGHTTP2_ERR_CALLBACK_FAILURE 728 * The callback function failed. 729 */ 730 int nghttp2_session_on_goaway_received(nghttp2_session *session, 731 nghttp2_frame *frame); 732 733 /* 734 * Called when WINDOW_UPDATE is received, assuming |frame| is properly 735 * initialized. 736 * 737 * This function returns 0 if it succeeds, or one of the following 738 * negative error codes: 739 * 740 * NGHTTP2_ERR_NOMEM 741 * Out of memory. 742 * NGHTTP2_ERR_CALLBACK_FAILURE 743 * The callback function failed. 744 */ 745 int nghttp2_session_on_window_update_received(nghttp2_session *session, 746 nghttp2_frame *frame); 747 748 /* 749 * Called when ALTSVC is received, assuming |frame| is properly 750 * initialized. 751 * 752 * This function returns 0 if it succeeds, or one of the following 753 * negative error codes: 754 * 755 * NGHTTP2_ERR_CALLBACK_FAILURE 756 * The callback function failed. 757 */ 758 int nghttp2_session_on_altsvc_received(nghttp2_session *session, 759 nghttp2_frame *frame); 760 761 /* 762 * Called when ORIGIN is received, assuming |frame| is properly 763 * initialized. 764 * 765 * This function returns 0 if it succeeds, or one of the following 766 * negative error codes: 767 * 768 * NGHTTP2_ERR_CALLBACK_FAILURE 769 * The callback function failed. 770 */ 771 int nghttp2_session_on_origin_received(nghttp2_session *session, 772 nghttp2_frame *frame); 773 774 /* 775 * Called when DATA is received, assuming |frame| is properly 776 * initialized. 777 * 778 * This function returns 0 if it succeeds, or one of the following 779 * negative error codes: 780 * 781 * NGHTTP2_ERR_NOMEM 782 * Out of memory. 783 * NGHTTP2_ERR_CALLBACK_FAILURE 784 * The callback function failed. 785 */ 786 int nghttp2_session_on_data_received(nghttp2_session *session, 787 nghttp2_frame *frame); 788 789 /* 790 * Returns nghttp2_stream* object whose stream ID is |stream_id|. It 791 * could be NULL if such stream does not exist. This function returns 792 * NULL if stream is marked as closed. 793 */ 794 nghttp2_stream *nghttp2_session_get_stream(nghttp2_session *session, 795 int32_t stream_id); 796 797 /* 798 * This function behaves like nghttp2_session_get_stream(), but it 799 * returns stream object even if it is marked as closed or in 800 * NGHTTP2_STREAM_IDLE state. 801 */ 802 nghttp2_stream *nghttp2_session_get_stream_raw(nghttp2_session *session, 803 int32_t stream_id); 804 805 /* 806 * Packs DATA frame |frame| in wire frame format and stores it in 807 * |bufs|. Payload will be read using |aux_data->data_prd|. The 808 * length of payload is at most |datamax| bytes. 809 * 810 * This function returns 0 if it succeeds, or one of the following 811 * negative error codes: 812 * 813 * NGHTTP2_ERR_DEFERRED 814 * The DATA frame is postponed. 815 * NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE 816 * The read_callback failed (stream error). 817 * NGHTTP2_ERR_NOMEM 818 * Out of memory. 819 * NGHTTP2_ERR_CALLBACK_FAILURE 820 * The read_callback failed (session error). 821 */ 822 int nghttp2_session_pack_data(nghttp2_session *session, nghttp2_bufs *bufs, 823 size_t datamax, nghttp2_frame *frame, 824 nghttp2_data_aux_data *aux_data, 825 nghttp2_stream *stream); 826 827 /* 828 * Pops and returns next item to send. If there is no such item, 829 * returns NULL. This function takes into account max concurrent 830 * streams. That means if session->ob_syn has item and max concurrent 831 * streams is reached, the even if other queues contain items, then 832 * this function returns NULL. 833 */ 834 nghttp2_outbound_item * 835 nghttp2_session_pop_next_ob_item(nghttp2_session *session); 836 837 /* 838 * Returns next item to send. If there is no such item, this function 839 * returns NULL. This function takes into account max concurrent 840 * streams. That means if session->ob_syn has item and max concurrent 841 * streams is reached, the even if other queues contain items, then 842 * this function returns NULL. 843 */ 844 nghttp2_outbound_item * 845 nghttp2_session_get_next_ob_item(nghttp2_session *session); 846 847 /* 848 * Updates local settings with the |iv|. The number of elements in the 849 * array pointed by the |iv| is given by the |niv|. This function 850 * assumes that the all settings_id member in |iv| are in range 1 to 851 * NGHTTP2_SETTINGS_MAX, inclusive. 852 * 853 * While updating individual stream's local window size, if the window 854 * size becomes strictly larger than NGHTTP2_MAX_WINDOW_SIZE, 855 * RST_STREAM is issued against such a stream. 856 * 857 * This function returns 0 if it succeeds, or one of the following 858 * negative error codes: 859 * 860 * NGHTTP2_ERR_NOMEM 861 * Out of memory 862 */ 863 int nghttp2_session_update_local_settings(nghttp2_session *session, 864 nghttp2_settings_entry *iv, 865 size_t niv); 866 867 /* 868 * Re-prioritize |stream|. The new priority specification is 869 * |pri_spec|. Caller must ensure that stream->hd.stream_id != 870 * pri_spec->stream_id. 871 * 872 * This function does not adjust the number of idle streams. The 873 * caller should call nghttp2_session_adjust_idle_stream() later. 874 * 875 * This function returns 0 if it succeeds, or one of the following 876 * negative error codes: 877 * 878 * NGHTTP2_ERR_NOMEM 879 * Out of memory 880 */ 881 int nghttp2_session_reprioritize_stream(nghttp2_session *session, 882 nghttp2_stream *stream, 883 const nghttp2_priority_spec *pri_spec); 884 885 /* 886 * Terminates current |session| with the |error_code|. The |reason| 887 * is NULL-terminated debug string. 888 * 889 * This function returns 0 if it succeeds, or one of the following 890 * negative error codes: 891 * 892 * NGHTTP2_ERR_NOMEM 893 * Out of memory. 894 * NGHTTP2_ERR_INVALID_ARGUMENT 895 * The |reason| is too long. 896 */ 897 int nghttp2_session_terminate_session_with_reason(nghttp2_session *session, 898 uint32_t error_code, 899 const char *reason); 900 901 #endif /* NGHTTP2_SESSION_H */ 902