lib/nghttp2_stream.h

   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_STREAM_H
  26 #define NGHTTP2_STREAM_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_outbound_item.h"
  34 #include "nghttp2_map.h"
  35 #include "nghttp2_pq.h"
  36 #include "nghttp2_int.h"
  37
  38 /*
  39  * Maximum number of streams in one dependency tree.
  40  */
  41 #define NGHTTP2_MAX_DEP_TREE_LENGTH 100
  42
  43 /*
  44  * If local peer is stream initiator:
  45  * NGHTTP2_STREAM_OPENING : upon sending request HEADERS
  46  * NGHTTP2_STREAM_OPENED : upon receiving response HEADERS
  47  * NGHTTP2_STREAM_CLOSING : upon queuing RST_STREAM
  48  *
  49  * If remote peer is stream initiator:
  50  * NGHTTP2_STREAM_OPENING : upon receiving request HEADERS
  51  * NGHTTP2_STREAM_OPENED : upon sending response HEADERS
  52  * NGHTTP2_STREAM_CLOSING : upon queuing RST_STREAM
  53  */
  54 typedef enum {
  55   /* Initial state */
  56   NGHTTP2_STREAM_INITIAL,
  57   /* For stream initiator: request HEADERS has been sent, but response
  58      HEADERS has not been received yet.  For receiver: request HEADERS
  59      has been received, but it does not send response HEADERS yet. */
  60   NGHTTP2_STREAM_OPENING,
  61   /* For stream initiator: response HEADERS is received. For receiver:
  62      response HEADERS is sent. */
  63   NGHTTP2_STREAM_OPENED,
  64   /* RST_STREAM is received, but somehow we need to keep stream in
  65      memory. */
  66   NGHTTP2_STREAM_CLOSING,
  67   /* PUSH_PROMISE is received or sent */
  68   NGHTTP2_STREAM_RESERVED,
  69   /* Stream is created in this state if it is used as anchor in
  70      dependency tree. */
  71   NGHTTP2_STREAM_IDLE
  72 } nghttp2_stream_state;
  73
  74 typedef enum {
  75   NGHTTP2_SHUT_NONE = 0,
  76   /* Indicates further receptions will be disallowed. */
  77   NGHTTP2_SHUT_RD = 0x01,
  78   /* Indicates further transmissions will be disallowed. */
  79   NGHTTP2_SHUT_WR = 0x02,
  80   /* Indicates both further receptions and transmissions will be
  81      disallowed. */
  82   NGHTTP2_SHUT_RDWR = NGHTTP2_SHUT_RD | NGHTTP2_SHUT_WR
  83 } nghttp2_shut_flag;
  84
  85 typedef enum {
  86   NGHTTP2_STREAM_FLAG_NONE = 0,
  87   /* Indicates that this stream is pushed stream and not opened
  88      yet. */
  89   NGHTTP2_STREAM_FLAG_PUSH = 0x01,
  90   /* Indicates that this stream was closed */
  91   NGHTTP2_STREAM_FLAG_CLOSED = 0x02,
  92   /* Indicates the item is deferred due to flow control. */
  93   NGHTTP2_STREAM_FLAG_DEFERRED_FLOW_CONTROL = 0x04,
  94   /* Indicates the item is deferred by user callback */
  95   NGHTTP2_STREAM_FLAG_DEFERRED_USER = 0x08,
  96   /* bitwise OR of NGHTTP2_STREAM_FLAG_DEFERRED_FLOW_CONTROL and
  97      NGHTTP2_STREAM_FLAG_DEFERRED_USER. */
  98   NGHTTP2_STREAM_FLAG_DEFERRED_ALL = 0x0c
  99
 100 } nghttp2_stream_flag;
 101
 102 /* HTTP related flags to enforce HTTP semantics */
 103 typedef enum {
 104   NGHTTP2_HTTP_FLAG_NONE = 0,
 105   /* header field seen so far */
 106   NGHTTP2_HTTP_FLAG__AUTHORITY = 1,
 107   NGHTTP2_HTTP_FLAG__PATH = 1 << 1,
 108   NGHTTP2_HTTP_FLAG__METHOD = 1 << 2,
 109   NGHTTP2_HTTP_FLAG__SCHEME = 1 << 3,
 110   /* host is not pseudo header, but we require either host or
 111      :authority */
 112   NGHTTP2_HTTP_FLAG_HOST = 1 << 4,
 113   NGHTTP2_HTTP_FLAG__STATUS = 1 << 5,
 114   /* required header fields for HTTP request except for CONNECT
 115      method. */
 116   NGHTTP2_HTTP_FLAG_REQ_HEADERS = NGHTTP2_HTTP_FLAG__METHOD |
 117                                   NGHTTP2_HTTP_FLAG__PATH |
 118                                   NGHTTP2_HTTP_FLAG__SCHEME,
 119   NGHTTP2_HTTP_FLAG_PSEUDO_HEADER_DISALLOWED = 1 << 6,
 120   /* HTTP method flags */
 121   NGHTTP2_HTTP_FLAG_METH_CONNECT = 1 << 7,
 122   NGHTTP2_HTTP_FLAG_METH_HEAD = 1 << 8,
 123   NGHTTP2_HTTP_FLAG_METH_OPTIONS = 1 << 9,
 124   NGHTTP2_HTTP_FLAG_METH_ALL = NGHTTP2_HTTP_FLAG_METH_CONNECT |
 125                                NGHTTP2_HTTP_FLAG_METH_HEAD |
 126                                NGHTTP2_HTTP_FLAG_METH_OPTIONS,
 127   /* :path category */
 128   /* path starts with "/" */
 129   NGHTTP2_HTTP_FLAG_PATH_REGULAR = 1 << 10,
 130   /* path "*" */
 131   NGHTTP2_HTTP_FLAG_PATH_ASTERISK = 1 << 11,
 132   /* scheme */
 133   /* "http" or "https" scheme */
 134   NGHTTP2_HTTP_FLAG_SCHEME_HTTP = 1 << 12,
 135   /* set if final response is expected */
 136   NGHTTP2_HTTP_FLAG_EXPECT_FINAL_RESPONSE = 1 << 13
 137 } nghttp2_http_flag;
 138
 139 typedef enum {
 140   NGHTTP2_STREAM_DPRI_NONE = 0,
 141   NGHTTP2_STREAM_DPRI_NO_ITEM = 0x01,
 142   NGHTTP2_STREAM_DPRI_TOP = 0x02,
 143   NGHTTP2_STREAM_DPRI_REST = 0x04
 144 } nghttp2_stream_dpri;
 145
 146 struct nghttp2_stream_roots;
 147
 148 typedef struct nghttp2_stream_roots nghttp2_stream_roots;
 149
 150 struct nghttp2_stream;
 151
 152 typedef struct nghttp2_stream nghttp2_stream;
 153
 154 struct nghttp2_stream {
 155   /* Intrusive Map */
 156   nghttp2_map_entry map_entry;
 157   /* Content-Length of request/response body.  -1 if unknown. */
 158   int64_t content_length;
 159   /* Received body so far */
 160   int64_t recv_content_length;
 161   /* pointers to form dependency tree.  If multiple streams depend on
 162      a stream, only one stream (left most) has non-NULL dep_prev which
 163      points to the stream it depends on. The remaining streams are
 164      linked using sib_prev and sib_next.  The stream which has
 165      non-NULL dep_prev always NULL sib_prev.  The right most stream
 166      has NULL sib_next.  If this stream is a root of dependency tree,
 167      dep_prev and sib_prev are NULL. */
 168   nghttp2_stream *dep_prev, *dep_next;
 169   nghttp2_stream *sib_prev, *sib_next;
 170   /* pointers to track dependency tree root streams.  This is
 171      doubly-linked list and first element is pointed by
 172      roots->head. */
 173   nghttp2_stream *root_prev, *root_next;
 174   /* When stream is kept after closure, it may be kept in doubly
 175      linked list pointed by nghttp2_session closed_stream_head.
 176      closed_next points to the next stream object if it is the element
 177      of the list. */
 178   nghttp2_stream *closed_prev, *closed_next;
 179   /* pointer to roots, which tracks dependency tree roots */
 180   nghttp2_stream_roots *roots;
 181   /* The arbitrary data provided by user for this stream. */
 182   void *stream_user_data;
 183   /* Item to send */
 184   nghttp2_outbound_item *item;
 185   /* stream ID */
 186   int32_t stream_id;
 187   /* categorized priority of this stream.  Only stream bearing
 188      NGHTTP2_STREAM_DPRI_TOP can send item. */
 189   nghttp2_stream_dpri dpri;
 190   /* the number of streams in subtree */
 191   size_t num_substreams;
 192   /* Current remote window size. This value is computed against the
 193      current initial window size of remote endpoint. */
 194   int32_t remote_window_size;
 195   /* Keep track of the number of bytes received without
 196      WINDOW_UPDATE. This could be negative after submitting negative
 197      value to WINDOW_UPDATE */
 198   int32_t recv_window_size;
 199   /* The number of bytes consumed by the application and now is
 200      subject to WINDOW_UPDATE.  This is only used when auto
 201      WINDOW_UPDATE is turned off. */
 202   int32_t consumed_size;
 203   /* The amount of recv_window_size cut using submitting negative
 204      value to WINDOW_UPDATE */
 205   int32_t recv_reduction;
 206   /* window size for local flow control. It is initially set to
 207      NGHTTP2_INITIAL_WINDOW_SIZE and could be increased/decreased by
 208      submitting WINDOW_UPDATE. See nghttp2_submit_window_update(). */
 209   int32_t local_window_size;
 210   /* weight of this stream */
 211   int32_t weight;
 212   /* effective weight of this stream in belonging dependency tree */
 213   int32_t effective_weight;
 214   /* sum of weight (not effective_weight) of direct descendants */
 215   int32_t sum_dep_weight;
 216   /* sum of weight of direct descendants which have at least one
 217      descendant with dpri == NGHTTP2_STREAM_DPRI_TOP.  We use this
 218      value to calculate effective weight. */
 219   int32_t sum_norest_weight;
 220   nghttp2_stream_state state;
 221   /* status code from remote server */
 222   int16_t status_code;
 223   /* Bitwise OR of zero or more nghttp2_http_flag values */
 224   uint16_t http_flags;
 225   /* This is bitwise-OR of 0 or more of nghttp2_stream_flag. */
 226   uint8_t flags;
 227   /* Bitwise OR of zero or more nghttp2_shut_flag values */
 228   uint8_t shut_flags;
 229 };
 230
 231 void nghttp2_stream_init(nghttp2_stream *stream, int32_t stream_id,
 232                          uint8_t flags, nghttp2_stream_state initial_state,
 233                          int32_t weight, nghttp2_stream_roots *roots,
 234                          int32_t remote_initial_window_size,
 235                          int32_t local_initial_window_size,
 236                          void *stream_user_data);
 237
 238 void nghttp2_stream_free(nghttp2_stream *stream);
 239
 240 /*
 241  * Disallow either further receptions or transmissions, or both.
 242  * |flag| is bitwise OR of one or more of nghttp2_shut_flag.
 243  */
 244 void nghttp2_stream_shutdown(nghttp2_stream *stream, nghttp2_shut_flag flag);
 245
 246 /*
 247  * Defer |stream->item|.  We won't call this function in the situation
 248  * where |stream->item| == NULL.  The |flags| is bitwise OR of zero or
 249  * more of NGHTTP2_STREAM_FLAG_DEFERRED_USER and
 250  * NGHTTP2_STREAM_FLAG_DEFERRED_FLOW_CONTROL.  The |flags| indicates
 251  * the reason of this action.
 252  *
 253  * This function returns 0 if it succeeds, or one of the following
 254  * negative error codes:
 255  *
 256  * NGHTTP2_ERR_NOMEM
 257  *     Out of memory
 258  */
 259 int nghttp2_stream_defer_item(nghttp2_stream *stream, uint8_t flags,
 260                               nghttp2_session *session);
 261
 262 /*
 263  * Put back deferred data in this stream to active state.  The |flags|
 264  * are one or more of bitwise OR of the following values:
 265  * NGHTTP2_STREAM_FLAG_DEFERRED_USER and
 266  * NGHTTP2_STREAM_FLAG_DEFERRED_FLOW_CONTROL and given masks are
 267  * cleared if they are set.  So even if this function is called, if
 268  * one of flag is still set, data does not become active.
 269  */
 270 int nghttp2_stream_resume_deferred_item(nghttp2_stream *stream, uint8_t flags,
 271                                         nghttp2_session *session);
 272
 273 /*
 274  * Returns nonzero if item is deferred by whatever reason.
 275  */
 276 int nghttp2_stream_check_deferred_item(nghttp2_stream *stream);
 277
 278 /*
 279  * Returns nonzero if item is deferred by flow control.
 280  */
 281 int nghttp2_stream_check_deferred_by_flow_control(nghttp2_stream *stream);
 282
 283 /*
 284  * Updates the remote window size with the new value
 285  * |new_initial_window_size|. The |old_initial_window_size| is used to
 286  * calculate the current window size.
 287  *
 288  * This function returns 0 if it succeeds or -1. The failure is due to
 289  * overflow.
 290  */
 291 int nghttp2_stream_update_remote_initial_window_size(
 292     nghttp2_stream *stream, int32_t new_initial_window_size,
 293     int32_t old_initial_window_size);
 294
 295 /*
 296  * Updates the local window size with the new value
 297  * |new_initial_window_size|. The |old_initial_window_size| is used to
 298  * calculate the current window size.
 299  *
 300  * This function returns 0 if it succeeds or -1. The failure is due to
 301  * overflow.
 302  */
 303 int nghttp2_stream_update_local_initial_window_size(
 304     nghttp2_stream *stream, int32_t new_initial_window_size,
 305     int32_t old_initial_window_size);
 306
 307 /*
 308  * Call this function if promised stream |stream| is replied with
 309  * HEADERS.  This function makes the state of the |stream| to
 310  * NGHTTP2_STREAM_OPENED.
 311  */
 312 void nghttp2_stream_promise_fulfilled(nghttp2_stream *stream);
 313
 314 /*
 315  * Returns the stream positioned in root of the dependency tree the
 316  * |stream| belongs to.
 317  */
 318 nghttp2_stream *nghttp2_stream_get_dep_root(nghttp2_stream *stream);
 319
 320 /*
 321  * Returns nonzero if |target| is found in subtree of |stream|.
 322  */
 323 int nghttp2_stream_dep_subtree_find(nghttp2_stream *stream,
 324                                     nghttp2_stream *target);
 325
 326 /*
 327  * Computes distributed weight of a stream of the |weight| under the
 328  * |stream| if |stream| is removed from a dependency tree.  The result
 329  * is computed using stream->weight rather than
 330  * stream->effective_weight.
 331  */
 332 int32_t nghttp2_stream_dep_distributed_weight(nghttp2_stream *stream,
 333                                               int32_t weight);
 334
 335 /*
 336  * Computes effective weight of a stream of the |weight| under the
 337  * |stream|.  The result is computed using stream->effective_weight
 338  * rather than stream->weight.  This function is used to determine
 339  * weight in dependency tree.
 340  */
 341 int32_t nghttp2_stream_dep_distributed_effective_weight(nghttp2_stream *stream,
 342                                                         int32_t weight);
 343
 344 /*
 345  * Makes the |stream| depend on the |dep_stream|.  This dependency is
 346  * exclusive.  All existing direct descendants of |dep_stream| become
 347  * the descendants of the |stream|.  This function assumes
 348  * |stream->data| is NULL and no dpri members are changed in this
 349  * dependency tree.
 350  */
 351 void nghttp2_stream_dep_insert(nghttp2_stream *dep_stream,
 352                                nghttp2_stream *stream);
 353
 354 /*
 355  * Makes the |stream| depend on the |dep_stream|.  This dependency is
 356  * not exclusive.  This function assumes |stream->data| is NULL and no
 357  * dpri members are changed in this dependency tree.
 358  */
 359 void nghttp2_stream_dep_add(nghttp2_stream *dep_stream, nghttp2_stream *stream);
 360
 361 /*
 362  * Removes the |stream| from the current dependency tree.  This
 363  * function assumes |stream->data| is NULL.
 364  */
 365 void nghttp2_stream_dep_remove(nghttp2_stream *stream);
 366
 367 /*
 368  * Attaches |item| to |stream|.  Updates dpri members in this
 369  * dependency tree.
 370  *
 371  * This function returns 0 if it succeeds, or one of the following
 372  * negative error codes:
 373  *
 374  * NGHTTP2_ERR_NOMEM
 375  *     Out of memory
 376  */
 377 int nghttp2_stream_attach_item(nghttp2_stream *stream,
 378                                nghttp2_outbound_item *item,
 379                                nghttp2_session *session);
 380
 381 /*
 382  * Detaches |stream->item|.  Updates dpri members in this dependency
 383  * tree.  This function does not free |stream->item|.  The caller must
 384  * free it.
 385  *
 386  * This function returns 0 if it succeeds, or one of the following
 387  * negative error codes:
 388  *
 389  * NGHTTP2_ERR_NOMEM
 390  *     Out of memory
 391  */
 392 int nghttp2_stream_detach_item(nghttp2_stream *stream,
 393                                nghttp2_session *session);
 394
 395 /*
 396  * Makes the |stream| depend on the |dep_stream|.  This dependency is
 397  * exclusive.  Updates dpri members in this dependency tree.
 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_stream_dep_insert_subtree(nghttp2_stream *dep_stream,
 406                                       nghttp2_stream *stream,
 407                                       nghttp2_session *session);
 408
 409 /*
 410  * Makes the |stream| depend on the |dep_stream|.  This dependency is
 411  * not exclusive.  Updates dpri members in this dependency tree.
 412  *
 413  * This function returns 0 if it succeeds, or one of the following
 414  * negative error codes:
 415  *
 416  * NGHTTP2_ERR_NOMEM
 417  *     Out of memory
 418  */
 419 int nghttp2_stream_dep_add_subtree(nghttp2_stream *dep_stream,
 420                                    nghttp2_stream *stream,
 421                                    nghttp2_session *session);
 422
 423 /*
 424  * Removes subtree whose root stream is |stream|.  Removing subtree
 425  * does not change dpri values.  The effective_weight of streams in
 426  * removed subtree is not updated.
 427  *
 428  * This function returns 0 if it succeeds, or one of the following
 429  * negative error codes:
 430  *
 431  * NGHTTP2_ERR_NOMEM
 432  *     Out of memory
 433  */
 434 void nghttp2_stream_dep_remove_subtree(nghttp2_stream *stream);
 435
 436 /*
 437  * Makes the |stream| as root.  Updates dpri members in this
 438  * dependency tree.
 439  *
 440  * This function returns 0 if it succeeds, or one of the following
 441  * negative error codes:
 442  *
 443  * NGHTTP2_ERR_NOMEM
 444  *     Out of memory
 445  */
 446 int nghttp2_stream_dep_make_root(nghttp2_stream *stream,
 447                                  nghttp2_session *session);
 448
 449 /*
 450  * Makes the |stream| as root and all existing root streams become
 451  * direct children of |stream|.
 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
 460 nghttp2_stream_dep_all_your_stream_are_belong_to_us(nghttp2_stream *stream,
 461                                                     nghttp2_session *session);
 462
 463 /*
 464  * Returns nonzero if |stream| is in any dependency tree.
 465  */
 466 int nghttp2_stream_in_dep_tree(nghttp2_stream *stream);
 467
 468 struct nghttp2_stream_roots {
 469   nghttp2_stream *head;
 470
 471   int32_t num_streams;
 472 };
 473
 474 void nghttp2_stream_roots_init(nghttp2_stream_roots *roots);
 475
 476 void nghttp2_stream_roots_free(nghttp2_stream_roots *roots);
 477
 478 void nghttp2_stream_roots_add(nghttp2_stream_roots *roots,
 479                               nghttp2_stream *stream);
 480
 481 void nghttp2_stream_roots_remove(nghttp2_stream_roots *roots,
 482                                  nghttp2_stream *stream);
 483
 484 void nghttp2_stream_roots_remove_all(nghttp2_stream_roots *roots);
 485
 486 #endif /* NGHTTP2_STREAM */