From d7580dbfdbdcf3ecf085479b6550284a47745138 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 28 Apr 2023 13:34:22 +0200
Subject: Cowboy 2.10.0

---
 .../cowboy/2.10/guide/migrating_from_2.6.asciidoc  | 224 +++++++++++++++++++++
 1 file changed, 224 insertions(+)
 create mode 100644 docs/en/cowboy/2.10/guide/migrating_from_2.6.asciidoc

(limited to 'docs/en/cowboy/2.10/guide/migrating_from_2.6.asciidoc')

diff --git a/docs/en/cowboy/2.10/guide/migrating_from_2.6.asciidoc b/docs/en/cowboy/2.10/guide/migrating_from_2.6.asciidoc
new file mode 100644
index 00000000..91d15887
--- /dev/null
+++ b/docs/en/cowboy/2.10/guide/migrating_from_2.6.asciidoc
@@ -0,0 +1,224 @@
+[appendix]
+== Migrating from Cowboy 2.6 to 2.7
+
+Cowboy 2.7 improves the HTTP/2 code with optimizations
+around the sending of DATA and WINDOW_UPDATE frames;
+graceful shutdown of the connection when the client is
+going away; and rate limiting mechanisms. New options
+and mechanisms have also been added to control the
+amount of memory Cowboy ends up using with both HTTP/1.1
+and HTTP/2. Much, but not all, of this work was done
+to address HTTP/2 CVEs about potential denial of service.
+
+In addition, many of the experimental features introduced
+in previous releases have been marked stable and are now
+documented.
+
+Cowboy 2.7 requires Erlang/OTP 20.0 or greater.
+
+=== Features added
+
+* Cowboy is now compatible with both Ranch 1.7 and the
+  upcoming Ranch 2.0.
+
+* The number of HTTP/2 WINDOW_UPDATE frames Cowboy sends
+  has been greatly reduced. Cowboy now applies heuristics
+  to determine whether it is necessary to update the window,
+  based on the current window size and the amount of data
+  requested by streams (the `cowboy_req:read_body/2` length
+  for example). Six new options have been added to control
+  this behavior: `connection_window_margin_size`,
+  `connection_window_update_threshold`,
+  `max_connection_window_size`, `max_stream_window_size`,
+  `stream_window_margin_size` and
+  `stream_window_update_threshold`.
+
+* HTTP/2 connections will now be shut down gracefully
+  when receiving a GOAWAY frame. Cowboy will simply
+  wait for existing streams to finish before closing
+  the connection.
+
+* Functions that stream the response body now have
+  backpressure applied. They now wait for a message
+  to be sent back. The message will be held off when
+  using HTTP/2 and the buffer sizes exceed either
+  `max_connection_buffer_size` or `max_stream_buffer_size`.
+  For HTTP/1.1 the data is sent synchronously and we
+  rely instead on the TCP backpressure.
+
+* A new HTTP/2 option `stream_window_data_threshold`
+  can be used to control how little the DATA frames that
+  Cowboy sends can get. By default Cowboy will wait for
+  the window to be large enough to send either everything
+  queued or to reach the default maximum frame size of
+  16384 bytes.
+
+* A new HTTP/2 option `max_receive_frame_rate` can be
+  used to control how fast the server is willing to receive
+  frames. By default it will accept 1000 frames every 10
+  seconds.
+
+* A new HTTP/2 option `max_reset_stream_rate` can be
+  used to control the rate of errors the server is
+  willing to accept. By default it will accept 10
+  stream resets every 10 seconds.
+
+* Flow control for incoming data has been implemented
+  for HTTP/1.1. Cowboy will now wait for the user code
+  to ask for the request body before reading it from
+  the socket. The option `initial_stream_flow_size`
+  controls how much data Cowboy will read without
+  being asked.
+
+* The HTTP/1.1 and HTTP/2 option `logger` is now
+  documented.
+
+* The Websocket option `validate_utf8` has been
+  added. It can be used to disable the expensive UTF-8
+  validation for incoming text and close frames.
+
+* The experimental commands based Websocket interface
+  is now considered stable and has been documented.
+  The old interface is now deprecated.
+
+* A new Websocket handler command `shutdown_reason`
+  can be used to change the normal exit reason of
+  Websocket processes. By default `normal` is used;
+  with this command the exit reason can be changed
+  to `{shutdown, ShutdownReason}`.
+
+* The experimental stream handlers `cowboy_metrics_h`
+  and `cowboy_tracer_h` are now considered stable and
+  have been documented.
+
+* The stream handler commands `set_options` and `log`
+  are now considered stable and have been documented.
+
+* The router is now capable of retrieving dispatch
+  rules directly from the `persistent_term` storage
+  (available starting from Erlang/OTP 21.2).
+
+* Support for the status codes 208 and 508 has been
+  added.
+
+* Update Ranch to 1.7.1.
+
+* Update Cowlib to 2.8.0.
+
+=== Experimental features added
+
+* It is now possible to read the response body from any
+  process, as well as doing any other `cowboy_req`
+  operations. Since this is not recommended due to
+  race condition concerns this feature will always
+  remain experimental.
+
+=== New functions
+
+* The function `cowboy_req:filter_cookies/2` has been
+  added. It can be called before parsing/matching
+  cookies in order to filter out undesirables. The
+  main reason for doing this is to avoid most parse
+  errors that may occur when dealing with Web browsers
+  (which have a string-based Javascript interface to
+  cookies that is very permissive of invalid content)
+  and to be able to recover in other cases.
+
+* The function `cowboy_req:cast/2` has been added.
+  It can be used to send events to stream handlers.
+
+=== Bugs fixed
+
+* A number of fixes and additions were made to address the
+  HTTP/2 CVEs CVE-2019-9511 through CVE-2019-9518, except
+  for CVE-2019-9513 which required no intervention as the
+  relevant protocol feature is not implemented by Cowboy.
+
+* The HTTP/2 connection window could become larger than the
+  protocol allows, leading to errors. This has been corrected.
+
+* The presence of empty header names in HTTP/2 requests now
+  results in the request to be rejected.
+
+* Cowboy will now remove headers specific to HTTP/1.1
+  (the hop by hop headers such as connection or upgrade)
+  when building an HTTP/2 response.
+
+* A bug in the HTTP/2 code that resulted in the failure to
+  fully send iolist response bodies has been fixed. Cowboy
+  would just wait indefinitely in those cases.
+
+* It was possible for a final empty HTTP/2 DATA frame to get
+  stuck and never sent when the window reached 0 and the remote
+  end did not increase the window anymore. This has been
+  corrected.
+
+* Cowboy now uses the host header when the HTTP/2
+  :authority pseudo header is missing. A common scenario
+  where this occurs is when proxies translate incoming
+  HTTP/1.1 requests to HTTP/2.
+
+* HTTP/1.1 connections are now properly closed when the
+  user code sends less data than advertised in the response
+  headers.
+
+* Cowboy will now close HTTP/1.1 connections immediately when
+  a header line is missing a colon separator. Previously it
+  was waiting for more data.
+
+* It was possible for Cowboy to receive stray timeout messages
+  for HTTP/1.1 connections, resulting in crashes. The timeout
+  handling in HTTP/1.1 has been reworked and the issue should
+  no longer occur.
+
+* The type for the Req object has been updated to accept
+  custom fields as was already documented.
+
+* The authentication scheme returned when parsing the
+  authorization header is now case insensitive, which
+  means it will be returned as lowercase.
+
+* Cowboy no longer discards data that follows a Websocket
+  upgrade request. Note that the protocol does not allow
+  sending data before receiving a successful Websocket
+  upgrade response, so this fix is more out of principle
+  rather than to fix a real world issue.
+
+* The `cowboy_static` handler will now properly detect
+  the type of files that have an uppercase or mixed
+  extension component.
+
+* The `cowboy_static` handler is now consistent across all
+  supported platforms. It now explicitly rejects `path_info`
+  components that include a forward slash, backward slash
+  or NUL character.
+
+* The update to Ranch 1.7.1 fixes an issue with the PROXY
+  protocol that would cause checksum verification to fail.
+
+* The HTTP/1.1 error reason for `stream_error` mistakenly
+  contained an extra element. It has now been removed.
+
+* The `PartialReq` given to the `early_error` stream handler
+  callback now includes headers when the protocol is HTTP/2.
+
+* A bug where the stacktrace was incorrect in error messages
+  has been fixed. The problem occurred when an exception
+  occurred in the handler's terminate callback.
+
+* The REST flowchart for POST, PATCH and PUT has received
+  a number of fixes and had to be greatly reworked as a
+  result. When the method is PUT, we do not check for
+  the location header in the response. When the resource
+  doesn't exist and the method was PUT the flowchart was
+  largely incorrect. A 415 response may occur after the
+  `content_types_accepted` callback and was missing from
+  the flowchart.
+
+* The documentation for `content_types_accepted` now
+  includes the media type wildcard that was previously
+  missing.
+
+* The documentation for a type found in `cow_cookie`
+  was missing. A manual page for `cow_cookie` was added
+  and can be found in the Cowlib documentation.
-- 
cgit v1.2.3

