From 2052a1a4bd64b10236f9bbba63679cc498e430ed Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Fri, 23 Sep 2016 22:41:49 +0900 Subject: [PATCH] Document how libnghttp2 schedules HTTP/2 frames internally --- doc/programmers-guide.rst | 45 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/doc/programmers-guide.rst b/doc/programmers-guide.rst index 554c79bc..f49663b6 100644 --- a/doc/programmers-guide.rst +++ b/doc/programmers-guide.rst @@ -177,6 +177,51 @@ Any deviation results in stream error of type PROTOCOL_ERROR. If error is found in PUSH_PROMISE frame, stream error is raised against promised stream. +The order of transmission of the HTTP/2 frames +---------------------------------------------- + +This section describes the internals of libnghttp2 about the +scheduling of transmission of HTTP/2 frames. This is pretty much +internal stuff, so the details could change in the future versions of +the library. + +libnghttp2 categorizes HTTP/2 frames into 4 categories: urgent, +regular, syn_stream, and data in the order of higher priority. + +The urgent category includes PING and SETTINGS. They are sent with +highest priority. The order inside the category is FIFO. + +The regular category includes frames other than PING, SETTINGS, DATA, +and HEADERS which does not create stream (which counts toward +concurrent stream limit). The order inside the category is FIFO. + +The syn_stream category includes HEADERS frame which creates stream, +that counts toward the concurrent stream limit. + +The data category includes DATA frame, and the scheduling among DATA +frames are determined by HTTP/2 dependency tree. + +If the application wants to send frames in the specific order, and the +default transmission order does not fit, it has to schedule frames by +itself using the callbacks (e.g., +:type:`nghttp2_on_frame_send_callback`). + +For example, suppose that application wants to send RST_STREAM after +sending response HEADERS and DATA. Because of the reason we mentioned +above, the following code does not work: + +.. code-block:: c + + nghttp2_submit_response(...) + nghttp2_submit_rst_stream(...) + +This is because HEADERS submitted by `nghttp2_submit_response()` is +scheduled after RST_STREAM submitted by `nghttp2_submit_rst_stream()`. + +The correct way is use :type:`nghttp2_on_frame_send_callback`, and +after HEADERS and DATA frames are sent, issue +`nghttp2_submit_rst_stream()`. + Implement user defined HTTP/2 non-critical extensions -----------------------------------------------------