diff options
| -rw-r--r-- | doc/src/guide/book.asciidoc | 4 | ||||
| -rw-r--r-- | doc/src/guide/introduction.asciidoc | 4 | ||||
| -rw-r--r-- | doc/src/guide/migrating_from_1.7.asciidoc | 138 | ||||
| -rw-r--r-- | doc/src/guide/upcoming_2.0_changes.asciidoc | 39 |
4 files changed, 132 insertions, 53 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc index e87e7b3..1c8d78a 100644 --- a/doc/src/guide/book.asciidoc +++ b/doc/src/guide/book.asciidoc @@ -29,9 +29,7 @@ include::internals.asciidoc[Internals] = Additional information -include::upcoming_2.0_changes.asciidoc[Upcoming changes in Ranch 2.0] - -include::migrating_from_1.7.asciidoc[Changes since Ranch 1.7] +include::migrating_from_1.7.asciidoc[Migrating from Ranch 1.7 to 2.0] include::migrating_from_1.6.asciidoc[Migrating from Ranch 1.6 to 1.7] diff --git a/doc/src/guide/introduction.asciidoc b/doc/src/guide/introduction.asciidoc index 1644921..d904c65 100644 --- a/doc/src/guide/introduction.asciidoc +++ b/doc/src/guide/introduction.asciidoc @@ -13,9 +13,9 @@ with socket programming and TCP protocols. === Supported platforms -Ranch is tested and supported on Linux, FreeBSD, OSX and Windows. +Ranch is tested and supported on Linux, FreeBSD, macOS and Windows. -Ranch is developed for Erlang/OTP 19+. +Ranch is developed for Erlang/OTP 21+. Ranch may be compiled on earlier Erlang versions with small source code modifications but there is no guarantee that it will work as expected. diff --git a/doc/src/guide/migrating_from_1.7.asciidoc b/doc/src/guide/migrating_from_1.7.asciidoc index a4ce981..3724246 100644 --- a/doc/src/guide/migrating_from_1.7.asciidoc +++ b/doc/src/guide/migrating_from_1.7.asciidoc @@ -1,14 +1,134 @@ [appendix] -== Changes since Ranch 1.7 +== Migrating from Ranch 1.7 to Ranch 2.0 -The following patch versions were released since Ranch 1.7: +Ranch 2.0 adds support for multiple connection supervisors. -=== Ranch 1.7.1 +Ranch 1.x had a bottleneck because it used only a single +connection supervisor. This was more evident when many +connections were dropped at once as the supervisor couldn't +keep up and failed to accept new connections while cleaning +up the old ones. Ranch 2.0 behaves much better in this scenario +by default. Multiple connection supervisors also helps with +concurrently accepting new connections. -This release fixes an issue with the PROXY protocol where -the wrong CRC32 algorithm was used and would cause checksum -verification to fail. +Ranch 2.0 also adds experimental support for opening more +than one listening socket on a single port. -Because the plain `crc32` checksum is not supported by the -PROXY protocol, the configuration value when building PROXY -headers has been changed to `crc32c`. +Starting with Ranch 2.0 we are also providing a Prometheus +collector as a separate project as well as a Grafana +dashboard. + +Ranch 2.0 is compatible with Erlang/OTP 21.0 onward. Support +for Erlang/OTP 19 and 20 has been removed. + +=== Features added + +* The `num_conns_sup` option has been added. It allows + configuring the number of connection supervisors. It + now defaults to `num_accceptors`. The old behavior can + be obtained by setting this value to 1. + +* The `logger` option is no longer experimental. It now + defaults to `logger` instead of `error_logger`. + +* UNIX domain sockets are now supported. + +* The active N socket option is now supported. It requires + Erlang/OTP 21.3 or above for TLS, however. + +* Embedded listeners are now failing in a predictable + manner when `ranch_server` goes down. It is no longer + necessary to embed `ranch_sup` and the recommendation + is now to just start Ranch normally when using embedded + listeners. + +=== Experimental features added + +* The experimental `num_listen_sockets` option has been + added. It allows opening more than one listening socket + per listener. It can only be used alongside the Linux + `SO_REUSEPORT` socket option or equivalent. It allows + working around a bottleneck in the kernel and maximizes + resource usage, leading to increased rates for accepting + new connections. + +=== Features removed + +* The `socket` option was removed. A more viable solution + is to define a custom transport module that returns a fresh + socket when `Transport:listen/1` is called. + +=== Changed behaviors + +* The callback function `Transport:listen/1` and its + implementations in `ranch_tcp` and `ranch_ssl` have changed + to accept a map of transport options instead of only + socket options. + +* The callback function `Transport:messages/0` return value + now include the tag used for passive messages. + +* The `Socket` argument was removed from `Protocol:start_link/3`. + The socket must now be obtained by calling `ranch:handshake/1,2`. + +=== Changed functions + +* The `NumAcceptors` argument was removed from `ranch:start_listener/5`` + and `ranch:child_spec/5` and moved to the transport options. + +* Ranch options can no longer be passed along with socket options + as a proplist. The only forms allowed are now the `ranch:opts()` + map or only socket options as-is. Individual transport options + are now validated as well. The `ranch:opts()` map must + be used when socket options also use a map. This applies to the + `ranch:start_listener/5`, `ranch:child_spec/5` and + `ranch:set_transport_options/2` functions. + +* The function `ranch:info/1,2` now returns a map containing + each listener's information rather than a list of key/values. + The key `num_acceptors` was removed as it can be found in the + transport options. + +* The function `ranch:set_transport_options/2` no longer requires + the listener to be suspended. Which options apply immediately, + on suspend/resume or on restart has been documented. Some work + has also been done to make these option changes more predictable. + +=== Removed functions + +* The function `ranch:accept_ack/1` has been removed in favor + of `ranch:handshake/1,2`. + +=== Bugs fixed + +* Repeatedly calling `ranch:remove_connection/1` from a connection + process would crash the respective connection supervisor. This has + now been fixed. + +* When a connection process was failing to start, the socket was + not closed and this lead to leaking sockets. This is now corrected. + +=== Other changes + +* Connection draining has now been documented in the guide + following user feedback and discussions. + +* Ranch is now tested against `havoc`, a chaos monkey style + testing tool. Currently includes three scenarios: normal + TCP and TLS listeners and embedded TCP listener. This new + test suite helped uncover a misplaced `monitor/2` call + added during the development of Ranch 2.0. + +* The supervisor for acceptors and the parent supervisor for + connection supervisors now have an adaptive restart + intensity limit set to `1 + ceil(math:log2(NumChildren))` + to allow room for errors when they have many children. + +* Ranch now uses stricter compiler options. Missing function + specs were added to internal modules. + +* Ranch now calls `ssl:handshake/1,2,3` instead of + `ssl:ssl_accept/1,2`. + +* The `ranch_ssl:ssl_opt()` type has been updated to conform + with Erlang/OTP 22.0. diff --git a/doc/src/guide/upcoming_2.0_changes.asciidoc b/doc/src/guide/upcoming_2.0_changes.asciidoc deleted file mode 100644 index 378d0a6..0000000 --- a/doc/src/guide/upcoming_2.0_changes.asciidoc +++ /dev/null @@ -1,39 +0,0 @@ -[appendix] -== Upcoming changes in Ranch 2.0 - -The following changes will be done in Ranch 2.0. In most -cases an alternative is already available in the most -recent Ranch version. - -* The callback function `ranch_transport:listen/1` and its - implementations in `ranch_tcp` and `ranch_ssl` have changed - to accept a map of transport options instead of socket - options. - -* The function `ranch:start_listener/6` has been deprecated - in favor of `ranch:start_listener/5`. The number of acceptors - was removed and will be taken from the transport options. - -* The function `ranch:child_spec/6` has also been deprecated, - in favor of `ranch:child_spec/5`. - -* The function `ranch:accept_ack/1` has been deprecated in - favor of `ranch:handshake/1,2`. - -* The function `ranch:info/1,2` will return a map containing - each listener's information rather than a list of key/values. - The `num_acceptors` key will be removed. - -* The socket will no longer be passed to the protocol when - starting it. It will be available as a return value from - `ranch:handshake/1,2` only. - -* Starting from Ranch 2.0 it will no longer be allowed to - pass Ranch options along with socket options as a proplist. - The only forms allowed will be the `ranch:opts()` map or socket - options as-is. The `ranch:opts()` map must be used in case socket - options also use a map. - -* The `socket` option will be removed. A more viable solution - is to define a custom transport module that returns a fresh - socket when `Transport:listen/1` is called. |