aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/guide/book.asciidoc4
-rw-r--r--doc/src/guide/migrating_from_1.5.asciidoc69
-rw-r--r--doc/src/guide/migrating_from_1.x.asciidoc70
-rw-r--r--doc/src/guide/upcoming_2.0_changes.asciidoc1
4 files changed, 144 insertions, 0 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index c1e9e5d..ed47388 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -28,3 +28,7 @@ include::internals.asciidoc[Internals]
= Additional information
include::upcoming_2.0_changes.asciidoc[Upcoming changes in Ranch 2.0]
+
+include::migrating_from_1.5.asciidoc[Migrating from Ranch 1.5 to 1.6]
+
+include::migrating_from_1.x.asciidoc[Migrating from Ranch 1.x]
diff --git a/doc/src/guide/migrating_from_1.5.asciidoc b/doc/src/guide/migrating_from_1.5.asciidoc
new file mode 100644
index 0000000..40489f7
--- /dev/null
+++ b/doc/src/guide/migrating_from_1.5.asciidoc
@@ -0,0 +1,69 @@
+[appendix]
+== Migrating from Ranch 1.5 to 1.6
+
+Ranch 1.6 added the ability to suspend and resume listeners.
+It also deprecates a number of features and add interfaces
+that will be used in Ranch 2.0.
+
+Ranch 1.6 is compatible with Erlang/OTP 18.0 onward. Support
+for older releases has been removed.
+
+=== Features added
+
+* Listeners can now be suspended/resumed without stopping existing
+ connection processes. This effectively closes the listening socket
+ and stops the acceptor processes.
+
+* Transport options can now be updated for suspended listeners.
+
+* Ranch-specific transport options and socket options are now
+ better separated. When passing Ranch-specific transport options,
+ Ranch now expects to receive a map, in which case socket
+ options are passed in the `socket_opts` value. When there
+ are only socket options they can be passed to Ranch directly
+ as a convenience.
+
+* Any future transport option will only be added to the map
+ type. This includes transport options added in this release.
+
+* The transport option `ack_timeout` was renamed to `handshake_timeout`
+ in the map type.
+
+* The `cacerts` transport option is now silenced in error logs
+ just like the `certs` and `key` options.
+
+* The manual has been heavily updated and now features one
+ manual page per function and module, complete with a per-function
+ changelog, examples and more.
+
+=== Experimental features added
+
+* It is now possible to configure the restart intensity for
+ `ranch_sup` using the OTP application environment. This
+ feature will remain undocumented unless there is popular
+ demand for it.
+
+* Add the transport option `logger` that allows configuring
+ which logger module will be used. The logger module must
+ follow the interface of the new `logger` module in Erlang/OTP 21,
+ or be set to `error_logger` to keep the old behavior.
+
+=== Changed behaviors
+
+* Transport modules must now implement `Transport:handshake/1,2`
+ which deprecates and will replace `Transport:accept_ack/1` in
+ Ranch 2.0. It returns a new socket and can therefore be used
+ for implementing TLS upgrade mechanisms.
+
+=== New functions
+
+* The functions `ranch:suspend_listener/1` and `ranch:resume_listener/1`
+ were added. In addition the function `ranch:get_state/1` can be used
+ to obtain the running state of a listener.
+
+* A function `ranch:wait_for_connections/3` was added.
+
+=== Bugs fixed
+
+* The specs for the function `Transport:sendfile/2,4,5` have been
+ corrected. The type used for the filename was too restricting.
diff --git a/doc/src/guide/migrating_from_1.x.asciidoc b/doc/src/guide/migrating_from_1.x.asciidoc
new file mode 100644
index 0000000..44babf1
--- /dev/null
+++ b/doc/src/guide/migrating_from_1.x.asciidoc
@@ -0,0 +1,70 @@
+[appendix]
+== Migrating from Ranch 1.x
+
+The changelog for Ranch releases before 1.6 can be found
+in this section.
+
+=== 1.5.0
+
+* Add transport functions getopts/2, getstat/1 and getstat/2
+* Fix ranch:info/0 and ranch:procs/2 in embedded mode
+* Prevent ranch_conns_sup from stopping on unexpected messages
+
+=== 1.4.0
+
+* Add new transport option num_acceptor
+* Deprecate ranch:start_listener/6 in favor of start_listener/5
+* Deprecate ranch:child_spec/6 in favor of child_spec/5
+
+=== 1.3.0
+
+The version numbers 1.3.1 and 1.3.2 were later made to fix
+small mistakes made during the 1.3.0 release process. They
+do not include code changes.
+
+* Tested with OTP R16B+ on Linux, FreeBSD, OSX and Windows
+* Add ssl to the list of dependencies
+* Add ranch:info/0 and ranch:procs/2 to retrieve Ranch state information
+* Allow configuring a listener with only SNI, without a default certificate
+* Blacklist transport options instead of whitelist
+** Unknown options are now allowed, but will result in a Dialyzer warning
+* Add many transport options typespecs and documentation
+* Don't silently drop the accept rate when running out of fds
+* Prevent a race condition when stopping listeners
+* Improve reporting for common errors, for example eaddrinuse
+* Fix double removal of connections bug
+** The number of active connections should now be exact
+* Fix stuck acceptor bug when controlling_socket returned errors
+* Numerous documentation and examples improvements
+
+=== 1.2.1
+
+* Fix bug preventing node shutdown when SSL is used with OTP 17.1+
+* Tune restart intensity in all supervisors
+
+=== 1.2.0
+
+* Allow the supervised process and the process owning the socket to be different
+* Add many transport options (please refer to the documentation)
+* Add function ranch:get_addr/1 to retrieve both IP and port of listener
+* Don't pass Ranch-specific options down to transports
+** Should make Dialyzer happy in user projects
+** New types ranch:opt(), ranch_tcp:opt(), ranch_ssl:ssl_opt() and ranch_ssl:opt()
+* Fix crash when filtering unknown options out
+* Print a warning for each option filtered out
+* Handle Transport:controlling_socket/2 errors and close the socket
+* Handle Protocol:start_link/4 crashes to avoid killing all active connections
+* Use Asciidoc for documentation
+* Test Ranch across 14 Erlang versions on CircleCI
+* Improve and document test suites with recent ct_helper improvements
+* Fix a number of intermittent test issues
+
+=== 1.1.0
+
+* Add Transport:secure/0
+* Add SSL partial_chain option
+* Stop reporting errors on {error, closed} in accept_ack
+
+=== 1.0.0
+
+* Initial release
diff --git a/doc/src/guide/upcoming_2.0_changes.asciidoc b/doc/src/guide/upcoming_2.0_changes.asciidoc
index f60bde6..d743090 100644
--- a/doc/src/guide/upcoming_2.0_changes.asciidoc
+++ b/doc/src/guide/upcoming_2.0_changes.asciidoc
@@ -1,3 +1,4 @@
+[appendix]
== Upcoming changes in Ranch 2.0
The following changes will be done in Ranch 2.0. In most