diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 15 | ||||
| -rw-r--r-- | doc/README.rst | 2 | ||||
| -rw-r--r-- | doc/bash_completion/h2load | 2 | ||||
| -rw-r--r-- | doc/h2load.1 | 8 | ||||
| -rw-r--r-- | doc/h2load.1.rst | 5 | ||||
| -rw-r--r-- | doc/nghttp.1 | 2 | ||||
| -rw-r--r-- | doc/nghttpd.1 | 2 | ||||
| -rw-r--r-- | doc/nghttpx.1 | 2 | ||||
| -rw-r--r-- | doc/programmers-guide.rst | 42 | ||||
| -rw-r--r-- | doc/security.rst | 1 | ||||
| -rw-r--r-- | doc/sources/index.rst | 1 | ||||
| -rw-r--r-- | doc/sources/security.rst | 33 | ||||
| -rw-r--r-- | doc/sources/tutorial-client.rst | 27 | ||||
| -rw-r--r-- | doc/sources/tutorial-hpack.rst | 30 | ||||
| -rw-r--r-- | doc/sources/tutorial-server.rst | 43 |
15 files changed, 103 insertions, 112 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 7d7f31c..51945e4 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -42,7 +42,9 @@ APIDOCS= \ nghttp2_hd_deflate_get_num_table_entries.rst \ nghttp2_hd_deflate_get_table_entry.rst \ nghttp2_hd_deflate_hd.rst \ + nghttp2_hd_deflate_hd2.rst \ nghttp2_hd_deflate_hd_vec.rst \ + nghttp2_hd_deflate_hd_vec2.rst \ nghttp2_hd_deflate_new.rst \ nghttp2_hd_deflate_new2.rst \ nghttp2_hd_inflate_change_table_size.rst \ @@ -54,6 +56,7 @@ APIDOCS= \ nghttp2_hd_inflate_get_table_entry.rst \ nghttp2_hd_inflate_hd.rst \ nghttp2_hd_inflate_hd2.rst \ + nghttp2_hd_inflate_hd3.rst \ nghttp2_hd_inflate_new.rst \ nghttp2_hd_inflate_new2.rst \ nghttp2_http2_strerror.rst \ @@ -78,6 +81,7 @@ APIDOCS= \ nghttp2_option_set_max_settings.rst \ nghttp2_option_set_stream_reset_rate_limit.rst \ nghttp2_pack_settings_payload.rst \ + nghttp2_pack_settings_payload2.rst \ nghttp2_priority_spec_check_default.rst \ nghttp2_priority_spec_default_init.rst \ nghttp2_priority_spec_init.rst \ @@ -91,6 +95,7 @@ APIDOCS= \ nghttp2_session_callbacks_new.rst \ nghttp2_session_callbacks_set_before_frame_send_callback.rst \ nghttp2_session_callbacks_set_data_source_read_length_callback.rst \ + nghttp2_session_callbacks_set_data_source_read_length_callback2.rst \ nghttp2_session_callbacks_set_error_callback.rst \ nghttp2_session_callbacks_set_error_callback2.rst \ nghttp2_session_callbacks_set_on_begin_frame_callback.rst \ @@ -107,9 +112,13 @@ APIDOCS= \ nghttp2_session_callbacks_set_on_invalid_header_callback2.rst \ nghttp2_session_callbacks_set_on_stream_close_callback.rst \ nghttp2_session_callbacks_set_pack_extension_callback.rst \ + nghttp2_session_callbacks_set_pack_extension_callback2.rst \ nghttp2_session_callbacks_set_recv_callback.rst \ + nghttp2_session_callbacks_set_recv_callback2.rst \ nghttp2_session_callbacks_set_select_padding_callback.rst \ + nghttp2_session_callbacks_set_select_padding_callback2.rst \ nghttp2_session_callbacks_set_send_callback.rst \ + nghttp2_session_callbacks_set_send_callback2.rst \ nghttp2_session_callbacks_set_send_data_callback.rst \ nghttp2_session_callbacks_set_unpack_extension_callback.rst \ nghttp2_session_change_extpri_stream_priority.rst \ @@ -146,7 +155,9 @@ APIDOCS= \ nghttp2_session_get_stream_remote_window_size.rst \ nghttp2_session_get_stream_user_data.rst \ nghttp2_session_mem_recv.rst \ + nghttp2_session_mem_recv2.rst \ nghttp2_session_mem_send.rst \ + nghttp2_session_mem_send2.rst \ nghttp2_session_recv.rst \ nghttp2_session_resume_data.rst \ nghttp2_session_send.rst \ @@ -174,6 +185,7 @@ APIDOCS= \ nghttp2_strerror.rst \ nghttp2_submit_altsvc.rst \ nghttp2_submit_data.rst \ + nghttp2_submit_data2.rst \ nghttp2_submit_extension.rst \ nghttp2_submit_goaway.rst \ nghttp2_submit_headers.rst \ @@ -183,7 +195,9 @@ APIDOCS= \ nghttp2_submit_priority_update.rst \ nghttp2_submit_push_promise.rst \ nghttp2_submit_request.rst \ + nghttp2_submit_request2.rst \ nghttp2_submit_response.rst \ + nghttp2_submit_response2.rst \ nghttp2_submit_rst_stream.rst \ nghttp2_submit_settings.rst \ nghttp2_submit_shutdown_notice.rst \ @@ -212,7 +226,6 @@ EXTRA_DIST = \ sources/h2load-howto.rst \ sources/building-android-binary.rst \ sources/contribute.rst \ - sources/security.rst \ _exts/rubydomain/LICENSE.rubydomain \ _exts/rubydomain/__init__.py \ _exts/rubydomain/rubydomain.py \ diff --git a/doc/README.rst b/doc/README.rst index 549e550..7d4809c 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -68,7 +68,7 @@ The example follows:: * Callback function invoked when |session| wants to send data to * remote peer. */ - typedef ssize_t (*nghttp2_send_callback) + typedef nghttp2_ssize (*nghttp2_send_callback2) (nghttp2_session *session, const uint8_t *data, size_t length, int flags, void *user_data); diff --git a/doc/bash_completion/h2load b/doc/bash_completion/h2load index 2b2d4ab..e07d753 100644 --- a/doc/bash_completion/h2load +++ b/doc/bash_completion/h2load @@ -8,7 +8,7 @@ _h2load() _get_comp_words_by_ref cur prev case $cur in -*) - COMPREPLY=( $( compgen -W '--requests --clients --threads --input-file --max-concurrent-streams --max-frame-size --window-bits --connection-window-bits --header --ciphers --tls13-ciphers --no-tls-proto --data --rate --rate-period --duration --warm-up-time --connection-active-timeout --connection-inactivity-timeout --timing-script-file --base-uri --alpn-list --h1 --header-table-size --encoder-header-table-size --log-file --qlog-file-base --connect-to --rps --groups --no-udp-gso --max-udp-payload-size --ktls --verbose --version --help ' -- "$cur" ) ) + COMPREPLY=( $( compgen -W '--requests --clients --threads --input-file --max-concurrent-streams --max-frame-size --window-bits --connection-window-bits --header --ciphers --tls13-ciphers --no-tls-proto --data --rate --rate-period --duration --warm-up-time --connection-active-timeout --connection-inactivity-timeout --timing-script-file --base-uri --alpn-list --h1 --header-table-size --encoder-header-table-size --log-file --qlog-file-base --connect-to --rps --groups --no-udp-gso --max-udp-payload-size --ktls --sni --verbose --version --help ' -- "$cur" ) ) ;; *) _filedir diff --git a/doc/h2load.1 b/doc/h2load.1 index df052ab..09cdcf3 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "H2LOAD" "1" "Jan 21, 2024" "1.59.0" "nghttp2" +.TH "H2LOAD" "1" "Mar 01, 2024" "1.60.0" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool .SH SYNOPSIS @@ -344,6 +344,12 @@ Enable ktls. .UNINDENT .INDENT 0.0 .TP +.B \-\-sni=<DNSNAME> +Send <DNSNAME> in TLS SNI, overriding the host name +specified in URI. +.UNINDENT +.INDENT 0.0 +.TP .B \-v, \-\-verbose Output debug information. .UNINDENT diff --git a/doc/h2load.1.rst b/doc/h2load.1.rst index 85ed651..d63a839 100644 --- a/doc/h2load.1.rst +++ b/doc/h2load.1.rst @@ -290,6 +290,11 @@ OPTIONS Enable ktls. +.. option:: --sni=<DNSNAME> + + Send <DNSNAME> in TLS SNI, overriding the host name + specified in URI. + .. option:: -v, --verbose Output debug information. diff --git a/doc/nghttp.1 b/doc/nghttp.1 index 332d9c6..231e5a4 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "NGHTTP" "1" "Jan 21, 2024" "1.59.0" "nghttp2" +.TH "NGHTTP" "1" "Mar 01, 2024" "1.60.0" "nghttp2" .SH NAME nghttp \- HTTP/2 client .SH SYNOPSIS diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index 219a365..93a990d 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "NGHTTPD" "1" "Jan 21, 2024" "1.59.0" "nghttp2" +.TH "NGHTTPD" "1" "Mar 01, 2024" "1.60.0" "nghttp2" .SH NAME nghttpd \- HTTP/2 server .SH SYNOPSIS diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index e9742a5..ba40059 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "NGHTTPX" "1" "Jan 21, 2024" "1.59.0" "nghttp2" +.TH "NGHTTPX" "1" "Mar 01, 2024" "1.60.0" "nghttp2" .SH NAME nghttpx \- HTTP/2 proxy .SH SYNOPSIS diff --git a/doc/programmers-guide.rst b/doc/programmers-guide.rst index 820cd20..4bf5e28 100644 --- a/doc/programmers-guide.rst +++ b/doc/programmers-guide.rst @@ -40,28 +40,28 @@ most event-based architecture applications use is single thread per core, and handling one connection I/O is done by single thread. To feed input to :type:`nghttp2_session` object, one can use -`nghttp2_session_recv()` or `nghttp2_session_mem_recv()` functions. +`nghttp2_session_recv()` or `nghttp2_session_mem_recv2()` functions. They behave similarly, and the difference is that `nghttp2_session_recv()` will use :type:`nghttp2_read_callback` to get -input. On the other hand, `nghttp2_session_mem_recv()` will take -input as its parameter. If in doubt, use `nghttp2_session_mem_recv()` -since it is simpler, and could be faster since it avoids calling -callback function. +input. On the other hand, `nghttp2_session_mem_recv2()` will take +input as its parameter. If in doubt, use +`nghttp2_session_mem_recv2()` since it is simpler, and could be faster +since it avoids calling callback function. To get output from :type:`nghttp2_session` object, one can use -`nghttp2_session_send()` or `nghttp2_session_mem_send()`. The +`nghttp2_session_send()` or `nghttp2_session_mem_send2()`. The difference between them is that the former uses :type:`nghttp2_send_callback` to pass output to an application. On the other hand, the latter returns the output to the caller. If in -doubt, use `nghttp2_session_mem_send()` since it is simpler. But +doubt, use `nghttp2_session_mem_send2()` since it is simpler. But `nghttp2_session_send()` might be easier to use if the output buffer an application has is fixed sized. -In general, an application should call `nghttp2_session_mem_send()` +In general, an application should call `nghttp2_session_mem_send2()` when it gets input from underlying connection. Since there is great chance to get something pushed into transmission queue while the call -of `nghttp2_session_mem_send()`, it is recommended to call -`nghttp2_session_mem_recv()` after `nghttp2_session_mem_send()`. +of `nghttp2_session_mem_send2()`, it is recommended to call +`nghttp2_session_mem_recv2()` after `nghttp2_session_mem_send2()`. There is a question when we are safe to close HTTP/2 session without waiting for the closure of underlying connection. We offer 2 API @@ -70,7 +70,7 @@ calls for this: `nghttp2_session_want_read()` and can destroy :type:`nghttp2_session`, and then close the underlying connection. But make sure that the buffered output has been transmitted to the peer before closing the connection when -`nghttp2_session_mem_send()` is used, since +`nghttp2_session_mem_send2()` is used, since `nghttp2_session_want_write()` does not take into account the transmission of the buffered data outside of :type:`nghttp2_session`. @@ -87,18 +87,18 @@ The header files are also available online: :doc:`nghttp2.h` and Remarks ------- -Do not call `nghttp2_session_send()`, `nghttp2_session_mem_send()`, -`nghttp2_session_recv()` or `nghttp2_session_mem_recv()` from the +Do not call `nghttp2_session_send()`, `nghttp2_session_mem_send2()`, +`nghttp2_session_recv()` or `nghttp2_session_mem_recv2()` from the nghttp2 callback functions directly or indirectly. It will lead to the crash. You can submit requests or frames in the callbacks then call these functions outside the callbacks. -`nghttp2_session_send()` and `nghttp2_session_mem_send()` send first +`nghttp2_session_send()` and `nghttp2_session_mem_send2()` send first 24 bytes of client magic string (MAGIC) (:macro:`NGHTTP2_CLIENT_MAGIC`) on client configuration. The applications are responsible to send SETTINGS frame as part of connection preface using `nghttp2_submit_settings()`. Similarly, -`nghttp2_session_recv()` and `nghttp2_session_mem_recv()` consume +`nghttp2_session_recv()` and `nghttp2_session_mem_recv2()` consume MAGIC on server configuration unless `nghttp2_option_set_no_recv_client_magic()` is used with nonzero option value. @@ -222,7 +222,7 @@ above, the following code does not work: .. code-block:: c - nghttp2_submit_response(...) + nghttp2_submit_response2(...) nghttp2_submit_rst_stream(...) RST_STREAM cancels HEADERS (and DATA), and just RST_STREAM is sent. @@ -258,9 +258,9 @@ For example, we will illustrate how to send `ALTSVC const char *field; } alt_svc; - ssize_t pack_extension_callback(nghttp2_session *session, uint8_t *buf, - size_t len, const nghttp2_frame *frame, - void *user_data) { + nghttp2_ssize pack_extension_callback(nghttp2_session *session, uint8_t *buf, + size_t len, const nghttp2_frame *frame, + void *user_data) { const alt_svc *altsvc = (const alt_svc *)frame->ext.payload; size_t originlen = strlen(altsvc->origin); size_t fieldlen = strlen(altsvc->field); @@ -497,8 +497,8 @@ order to receive and process PRIORITY_UPDATE frame, server has to call NGHTTP2_PRIORITY_UPDATE)`` (see the above section), and pass the option to `nghttp2_session_server_new2()` or `nghttp2_session_server_new3()` to create a server session. Client -can send Priority header field via `nghttp2_submit_request()`. It can -also send PRIORITY_UPDATE frame via +can send Priority header field via `nghttp2_submit_request2()`. It +can also send PRIORITY_UPDATE frame via `nghttp2_submit_priority_update()`. Server processes Priority header field in a request header field and updates the stream priority unless HTTP messaging rule enforcement is disabled (see diff --git a/doc/security.rst b/doc/security.rst deleted file mode 100644 index 00b0c9c..0000000 --- a/doc/security.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../doc/sources/security.rst diff --git a/doc/sources/index.rst b/doc/sources/index.rst index b03c348..e181645 100644 --- a/doc/sources/index.rst +++ b/doc/sources/index.rst @@ -18,7 +18,6 @@ Contents: package_README contribute - security building-android-binary tutorial-client tutorial-server diff --git a/doc/sources/security.rst b/doc/sources/security.rst deleted file mode 100644 index 5a8fcd0..0000000 --- a/doc/sources/security.rst +++ /dev/null @@ -1,33 +0,0 @@ -Security Process -================ - -If you find a vulnerability in our software, please send the email to -"tatsuhiro.t at gmail dot com" about its details instead of submitting -issues on github issue page. It is a standard practice not to -disclose vulnerability information publicly until a fixed version is -released, or mitigation is worked out. In the future, we may setup a -dedicated mail address for this purpose. - -If we identify that the reported issue is really a vulnerability, we -open a new security advisory draft using `GitHub security feature -<https://github.com/nghttp2/nghttp2/security>`_ and discuss the -mitigation and bug fixes there. The fixes are committed to the -private repository. - -We write the security advisory and get CVE number from GitHub -privately. We also discuss the disclosure date to the public. - -We make a new release with the fix at the same time when the -vulnerability is disclosed to public. - -At least 7 days before the public disclosure date, we open a new issue -on `nghttp2 issue tracker -<https://github.com/nghttp2/nghttp2/issues>`_ which notifies that the -upcoming release will have a security fix. The ``SECURITY`` label is -attached to this kind of issue. The issue is not opened if a -vulnerability is already disclosed, and it is publicly known that -nghttp2 is affected by that. - -Before few hours of new release, we merge the fixes to the master -branch (and/or a release branch if necessary) and make a new release. -Security advisory is disclosed on GitHub. diff --git a/doc/sources/tutorial-client.rst b/doc/sources/tutorial-client.rst index 95a6230..be6eb55 100644 --- a/doc/sources/tutorial-client.rst +++ b/doc/sources/tutorial-client.rst @@ -171,7 +171,7 @@ session object and several callbacks:: nghttp2_session_callbacks_new(&callbacks); - nghttp2_session_callbacks_set_send_callback(callbacks, send_callback); + nghttp2_session_callbacks_set_send_callback2(callbacks, send_callback); nghttp2_session_callbacks_set_on_frame_recv_callback(callbacks, on_frame_recv_callback); @@ -246,8 +246,8 @@ HTTP request in the ``submit_request()`` function:: MAKE_NV(":path", stream_data->path, stream_data->pathlen)}; fprintf(stderr, "Request headers:\n"); print_headers(stderr, hdrs, ARRLEN(hdrs)); - stream_id = nghttp2_submit_request(session_data->session, NULL, hdrs, - ARRLEN(hdrs), NULL, stream_data); + stream_id = nghttp2_submit_request2(session_data->session, NULL, hdrs, + ARRLEN(hdrs), NULL, stream_data); if (stream_id < 0) { errx(1, "Could not submit HTTP request: %s", nghttp2_strerror(stream_id)); } @@ -258,11 +258,11 @@ HTTP request in the ``submit_request()`` function:: We build the HTTP request header fields in ``hdrs``, which is an array of :type:`nghttp2_nv`. There are four header fields to be sent: ``:method``, ``:scheme``, ``:authority``, and ``:path``. To queue the -HTTP request, we call `nghttp2_submit_request()`. The ``stream_data`` +HTTP request, we call `nghttp2_submit_request2()`. The ``stream_data`` is passed via the *stream_user_data* parameter, which is helpfully later passed back to callback functions. -`nghttp2_submit_request()` returns the newly assigned stream ID for +`nghttp2_submit_request2()` returns the newly assigned stream ID for the request. The next bufferevent callback is ``readcb()``, which is invoked when @@ -270,12 +270,12 @@ data is available to read from the bufferevent input buffer:: static void readcb(struct bufferevent *bev, void *ptr) { http2_session_data *session_data = (http2_session_data *)ptr; - ssize_t readlen; + nghttp2_ssize readlen; struct evbuffer *input = bufferevent_get_input(bev); size_t datalen = evbuffer_get_length(input); unsigned char *data = evbuffer_pullup(input, -1); - readlen = nghttp2_session_mem_recv(session_data->session, data, datalen); + readlen = nghttp2_session_mem_recv2(session_data->session, data, datalen); if (readlen < 0) { warnx("Fatal error: %s", nghttp2_strerror((int)readlen)); delete_http2_session_data(session_data); @@ -293,8 +293,8 @@ data is available to read from the bufferevent input buffer:: } In this function we feed all unprocessed, received data to the nghttp2 -session object using the `nghttp2_session_mem_recv()` function. -`nghttp2_session_mem_recv()` processes the received data and may +session object using the `nghttp2_session_mem_recv2()` function. +`nghttp2_session_mem_recv2()` processes the received data and may invoke nghttp2 callbacks and queue frames for transmission. Since there may be pending frames for transmission, we call immediately ``session_send()`` to send them. ``session_send()`` is defined as @@ -313,15 +313,16 @@ follows:: The `nghttp2_session_send()` function serializes pending frames into wire format and calls the ``send_callback()`` function to send them. -``send_callback()`` has type :type:`nghttp2_send_callback` and is +``send_callback()`` has type :type:`nghttp2_send_callback2` and is defined as:: - static ssize_t send_callback(nghttp2_session *session _U_, const uint8_t *data, - size_t length, int flags _U_, void *user_data) { + static nghttp2_ssize send_callback(nghttp2_session *session _U_, + const uint8_t *data, size_t length, + int flags _U_, void *user_data) { http2_session_data *session_data = (http2_session_data *)user_data; struct bufferevent *bev = session_data->bev; bufferevent_write(bev, data, length); - return (ssize_t)length; + return (nghttp2_ssize)length; } Since we use bufferevent to abstract network I/O, we just write the diff --git a/doc/sources/tutorial-hpack.rst b/doc/sources/tutorial-hpack.rst index 36e82d9..82acd94 100644 --- a/doc/sources/tutorial-hpack.rst +++ b/doc/sources/tutorial-hpack.rst @@ -24,11 +24,11 @@ deflater object for the dynamic header table. If in doubt, just specify 4096 here, which is the default upper bound of dynamic header table buffer size. -To encode header fields, use the `nghttp2_hd_deflate_hd()` function:: +To encode header fields, use the `nghttp2_hd_deflate_hd2()` function:: - ssize_t nghttp2_hd_deflate_hd(nghttp2_hd_deflater *deflater, - uint8_t *buf, size_t buflen, - const nghttp2_nv *nva, size_t nvlen); + nghttp2_ssize nghttp2_hd_deflate_hd2(nghttp2_hd_deflater *deflater, + uint8_t *buf, size_t buflen, + const nghttp2_nv *nva, size_t nvlen); The *deflater* is the deflater object initialized by `nghttp2_hd_deflate_new()` described above. The encoded byte string is @@ -44,7 +44,7 @@ cookies), set the :macro:`NGHTTP2_NV_FLAG_NO_INDEX` flag in sensitive header fields by compression based attacks: This is achieved by not inserting the header field into the dynamic header table. -`nghttp2_hd_deflate_hd()` processes all headers given in *nva*. The +`nghttp2_hd_deflate_hd2()` processes all headers given in *nva*. The *nva* must include all request or response header fields to be sent in one HEADERS (or optionally following (multiple) CONTINUATION frame(s)). The *buf* must have enough space to store the encoded @@ -55,13 +55,13 @@ of the encoded result length, use `nghttp2_hd_deflate_bound()`:: const nghttp2_nv *nva, size_t nvlen); Pass this function the same parameters (*deflater*, *nva*, and -*nvlen*) which will be passed to `nghttp2_hd_deflate_hd()`. +*nvlen*) which will be passed to `nghttp2_hd_deflate_hd2()`. -Subsequent calls to `nghttp2_hd_deflate_hd()` will use the current +Subsequent calls to `nghttp2_hd_deflate_hd2()` will use the current encoder state and perform differential encoding, which yields HPAC's fundamental compression gain. -If `nghttp2_hd_deflate_hd()` fails, the failure is fatal and any +If `nghttp2_hd_deflate_hd2()` fails, the failure is fatal and any further calls with the same deflater object will fail. Thus it's very important to use `nghttp2_hd_deflate_bound()` to determine the required size of the output buffer. @@ -78,14 +78,14 @@ header data. To initialize the object, use int nghttp2_hd_inflate_new(nghttp2_hd_inflater **inflater_ptr); -To inflate header data, use `nghttp2_hd_inflate_hd2()`:: +To inflate header data, use `nghttp2_hd_inflate_hd3()`:: - ssize_t nghttp2_hd_inflate_hd2(nghttp2_hd_inflater *inflater, - nghttp2_nv *nv_out, int *inflate_flags, - const uint8_t *in, size_t inlen, - int in_final); + nghttp2_ssize nghttp2_hd_inflate_hd3(nghttp2_hd_inflater *inflater, + nghttp2_nv *nv_out, int *inflate_flags, + const uint8_t *in, size_t inlen, + int in_final); -`nghttp2_hd_inflate_hd2()` reads a stream of bytes and outputs a +`nghttp2_hd_inflate_hd3()` reads a stream of bytes and outputs a single header field at a time. Multiple calls are normally required to read a full stream of bytes and output all of the header fields. @@ -119,7 +119,7 @@ If *in_final* is zero and the :macro:`NGHTTP2_HD_INFLATE_EMIT` flag is not set, it indicates that all given data was processed. The caller is required to pass additional data. -Example usage of `nghttp2_hd_inflate_hd2()` is shown in the +Example usage of `nghttp2_hd_inflate_hd3()` is shown in the `inflate_header_block()` function in `deflate.c`_. Finally, to delete a :type:`nghttp2_hd_inflater` object, use diff --git a/doc/sources/tutorial-server.rst b/doc/sources/tutorial-server.rst index 41680bd..bf71296 100644 --- a/doc/sources/tutorial-server.rst +++ b/doc/sources/tutorial-server.rst @@ -220,7 +220,7 @@ session object and several callbacks:: nghttp2_session_callbacks_new(&callbacks); - nghttp2_session_callbacks_set_send_callback(callbacks, send_callback); + nghttp2_session_callbacks_set_send_callback2(callbacks, send_callback); nghttp2_session_callbacks_set_on_frame_recv_callback(callbacks, on_frame_recv_callback); @@ -275,12 +275,12 @@ this pending data. To process the received data, we call the ``session_recv()`` function:: static int session_recv(http2_session_data *session_data) { - ssize_t readlen; + nghttp2_ssize readlen; struct evbuffer *input = bufferevent_get_input(session_data->bev); size_t datalen = evbuffer_get_length(input); unsigned char *data = evbuffer_pullup(input, -1); - readlen = nghttp2_session_mem_recv(session_data->session, data, datalen); + readlen = nghttp2_session_mem_recv2(session_data->session, data, datalen); if (readlen < 0) { warnx("Fatal error: %s", nghttp2_strerror((int)readlen)); return -1; @@ -296,9 +296,9 @@ this pending data. To process the received data, we call the } In this function, we feed all unprocessed but already received data to -the nghttp2 session object using the `nghttp2_session_mem_recv()` -function. The `nghttp2_session_mem_recv()` function processes the data -and may both invoke the previously setup callbacks and also queue +the nghttp2 session object using the `nghttp2_session_mem_recv2()` +function. The `nghttp2_session_mem_recv2()` function processes the +data and may both invoke the previously setup callbacks and also queue outgoing frames. To send any pending outgoing frames, we immediately call ``session_send()``. @@ -316,11 +316,12 @@ The ``session_send()`` function is defined as follows:: The `nghttp2_session_send()` function serializes the frame into wire format and calls the ``send_callback()``, which is of type -:type:`nghttp2_send_callback`. The ``send_callback()`` is defined as +:type:`nghttp2_send_callback2`. The ``send_callback()`` is defined as follows:: - static ssize_t send_callback(nghttp2_session *session _U_, const uint8_t *data, - size_t length, int flags _U_, void *user_data) { + static nghttp2_ssize send_callback(nghttp2_session *session _U_, + const uint8_t *data, size_t length, + int flags _U_, void *user_data) { http2_session_data *session_data = (http2_session_data *)user_data; struct bufferevent *bev = session_data->bev; /* Avoid excessive buffering in server side. */ @@ -329,7 +330,7 @@ follows:: return NGHTTP2_ERR_WOULDBLOCK; } bufferevent_write(bev, data, length); - return (ssize_t)length; + return (nghttp2_ssize)length; } Since we use bufferevent to abstract network I/O, we just write the @@ -509,11 +510,11 @@ Sending the file content is performed by the ``send_response()`` function:: static int send_response(nghttp2_session *session, int32_t stream_id, nghttp2_nv *nva, size_t nvlen, int fd) { int rv; - nghttp2_data_provider data_prd; + nghttp2_data_provider2 data_prd; data_prd.source.fd = fd; data_prd.read_callback = file_read_callback; - rv = nghttp2_submit_response(session, stream_id, nva, nvlen, &data_prd); + rv = nghttp2_submit_response2(session, stream_id, nva, nvlen, &data_prd); if (rv != 0) { warnx("Fatal error: %s", nghttp2_strerror(rv)); return -1; @@ -521,7 +522,7 @@ Sending the file content is performed by the ``send_response()`` function:: return 0; } -nghttp2 uses the :type:`nghttp2_data_provider` structure to send the +nghttp2 uses the :type:`nghttp2_data_provider2` structure to send the entity body to the remote peer. The ``source`` member of this structure is a union, which can be either a void pointer or an int (which is intended to be used as file descriptor). In this example @@ -529,11 +530,11 @@ server, we use it as a file descriptor. We also set the ``file_read_callback()`` callback function to read the contents of the file:: - static ssize_t file_read_callback(nghttp2_session *session _U_, - int32_t stream_id _U_, uint8_t *buf, - size_t length, uint32_t *data_flags, - nghttp2_data_source *source, - void *user_data _U_) { + static nghttp2_ssize file_read_callback(nghttp2_session *session _U_, + int32_t stream_id _U_, uint8_t *buf, + size_t length, uint32_t *data_flags, + nghttp2_data_source *source, + void *user_data _U_) { int fd = source->fd; ssize_t r; while ((r = read(fd, buf, length)) == -1 && errno == EINTR) @@ -544,7 +545,7 @@ file:: if (r == 0) { *data_flags |= NGHTTP2_DATA_FLAG_EOF; } - return r; + return (nghttp2_ssize)r; } If an error occurs while reading the file, we return @@ -553,8 +554,8 @@ library to send RST_STREAM to the stream. When all data has been read, the :macro:`NGHTTP2_DATA_FLAG_EOF` flag is set to signal nghttp2 that we have finished reading the file. -The `nghttp2_submit_response()` function is used to send the response to the -remote peer. +The `nghttp2_submit_response2()` function is used to send the response +to the remote peer. The ``on_stream_close_callback()`` function is invoked when the stream is about to close:: |