doc/programmers-guide.rst

   1 Programmers' Guide
   2 ==================
   3
   4 Includes
   5 --------
   6
   7 To use the public APIs, include ``nghttp2/nghttp2.h``::
   8
   9     #include <nghttp2/nghttp2.h>
  10
  11 The header files are also available online: :doc:`nghttp2.h` and
  12 :doc:`nghttp2ver.h`.
  13
  14 Remarks
  15 -------
  16
  17 Do not call `nghttp2_session_send()`, `nghttp2_session_mem_send()`,
  18 `nghttp2_session_recv()` or `nghttp2_session_mem_recv()` from the
  19 nghttp2 callback functions directly or indirectly. It will lead to the
  20 crash.  You can submit requests or frames in the callbacks then call
  21 these functions outside the callbacks.
  22
  23 `nghttp2_session_send()` and `nghttp2_session_mem_send()` send first
  24 24 bytes of client magic string (MAGIC)
  25 (:macro:`NGHTTP2_CLIENT_MAGIC`) on client configuration.  The
  26 applications are responsible to send SETTINGS frame as part of
  27 connection preface using `nghttp2_submit_settings()`.  Similarly,
  28 `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` consume
  29 MAGIC on server configuration unless
  30 `nghttp2_option_set_no_recv_client_magic()` is used with nonzero
  31 option value.
  32
  33 .. _http-messaging:
  34
  35 HTTP Messaging
  36 --------------
  37
  38 By default, nghttp2 library checks HTTP messaging rules described in
  39 `HTTP/2 specification, section 8
  40 <https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-8>`_.
  41 Everything described in that section is not validated however.  We
  42 briefly describe what the library does in this area.  In the following
  43 description, without loss of generality we omit CONTINUATION frame
  44 since they must follow HEADERS frame and are processed atomically.  In
  45 other words, they are just one big HEADERS frame.  To disable these
  46 validations, use `nghttp2_option_set_no_http_messaging()`.
  47
  48 For HTTP request, including those carried by PUSH_PROMISE, HTTP
  49 message starts with one HEADERS frame containing request headers.  It
  50 is followed by zero or more DATA frames containing request body, which
  51 is followed by zero or one HEADERS containing trailer headers.  The
  52 request headers must include ":scheme", ":method" and ":path" pseudo
  53 header fields unless ":method" is not "CONNECT".  ":authority" is
  54 optional, but nghttp2 requires either ":authority" or "Host" header
  55 field must be present.  If ":method" is "CONNECT", the request headers
  56 must include ":method" and ":authority" and must omit ":scheme" and
  57 ":path".
  58
  59 For HTTP response, HTTP message starts with zero or more HEADERS
  60 frames containing non-final response (status code 1xx).  They are
  61 followed by one HEADERS frame containing final response headers
  62 (non-1xx).  It is followed by zero or more DATA frames containing
  63 response body, which is followed by zero or one HEADERS containing
  64 trailer headers.  The non-final and final response headers must
  65 contain ":status" pseudo header field containing 3 digits only.
  66
  67 All request and response headers must include exactly one valid value
  68 for each pseudo header field.  Additionally nghttp2 requires all
  69 request headers must not include more than one "Host" header field.
  70
  71 HTTP/2 prohibits connection-specific header fields.  The following
  72 header fields must not appear: "Connection", "Keep-Alive",
  73 "Proxy-Connection", "Transfer-Encoding" and "Upgrade".  Additionally,
  74 "TE" header field must not include any value other than "trailers".
  75
  76 Each header field name and value must obey the field-name and
  77 field-value production rules described in `RFC 7230, section
  78 3.2. <https://tools.ietf.org/html/rfc7230#section-3.2>`_.
  79 Additionally, all field name must be lower cased.  While the pseudo
  80 header fields must satisfy these rules, we just ignore illegal regular
  81 headers (this means that these header fields are not passed to
  82 application callback).  This is because these illegal header fields
  83 are floating around in existing internet and resetting stream just
  84 because of this may break many web sites.  This is especially true if
  85 we forward to or translate from HTTP/1 traffic.
  86
  87 For "http" or "https" URIs, ":path" pseudo header fields must start
  88 with "/".  The only exception is OPTIONS request, in that case, "*" is
  89 allowed in ":path" pseudo header field to represent system-wide
  90 OPTIONS request.
  91
  92 With the above validations, nghttp2 library guarantees that header
  93 field name passed to `nghttp2_on_header_callback()` is not empty.
  94 Also required pseudo headers are all present and not empty.
  95
  96 nghttp2 enforces "Content-Length" validation as well.  All request or
  97 response headers must not contain more than one "Content-Length"
  98 header field.  If "Content-Length" header field is present, it must be
  99 parsed as 64 bit signed integer.  The sum of data length in the
 100 following DATA frames must match with the number in "Content-Length"
 101 header field if it is present (this does not include padding bytes).
 102
 103 Any deviation results in stream error of type PROTOCOL_ERROR.  If
 104 error is found in PUSH_PROMISE frame, stream error is raised against
 105 promised stream.