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