Add migration section
This commit is contained in:
parent
24897aa50d
commit
084e4487ed
98
README.rst
98
README.rst
|
@ -208,6 +208,104 @@ To run the tests, run the following command under
|
||||||
|
|
||||||
Inside the tests, we use port 3009 to run the test subject server.
|
Inside the tests, we use port 3009 to run the test subject server.
|
||||||
|
|
||||||
|
Migration from v0.7.9 or earlier
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
nghttp2 v1.0.0 introduced several backward incompatible changes. In
|
||||||
|
this section, we describe these changes and how to migrate to v1.0.0.
|
||||||
|
|
||||||
|
ALPN protocol ID is now ``h2`` and ``h2c``
|
||||||
|
++++++++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
Previously we announced ``h2-14`` and ``h2c-14``. v1.0.0 implements
|
||||||
|
final protocol version, and we changed ALPN ID to ``h2`` and ``h2c``.
|
||||||
|
The macros ``NGHTTP2_PROTO_VERSION_ID``,
|
||||||
|
``NGHTTP2_PROTO_VERSION_ID_LEN``,
|
||||||
|
``NGHTTP2_CLEARTEXT_PROTO_VERSION_ID``, and
|
||||||
|
``NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN`` have been updated to
|
||||||
|
reflect this change.
|
||||||
|
|
||||||
|
Basically, existing applications do not have to do anything, just
|
||||||
|
recompiling is enough for this change.
|
||||||
|
|
||||||
|
Use word "client magic" where we use "client connection preface"
|
||||||
|
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
We use "client connection preface" to mean first 24 bytes of client
|
||||||
|
connection preface. This is technically not correct, since client
|
||||||
|
connection preface is composed of 24 bytes client magic byte string
|
||||||
|
followed by SETTINGS frame. For clarification, we call "client magic"
|
||||||
|
for this 24 bytes byte string and updated API.
|
||||||
|
|
||||||
|
* ``NGHTTP2_CLIENT_CONNECTION_PREFACE`` was replaced with
|
||||||
|
``NGHTTP2_CLIENT_MAGIC``.
|
||||||
|
* ``NGHTTP2_CLIENT_CONNECTION_PREFACE_LEN`` was replaced with
|
||||||
|
``NGHTTP2_CLIENT_MAGIC_LEN``.
|
||||||
|
* ``NGHTTP2_BAD_PREFACE`` was renamed as ``NGHTTP2_BAD_CLIENT_MAGIC``
|
||||||
|
|
||||||
|
The alreay deprecated ``NGHTTP2_CLIENT_CONNECTION_HEADER`` and
|
||||||
|
``NGHTTP2_CLIENT_CONNECTION_HEADER_LEN`` were removed.
|
||||||
|
|
||||||
|
If application uses these macros, just replace old ones with new ones.
|
||||||
|
Since v1.0.0, client magic is sent by library (see next subsection),
|
||||||
|
so client application may just remove these macro use.
|
||||||
|
|
||||||
|
Client magic is sent by library
|
||||||
|
+++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
Previously nghttp2 library did not send client magic, which is first
|
||||||
|
24 bytes byte string of client connection preface, and client
|
||||||
|
applications have to send it by themselves. Since v1.0.0, client
|
||||||
|
magic is sent by library via first call of ``nghttp2_session_send()``
|
||||||
|
or ``nghttp2_session_mem_send()``.
|
||||||
|
|
||||||
|
The client applications which send client magic must remove the
|
||||||
|
relevant code.
|
||||||
|
|
||||||
|
Remove HTTP Alternative Services (Alt-Svc) related code
|
||||||
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
Alt-Svc specification is not finalized yet. To make our API stable,
|
||||||
|
we have decided to remove all Alt-Svc related API from nghttp2.
|
||||||
|
|
||||||
|
* ``NGHTTP2_EXT_ALTSVC`` was removed.
|
||||||
|
* ``nghttp2_ext_altsvc`` was removed.
|
||||||
|
|
||||||
|
We have already removed the functionality of Alt-Svc in v0.7 series
|
||||||
|
and they have been essentially noop. The application using these
|
||||||
|
macro and struct, remove those lines.
|
||||||
|
|
||||||
|
Use nghttp2_error in nghttp2_on_invalid_frame_recv_callback
|
||||||
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
Previously ``nghttp2_on_invalid_frame_recv_cb_called`` took the
|
||||||
|
``error_code``, defined in ``nghttp2_error_code``, as parameter. But
|
||||||
|
they are not detailed enough to debug. Therefore, we decided to use
|
||||||
|
more detailed ``nghttp2_error`` values instead.
|
||||||
|
|
||||||
|
The application using this callback should update the callback
|
||||||
|
signature. If it treats ``error_code`` as HTTP/2 error code, update
|
||||||
|
the code so that it is treated as ``nghttp2_error``.
|
||||||
|
|
||||||
|
Receive client magic by default
|
||||||
|
+++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
Previously nghttp2 did not process client magic (24 bytes byte
|
||||||
|
string). To make it deal with it, we had to use
|
||||||
|
``nghttp2_option_set_recv_client_preface()``. Since v1.0.0, nghttp2
|
||||||
|
processes client magic by default and
|
||||||
|
``nghttp2_option_set_recv_client_preface()`` was removed.
|
||||||
|
|
||||||
|
Some application may want to disable this behaviour, so we added
|
||||||
|
``nghttp2_option_set_no_recv_client_magic()`` to achieve this.
|
||||||
|
|
||||||
|
The application using ``nghttp2_option_set_recv_client_preface()``
|
||||||
|
with nonzero value, just remove it.
|
||||||
|
|
||||||
|
The application using ``nghttp2_option_set_recv_client_preface()``
|
||||||
|
with zero value or not using it must use
|
||||||
|
``nghttp2_option_set_no_recv_client_magic()`` with nonzero value.
|
||||||
|
|
||||||
Client, Server and Proxy programs
|
Client, Server and Proxy programs
|
||||||
---------------------------------
|
---------------------------------
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue