From 5ff790b8d2b04152d0bf851cbf759f3c33cf53e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 25 Mar 2020 14:09:51 +0100 Subject: Gun 2.0.0-pre.2 and Cowlib 2.9.0 --- .../2.8/manual/cow_cookie.parse_cookie/index.html | 2 + .../2.8/manual/cow_cookie.setcookie/index.html | 2 + docs/en/cowlib/2.8/manual/cow_cookie/index.html | 2 + docs/en/cowlib/2.8/manual/cowlib_app/index.html | 2 + docs/en/cowlib/2.8/manual/index.html | 2 + .../cowlib/2.9/manual/cow_cookie.cookie/index.html | 182 +++++++++++++ .../2.9/manual/cow_cookie.parse_cookie/index.html | 184 +++++++++++++ .../manual/cow_cookie.parse_set_cookie/index.html | 191 +++++++++++++ .../2.9/manual/cow_cookie.setcookie/index.html | 192 ++++++++++++++ docs/en/cowlib/2.9/manual/cow_cookie/index.html | 223 ++++++++++++++++ docs/en/cowlib/2.9/manual/cowlib_app/index.html | 173 ++++++++++++ docs/en/cowlib/2.9/manual/index.html | 173 ++++++++++++ docs/en/gun/2.0/guide/introduction.asciidoc | 8 +- docs/en/gun/2.0/guide/introduction/index.html | 3 +- docs/en/gun/2.0/guide/migrating_from_1.3.asciidoc | 34 ++- .../en/gun/2.0/guide/migrating_from_1.3/index.html | 18 +- docs/en/gun/2.0/manual/gun.info/index.html | 5 +- docs/en/gun/2.0/manual/gun/index.html | 9 +- docs/en/gun/2.0/manual/gun_app/index.html | 4 + .../2.0/manual/gun_cookies.domain_match/index.html | 195 ++++++++++++++ .../2.0/manual/gun_cookies.path_match/index.html | 195 ++++++++++++++ docs/en/gun/2.0/manual/gun_cookies/index.html | 294 +++++++++++++++++++++ docs/en/gun/2.0/manual/gun_cookies_list/index.html | 192 ++++++++++++++ docs/en/gun/2.0/manual/index.html | 4 + docs/en/ranch/2.0/guide/internals.asciidoc | 5 + docs/en/ranch/2.0/guide/internals/index.html | 1 + 26 files changed, 2277 insertions(+), 18 deletions(-) create mode 100644 docs/en/cowlib/2.9/manual/cow_cookie.cookie/index.html create mode 100644 docs/en/cowlib/2.9/manual/cow_cookie.parse_cookie/index.html create mode 100644 docs/en/cowlib/2.9/manual/cow_cookie.parse_set_cookie/index.html create mode 100644 docs/en/cowlib/2.9/manual/cow_cookie.setcookie/index.html create mode 100644 docs/en/cowlib/2.9/manual/cow_cookie/index.html create mode 100644 docs/en/cowlib/2.9/manual/cowlib_app/index.html create mode 100644 docs/en/cowlib/2.9/manual/index.html create mode 100644 docs/en/gun/2.0/manual/gun_cookies.domain_match/index.html create mode 100644 docs/en/gun/2.0/manual/gun_cookies.path_match/index.html create mode 100644 docs/en/gun/2.0/manual/gun_cookies/index.html create mode 100644 docs/en/gun/2.0/manual/gun_cookies_list/index.html (limited to 'docs/en') diff --git a/docs/en/cowlib/2.8/manual/cow_cookie.parse_cookie/index.html b/docs/en/cowlib/2.8/manual/cow_cookie.parse_cookie/index.html index 25e3b2cc..cfb7dabe 100644 --- a/docs/en/cowlib/2.8/manual/cow_cookie.parse_cookie/index.html +++ b/docs/en/cowlib/2.8/manual/cow_cookie.parse_cookie/index.html @@ -128,6 +128,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.9
  • +
  • 2.8
  • diff --git a/docs/en/cowlib/2.8/manual/cow_cookie.setcookie/index.html b/docs/en/cowlib/2.8/manual/cow_cookie.setcookie/index.html index 090481ac..9c12c18d 100644 --- a/docs/en/cowlib/2.8/manual/cow_cookie.setcookie/index.html +++ b/docs/en/cowlib/2.8/manual/cow_cookie.setcookie/index.html @@ -138,6 +138,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.9
  • +
  • 2.8
  • diff --git a/docs/en/cowlib/2.8/manual/cow_cookie/index.html b/docs/en/cowlib/2.8/manual/cow_cookie/index.html index 1b8a3a40..6ab9cda6 100644 --- a/docs/en/cowlib/2.8/manual/cow_cookie/index.html +++ b/docs/en/cowlib/2.8/manual/cow_cookie/index.html @@ -143,6 +143,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.9
  • +
  • 2.8
  • diff --git a/docs/en/cowlib/2.8/manual/cowlib_app/index.html b/docs/en/cowlib/2.8/manual/cowlib_app/index.html index 2251b562..75322d42 100644 --- a/docs/en/cowlib/2.8/manual/cowlib_app/index.html +++ b/docs/en/cowlib/2.8/manual/cowlib_app/index.html @@ -119,6 +119,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.9
  • +
  • 2.8
  • diff --git a/docs/en/cowlib/2.8/manual/index.html b/docs/en/cowlib/2.8/manual/index.html index 57057316..587d783f 100644 --- a/docs/en/cowlib/2.8/manual/index.html +++ b/docs/en/cowlib/2.8/manual/index.html @@ -119,6 +119,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.9
  • +
  • 2.8
  • diff --git a/docs/en/cowlib/2.9/manual/cow_cookie.cookie/index.html b/docs/en/cowlib/2.9/manual/cow_cookie.cookie/index.html new file mode 100644 index 00000000..c18b41a4 --- /dev/null +++ b/docs/en/cowlib/2.9/manual/cow_cookie.cookie/index.html @@ -0,0 +1,182 @@ + + + + + + + + + + Nine Nines: cow_cookie:cookie(3) + + + + + + + + + + + + + + + + +
    +
    +
    +
    + +

    cow_cookie:cookie(3)

    + +

    Name

    +

    cow_cookie:cookie - Generate a cookie header

    +

    Description

    +
    +
    cookie(Cookies) -> iolist()
    +
    +Cookies :: [{Name :: iodata(), Value :: iodata()}]
    +
    +

    Generate a cookie header.

    +

    Arguments

    +
    Cookies
    +

    A list of pairs of cookie name and value.

    +
    +
    +

    Return value

    +

    An iolist with the generated cookie header value.

    +

    Changelog

    +
    • 2.9: Function introduced. +
    • +
    +

    Examples

    +
    Generate a cookie header
    +
    +
    Cookie = cow_cookie:cookie([{<<"sessionid">>, ID}]).
    +
    +

    See also

    +

    cow_cookie(3), cow_cookie:parse_cookie(3), cow_cookie:parse_set_cookie(3), cow_cookie:setcookie(3)

    + + + + + + +
    + +
    + + +

    + Cowlib + 2.9 + Function Reference + +

    + + + +

    Navigation

    + +

    Version select

    + + +

    Like my work? Donate!

    +

    Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

    +
    + + + + + + + + + +

    Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

    + + + +
    +
    +
    +
    + + + + + + + + + diff --git a/docs/en/cowlib/2.9/manual/cow_cookie.parse_cookie/index.html b/docs/en/cowlib/2.9/manual/cow_cookie.parse_cookie/index.html new file mode 100644 index 00000000..089b5599 --- /dev/null +++ b/docs/en/cowlib/2.9/manual/cow_cookie.parse_cookie/index.html @@ -0,0 +1,184 @@ + + + + + + + + + + Nine Nines: cow_cookie:parse_cookie(3) + + + + + + + + + + + + + + + + +
    +
    +
    +
    + +

    cow_cookie:parse_cookie(3)

    + +

    Name

    +

    cow_cookie:parse_cookie - Parse a cookie header

    +

    Description

    +
    +
    parse_cookie(Cookie :: binary())
    +    -> [{binary(), binary()}]
    +
    +

    Parse a cookie header.

    +

    Arguments

    +
    Cookie
    +

    The cookie header value.

    +
    +
    +

    Return value

    +

    A list of cookie name/value pairs is returned on success.

    +

    An exception is thrown in the event of a parse error.

    +

    Changelog

    +
    • 2.9: Fixes to the parser may lead to potential incompatibilities. A cookie name starting with $ is no longer ignored. A cookie without a = will be parsed as the value of the cookie named <<>> (empty name). +
    • +
    • 1.0: Function introduced. +
    • +
    +

    Examples

    +
    Parse a cookie header
    +
    +
    Cookies = cow_cookie:parse_cookie(CookieHd).
    +
    +

    See also

    +

    cow_cookie(3), cow_cookie:parse_set_cookie(3), cow_cookie:cookie(3), cow_cookie:setcookie(3)

    + + + + + + +
    + +
    + + +

    + Cowlib + 2.9 + Function Reference + +

    + + + +

    Navigation

    + +

    Version select

    + + +

    Like my work? Donate!

    +

    Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

    +
    + + + + + + + + + +

    Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

    + + + +
    +
    +
    +
    + + + + + + + + + diff --git a/docs/en/cowlib/2.9/manual/cow_cookie.parse_set_cookie/index.html b/docs/en/cowlib/2.9/manual/cow_cookie.parse_set_cookie/index.html new file mode 100644 index 00000000..ec50d655 --- /dev/null +++ b/docs/en/cowlib/2.9/manual/cow_cookie.parse_set_cookie/index.html @@ -0,0 +1,191 @@ + + + + + + + + + + Nine Nines: cow_cookie:parse_set_cookie(3) + + + + + + + + + + + + + + + + +
    +
    +
    +
    + +

    cow_cookie:parse_set_cookie(3)

    + +

    Name

    +

    cow_cookie:parse_set_cookie - Parse a set-cookie header

    +

    Description

    +
    +
    parse_set_cookie(SetCookie :: binary())
    +    -> {ok, Name, Value, Attrs} | ignore
    +
    +Name  :: binary()
    +Value :: binary()
    +Attrs :: cow_cookie:cookie_attrs()
    +
    +

    Parse a set-cookie header.

    +

    Arguments

    +
    SetCookie
    +

    The set-cookie header value.

    +
    +
    +

    Return value

    +

    An ok tuple with the cookie name, value and attributes is returned on success.

    +

    An atom ignore is returned when the cookie has both an empty name and an empty value, and must be ignored.

    +

    Changelog

    +
    • 2.9: Function introduced. +
    • +
    +

    Examples

    +
    Parse a cookie header
    +
    +
    case cow_cookie:parse_set_cookie(SetCookieHd) of
    +    {ok, Name, Value, Attrs} ->
    +        cookie_engine_set_cookie(Name, Value, Attrs);
    +    ignore ->
    +        do_nothing()
    +end.
    +
    +

    See also

    +

    cow_cookie(3), cow_cookie:parse_cookie(3), cow_cookie:cookie(3), cow_cookie:setcookie(3)

    + + + + + + +
    + +
    + + +

    + Cowlib + 2.9 + Function Reference + +

    + + + +

    Navigation

    + +

    Version select

    + + +

    Like my work? Donate!

    +

    Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

    +
    + + + + + + + + + +

    Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

    + + + +
    +
    +
    +
    + + + + + + + + + diff --git a/docs/en/cowlib/2.9/manual/cow_cookie.setcookie/index.html b/docs/en/cowlib/2.9/manual/cow_cookie.setcookie/index.html new file mode 100644 index 00000000..1e68718d --- /dev/null +++ b/docs/en/cowlib/2.9/manual/cow_cookie.setcookie/index.html @@ -0,0 +1,192 @@ + + + + + + + + + + Nine Nines: cow_cookie:setcookie(3) + + + + + + + + + + + + + + + + +
    +
    +
    +
    + +

    cow_cookie:setcookie(3)

    + +

    Name

    +

    cow_cookie:setcookie - Generate a set-cookie header

    +

    Description

    +
    +
    setcookie(Name  :: iodata(),
    +          Value :: iodata(),
    +          Opts  :: cow_cookie:cookie_opts())
    +    -> iolist()
    +
    +

    Generate a set-cookie header.

    +

    Arguments

    +
    Name
    +

    Cookie name.

    +
    +
    Value
    +

    Cookie value.

    +
    +
    Opts
    +

    Options added to the set-cookie header as attributes.

    +
    +
    +

    Return value

    +

    An iolist with the generated set-cookie header value.

    +

    Changelog

    +
    • 1.0: Function introduced. +
    • +
    +

    Examples

    +
    Generate a set-cookie header
    +
    +
    SetCookie = cow_cookie:setcookie(<<"sessionid">>, ID, #{
    +    http_only => true,
    +    secure    => true
    +}).
    +
    +

    See also

    +

    cow_cookie(3), cow_cookie:parse_cookie(3), cow_cookie:parse_set_cookie(3), cow_cookie:cookie(3)

    + + + + + + +
    + +
    + + +

    + Cowlib + 2.9 + Function Reference + +

    + + + +

    Navigation

    + +

    Version select

    + + +

    Like my work? Donate!

    +

    Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

    +
    + + + + + + + + + +

    Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

    + + + +
    +
    +
    +
    + + + + + + + + + diff --git a/docs/en/cowlib/2.9/manual/cow_cookie/index.html b/docs/en/cowlib/2.9/manual/cow_cookie/index.html new file mode 100644 index 00000000..ccfb687b --- /dev/null +++ b/docs/en/cowlib/2.9/manual/cow_cookie/index.html @@ -0,0 +1,223 @@ + + + + + + + + + + Nine Nines: cow_cookie(3) + + + + + + + + + + + + + + + + +
    +
    +
    +
    + +

    cow_cookie(3)

    + +

    Name

    +

    cow_cookie - Cookies

    +

    Description

    +

    The module cow_cookie provides functions for parsing and manipulating cookie headers.

    +

    Exports

    + +

    Types

    + +
    +
    cookie_attrs() :: #{
    +    expires => calendar:datetime(),
    +    max_age => calendar:datetime(),
    +    domain => binary(),
    +    path => binary(),
    +    secure => true,
    +    http_only => true,
    +    same_site => strict | lax
    +}
    +
    +

    Cookie attributes parsed from the set-cookie header. The attributes must be passed as-is to a cookie store engine for processing, along with the cookie name and value. More information about the attributes can be found in RFC 6265.

    + +
    +
    cookie_opts() :: #{
    +    domain    => binary(),
    +    http_only => boolean(),
    +    max_age   => non_neg_integer(),
    +    path      => binary(),
    +    same_site => lax | strict,
    +    secure    => boolean()
    +}
    +
    +

    Options for the set-cookie header. They are added to the header as attributes. More information about the options can be found in RFC 6265.

    +

    The following options are defined:

    +
    domain
    +

    Hosts to which the cookie will be sent. By default it will only be sent to the origin server.

    +
    +
    http_only
    +

    Whether the cookie should be restricted to HTTP requests, or it should also be exposed to other APIs, for example Javascript. By default there are no restrictions.

    +
    +
    max_age
    +

    Maximum lifetime of the cookie, in seconds. By default the cookie is kept for the duration of the session.

    +
    +
    path
    +

    Path to which the cookie will be sent. By default it will be sent to the current "directory" of the effective request URI.

    +
    +
    same_site
    +

    Whether the cookie should be sent along with cross-site requests. This header is currently non-standard but is in the process of being standardized. Please refer to the RFC 6265 (bis) draft for details.

    +
    +
    secure
    +

    Whether the cookie should be sent only on secure channels (for example TLS). Note that this does not guarantee the integrity of the cookie, only its confidentiality during transfer. By default there are no restrictions.

    +
    +
    +

    Changelog

    +
    • 2.9: The cookie_attrs type was added. +
    • +
    • 1.0: Module introduced. +
    • +
    +

    See also

    +

    cowlib(7), RFC 6265

    + + + + + + +
    + +
    + + +

    + Cowlib + 2.9 + Function Reference + +

    + + + +

    Navigation

    + +

    Version select

    + + +

    Like my work? Donate!

    +

    Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

    +
    + + + + + + + + + +

    Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

    + + + +
    +
    +
    +
    + + + + + + + + + diff --git a/docs/en/cowlib/2.9/manual/cowlib_app/index.html b/docs/en/cowlib/2.9/manual/cowlib_app/index.html new file mode 100644 index 00000000..1c43ad84 --- /dev/null +++ b/docs/en/cowlib/2.9/manual/cowlib_app/index.html @@ -0,0 +1,173 @@ + + + + + + + + + + Nine Nines: cowlib(7) + + + + + + + + + + + + + + + + +
    +
    +
    +
    + +

    cowlib(7)

    + +

    Name

    +

    cowlib - Support library for manipulating Web protocols

    +

    Description

    +

    Cowlib provides libraries for parsing and building messages for various Web protocols, including HTTP/1.1, HTTP/2 and Websocket.

    +

    It is optimized for completeness rather than speed. No value is ignored, they are all returned.

    +

    Modules

    + +

    Dependencies

    +
    • crypto - Crypto functions +
    • +
    +

    All these applications must be started before the cowlib application. To start Cowlib and all dependencies at once:

    +
    +
    {ok, _} = application:ensure_all_started(cowlib).
    +
    +

    Environment

    +

    The cowlib application does not define any application environment configuration parameters.

    +

    See also

    +

    cowboy(7), gun(7)

    + + + + + + +
    + +
    + + +

    + Cowlib + 2.9 + Function Reference + +

    + + + +

    Navigation

    + +

    Version select

    + + +

    Like my work? Donate!

    +

    Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

    +
    + + + + + + + + + +

    Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

    + + + +
    +
    +
    +
    + + + + + + + + + diff --git a/docs/en/cowlib/2.9/manual/index.html b/docs/en/cowlib/2.9/manual/index.html new file mode 100644 index 00000000..33e04ecc --- /dev/null +++ b/docs/en/cowlib/2.9/manual/index.html @@ -0,0 +1,173 @@ + + + + + + + + + + Nine Nines: Cowlib Function Reference + + + + + + + + + + + + + + + + +
    +
    +
    +
    + +

    Cowlib Function Reference

    + +

    Name

    +

    cowlib - Support library for manipulating Web protocols

    +

    Description

    +

    Cowlib provides libraries for parsing and building messages for various Web protocols, including HTTP/1.1, HTTP/2 and Websocket.

    +

    It is optimized for completeness rather than speed. No value is ignored, they are all returned.

    +

    Modules

    + +

    Dependencies

    +
    • crypto - Crypto functions +
    • +
    +

    All these applications must be started before the cowlib application. To start Cowlib and all dependencies at once:

    +
    +
    {ok, _} = application:ensure_all_started(cowlib).
    +
    +

    Environment

    +

    The cowlib application does not define any application environment configuration parameters.

    +

    See also

    +

    cowboy(7), gun(7)

    + + + + + + +
    + +
    + + +

    + Cowlib + 2.9 + Function Reference + +

    + + + +

    Navigation

    + +

    Version select

    + + +

    Like my work? Donate!

    +

    Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

    +
    + + + + + + + + + +

    Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

    + + + +
    +
    +
    +
    + + + + + + + + + diff --git a/docs/en/gun/2.0/guide/introduction.asciidoc b/docs/en/gun/2.0/guide/introduction.asciidoc index dfbe1e30..a54a8d1d 100644 --- a/docs/en/gun/2.0/guide/introduction.asciidoc +++ b/docs/en/gun/2.0/guide/introduction.asciidoc @@ -14,13 +14,7 @@ protocols is required in order to read this guide. Gun is tested and supported on Linux, FreeBSD, Windows and OSX. -Gun is developed for Erlang/OTP 20.0 and newer. - -Note that Gun will not work on the Windows build of Erlang/OTP 20.3 -due to a bug in Erlang/OTP's stdlib application. The ticket number -for this bug is OTP-13995 and it was fixed in the patch release -OTP-20.3.2. Replacing the `gen_statem.beam` file on an 20.3 -installation is enough to fix the issue. +Gun is developed for Erlang/OTP 22.0 and newer. === License diff --git a/docs/en/gun/2.0/guide/introduction/index.html b/docs/en/gun/2.0/guide/introduction/index.html index 1b833e46..6f8f0006 100644 --- a/docs/en/gun/2.0/guide/introduction/index.html +++ b/docs/en/gun/2.0/guide/introduction/index.html @@ -68,8 +68,7 @@

    Knowledge of Erlang, but also of the HTTP/1.1, HTTP/2 and Websocket protocols is required in order to read this guide.

    Supported platforms

    Gun is tested and supported on Linux, FreeBSD, Windows and OSX.

    -

    Gun is developed for Erlang/OTP 20.0 and newer.

    -

    Note that Gun will not work on the Windows build of Erlang/OTP 20.3 due to a bug in Erlang/OTP's stdlib application. The ticket number for this bug is OTP-13995 and it was fixed in the patch release OTP-20.3.2. Replacing the gen_statem.beam file on an 20.3 installation is enough to fix the issue.

    +

    Gun is developed for Erlang/OTP 22.0 and newer.

    License

    Gun uses the ISC License.

    Copyright (c) 2013-2019, Loïc Hoguin <essen@ninenines.eu>
    diff --git a/docs/en/gun/2.0/guide/migrating_from_1.3.asciidoc b/docs/en/gun/2.0/guide/migrating_from_1.3.asciidoc
    index 1e2b8943..a20a0582 100644
    --- a/docs/en/gun/2.0/guide/migrating_from_1.3.asciidoc
    +++ b/docs/en/gun/2.0/guide/migrating_from_1.3.asciidoc
    @@ -19,10 +19,21 @@ much more advanced.
     
     The Gun connection process is now implemented using `gen_statem`.
     
    -Gun 2.0 requires Erlang/OTP 20.0 or greater.
    +Gun 2.0 requires Erlang/OTP 22.0 or greater.
     
     === Features added
     
    +* Cookie store support has been added. The `cookie_store`
    +  option allows configuring the cookie store backend.
    +  The `gun_cookies` module provides functions to help
    +  implementing such a backend. Gun comes with the backend
    +  `gun_cookies_list` which provides a per-connection,
    +  non-persistent cookie store. The cookie store engine
    +  implements the entire RFC6265bis draft algorithms except
    +  the parts about non-HTTP cookies as no such interface is
    +  provided; and the parts about SameSite as Gun has no
    +  concept of "browsing context".
    +
     * Graceful shutdown has been implemented. Graceful shutdown
       can be initiated on the client side by calling the new
       function `gun:shutdown/1` or when the owner process goes
    @@ -76,8 +87,7 @@ Gun 2.0 requires Erlang/OTP 20.0 or greater.
       for any sort of protocols. This can also be useful
       when performing HTTP/1.1 Upgrade to custom protocols.
     
    -* Headers can now be provided as a map. Header names may now
    -  be provided as binary, string or atom.
    +* Headers can now be provided as a map.
     
     * Header names may now be provided as binary, string or atom.
     
    @@ -218,3 +228,21 @@ Gun 2.0 requires Erlang/OTP 20.0 or greater.
     
     * An invalid stream reference was sent on failed Websocket
       upgrade responses. This has been corrected.
    +
    +* HTTP/2 connection preface errors are now properly detected
    +  and propagated in the `gun_down` message to the connection
    +  owner as well as the exit reason of the Gun process.
    +
    +* HTTP/2 connection preface errors now provide a different
    +  human readable error when the data received looks like an
    +  HTTP/1.x response.
    +
    +* HTTP/2 connection errors were missing the human readable
    +  reason in the `gun_error` message. This has been corrected.
    +
    +* Fix the host and :authority (pseudo-)headers when connecting
    +  to an IPv6 address given as a tuple. They were lacking the
    +  surrounding brackets.
    +
    +* Fix a crash in gun:info/1 when the socket was closed before
    +  we call Transport:sockname/1.
    diff --git a/docs/en/gun/2.0/guide/migrating_from_1.3/index.html b/docs/en/gun/2.0/guide/migrating_from_1.3/index.html
    index de7015dc..6d9a22a9 100644
    --- a/docs/en/gun/2.0/guide/migrating_from_1.3/index.html
    +++ b/docs/en/gun/2.0/guide/migrating_from_1.3/index.html
    @@ -66,9 +66,11 @@
     

    Gun 2.0 greatly improves the HTTP/2 performance when it comes to receiving large response bodies; and when receiving response bodies from many separate requests concurrently.

    Gun now shares much of its HTTP/2 code with Cowboy, including the HTTP/2 state machine. Numerous issues were fixed as a result because the Cowboy implementation was much more advanced.

    The Gun connection process is now implemented using gen_statem.

    -

    Gun 2.0 requires Erlang/OTP 20.0 or greater.

    +

    Gun 2.0 requires Erlang/OTP 22.0 or greater.

    Features added

    -
    • Graceful shutdown has been implemented. Graceful shutdown can be initiated on the client side by calling the new function gun:shutdown/1 or when the owner process goes away; or on the peer side via the connection: close HTTP/1.1 header, the HTTP/2 GOAWAY frame or the Websocket close frame. Gun will try to complete existing streams when possible; other streams get canceled immediately. The closing_timeout option controls how long we are willing to wait at most before closing the connection. +
      • Cookie store support has been added. The cookie_store option allows configuring the cookie store backend. The gun_cookies module provides functions to help implementing such a backend. Gun comes with the backend gun_cookies_list which provides a per-connection, non-persistent cookie store. The cookie store engine implements the entire RFC6265bis draft algorithms except the parts about non-HTTP cookies as no such interface is provided; and the parts about SameSite as Gun has no concept of "browsing context". +
      • +
      • Graceful shutdown has been implemented. Graceful shutdown can be initiated on the client side by calling the new function gun:shutdown/1 or when the owner process goes away; or on the peer side via the connection: close HTTP/1.1 header, the HTTP/2 GOAWAY frame or the Websocket close frame. Gun will try to complete existing streams when possible; other streams get canceled immediately. The closing_timeout option controls how long we are willing to wait at most before closing the connection.
      • Flow control has been added. It allows limiting the number of data/Websocket messages Gun sends to the calling process. Gun will stop reading from the socket or stop updating the protocol's flow control window when applicable as well, to apply some backpressure to the remote endpoint(s). It is disabled by default and can be applied on a per-request basis if necessary.
      • @@ -84,7 +86,7 @@
      • Gun can now be used to send and receive raw data, as if it was just a normal socket. This can be useful when needing to connect through a number of HTTP/Socks proxies, allowing the use of Gun's great proxying capabilities (including TLS over TLS) for any sort of protocols. This can also be useful when performing HTTP/1.1 Upgrade to custom protocols.
      • -
      • Headers can now be provided as a map. Header names may now be provided as binary, string or atom. +
      • Headers can now be provided as a map.
      • Header names may now be provided as binary, string or atom.
      • @@ -166,6 +168,16 @@
      • An invalid stream reference was sent on failed Websocket upgrade responses. This has been corrected.
      • +
      • HTTP/2 connection preface errors are now properly detected and propagated in the gun_down message to the connection owner as well as the exit reason of the Gun process. +
      • +
      • HTTP/2 connection preface errors now provide a different human readable error when the data received looks like an HTTP/1.x response. +
      • +
      • HTTP/2 connection errors were missing the human readable reason in the gun_error message. This has been corrected. +
      • +
      • Fix the host and :authority (pseudo-)headers when connecting to an IPv6 address given as a tuple. They were lacking the surrounding brackets. +
      • +
      • Fix a crash in gun:info/1 when the socket was closed before we call Transport:sockname/1. +
      diff --git a/docs/en/gun/2.0/manual/gun.info/index.html b/docs/en/gun/2.0/manual/gun.info/index.html index 4721d81f..6fbaaf8b 100644 --- a/docs/en/gun/2.0/manual/gun.info/index.html +++ b/docs/en/gun/2.0/manual/gun.info/index.html @@ -81,7 +81,8 @@ http://www.gnu.org/software/src-highlite --> sock_port => inet:port_number(), origin_host => inet:hostname() | inet:ip_address(), origin_port => inet:port_number(), - intermediaries => [Intermediary] + intermediaries => [Intermediary], + cookie_store => gun_cookies:cookie_store() } Intermediary :: #{ type => connect | socks5, @@ -100,7 +101,7 @@ http://www.gnu.org/software/src-highlite -->

      Return value

      A map is returned containing various informations about the connection.

      Changelog

      -
      • 2.0: The value owner was added. +
        • 2.0: The values owner and cookie_store were added.
        • 1.3: The values socket, transport, protocol, origin_host, origin_port and intermediaries were added.
        • diff --git a/docs/en/gun/2.0/manual/gun/index.html b/docs/en/gun/2.0/manual/gun/index.html index a59704f5..2ee49896 100644 --- a/docs/en/gun/2.0/manual/gun/index.html +++ b/docs/en/gun/2.0/manual/gun/index.html @@ -286,6 +286,7 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->
          opts() :: #{
               connect_timeout       => timeout(),
          +    cookie_store          => gun_cookies:store(),
               domain_lookup_timeout => timeout(),
               http_opts             => http_opts(),
               http2_opts            => http2_opts(),
          @@ -307,6 +308,10 @@ http://www.gnu.org/software/src-highlite -->
           
          connect_timeout (infinity)

          Connection timeout.

          +
          cookie_store - see below
          +

          The cookie store that Gun will use for this connection. When configured, Gun will query the store for cookies and include them in the request headers; and add cookies found in response headers to the store.

          +

          By default no cookie store will be used.

          +
          domain_lookup_timeout (infinity)

          Domain lookup timeout.

          @@ -484,7 +489,9 @@ http://www.gnu.org/software/src-highlite -->

          Changelog

          -
          • 2.0: The types protocols() and socks_opts() have been added. Support for the Socks protocol has been added in every places where protocol selection is available. In addition it is now possible to specify separate HTTP options for the CONNECT proxy and the origin server. +
            • 2.0: The option cookie_store was added. It can be used to configure a cookie store that Gun will use automatically. +
            • +
            • 2.0: The types protocols() and socks_opts() have been added. Support for the Socks protocol has been added in every places where protocol selection is available. In addition it is now possible to specify separate HTTP options for the CONNECT proxy and the origin server.
            • 2.0: The connect_timeout option has been split into three options: domain_lookup_timeout, connect_timeout and when applicable tls_handshake_timeout.
            • diff --git a/docs/en/gun/2.0/manual/gun_app/index.html b/docs/en/gun/2.0/manual/gun_app/index.html index cc05d96c..128f9228 100644 --- a/docs/en/gun/2.0/manual/gun_app/index.html +++ b/docs/en/gun/2.0/manual/gun_app/index.html @@ -70,6 +70,10 @@

              Modules

              Dependencies

              • cowlib(7) - Support library for manipulating Web protocols diff --git a/docs/en/gun/2.0/manual/gun_cookies.domain_match/index.html b/docs/en/gun/2.0/manual/gun_cookies.domain_match/index.html new file mode 100644 index 00000000..a67600e6 --- /dev/null +++ b/docs/en/gun/2.0/manual/gun_cookies.domain_match/index.html @@ -0,0 +1,195 @@ + + + + + + + + + + Nine Nines: gun_cookies:domain_match(3) + + + + + + + + + + + + + + + + +
                +
                +
                +
                + +

                gun_cookies:domain_match(3)

                + +

                Name

                +

                gun_cookies:domain_match - Cookie domain match

                +

                Description

                +
                +
                domain_match(String, DomainString) -> boolean()
                +
                +String       :: binary()
                +DomainString :: binary()
                +
                +

                Cookie domain match.

                +

                This function can be used when implementing the set_cookie_secure_match callback of a cookie store.

                +

                Arguments

                +
                String
                +

                The string to match.

                +
                +
                DomainString
                +

                The domain string that will be matched against.

                +
                +
                +

                Return value

                +

                Returns true when String domain-matches DomainString, and false otherwise.

                +

                Changelog

                +
                • 2.0: Function introduced. +
                • +
                +

                Examples

                +
                Perform a domain match
                +
                +
                Match = gun_cookies:domain_match(Domain, CookieDomain).
                +
                +

                See also

                +

                gun_cookies(3), gun_cookies:path_match(3)

                + + + + + + +
                + +
                + + +

                + Gun + 2.0 + Function Reference + +

                + + + +

                Navigation

                + +

                Version select

                + + +

                Like my work? Donate!

                +

                Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

                +
                + + + + + + + + + +

                Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

                + + + +
                +
                +
                +
                + + + + + + + + + diff --git a/docs/en/gun/2.0/manual/gun_cookies.path_match/index.html b/docs/en/gun/2.0/manual/gun_cookies.path_match/index.html new file mode 100644 index 00000000..930286a7 --- /dev/null +++ b/docs/en/gun/2.0/manual/gun_cookies.path_match/index.html @@ -0,0 +1,195 @@ + + + + + + + + + + Nine Nines: gun_cookies:path_match(3) + + + + + + + + + + + + + + + + +
                +
                +
                +
                + +

                gun_cookies:path_match(3)

                + +

                Name

                +

                gun_cookies:path_match - Cookie path match

                +

                Description

                +
                +
                path_match(ReqPath, CookiePath) -> boolean()
                +
                +ReqPath    :: binary()
                +CookiePath :: binary()
                +
                +

                Cookie path match.

                +

                This function can be used when implementing the set_cookie_secure_match callback of a cookie store.

                +

                Arguments

                +
                ReqPath
                +

                The request path to match.

                +
                +
                CookiePath
                +

                The cookie path that will be matched against.

                +
                +
                +

                Return value

                +

                Returns true when ReqPath path-matches CookiePath, and false otherwise.

                +

                Changelog

                +
                • 2.0: Function introduced. +
                • +
                +

                Examples

                +
                Perform a path match
                +
                +
                Match = gun_cookies:path_match(ReqPath, CookiePath).
                +
                +

                See also

                +

                gun_cookies(3), gun_cookies:domain_match(3)

                + + + + + + +
                + +
                + + +

                + Gun + 2.0 + Function Reference + +

                + + + +

                Navigation

                + +

                Version select

                + + +

                Like my work? Donate!

                +

                Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

                +
                + + + + + + + + + +

                Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

                + + + +
                +
                +
                +
                + + + + + + + + + diff --git a/docs/en/gun/2.0/manual/gun_cookies/index.html b/docs/en/gun/2.0/manual/gun_cookies/index.html new file mode 100644 index 00000000..4d75dab8 --- /dev/null +++ b/docs/en/gun/2.0/manual/gun_cookies/index.html @@ -0,0 +1,294 @@ + + + + + + + + + + Nine Nines: gun_cookies(3) + + + + + + + + + + + + + + + + +
                +
                +
                +
                + +

                gun_cookies(3)

                + +

                Name

                +

                gun_cookies - Cookie store engine

                +

                Description

                +

                The gun_cookies module implements a cookie store engine. It will be used by Gun when a cookie store is configured. It also defines the interface and provides functions used to implement cookie store backends.

                +

                Callbacks

                +

                Cookie store backends implement the following interface. Functions are organized by theme: initialization, querying, storing and garbage collecting:

                +

                init

                +
                +
                init(Opts :: any()) -> gun_cookies:store()
                +
                +

                Initialize the cookie store.

                +

                query

                +
                +
                query(State, URI) -> {ok, [Cookie], State}
                +
                +URI    :: uri_string:uri_map()
                +Cookie :: gun_cookies:cookie()
                +State  :: any()
                +
                +

                Query the store for the cookies for the given URI.

                + +
                +
                set_cookie_secure_match(State, Match) -> match | nomatch
                +
                +State :: any()
                +Match :: #{
                +    name := binary(),
                +%	secure_only := true,
                +    domain := binary(),
                +    path := binary()
                +}
                +
                +

                Perform a secure match against cookies already in the store. This is part of the heuristics that the cookie store engine applies to decide whether the cookie must be stored.

                +

                The secure_only attribute is implied, it is not actually passed in the argument.

                + +
                +
                set_cookie_get_exact_match(State, Match)
                +    -> {ok, gun_cookies:cookie(), State} | error
                +
                +State :: any()
                +Match :: #{
                +	name := binary(),
                +	domain := binary(),
                +	host_only := boolean(),
                +	path := binary()
                +}
                +
                +

                Perform an exact match against cookies already in the store. This is part of the heuristics that the cookie store engine applies to decide whether the cookie must be stored.

                +

                When a cookie is found, it must be returned so that it gets updated. When nothing is found a new cookie will be stored.

                +

                store

                +
                +
                store(State, gun_cookies:cookie())
                +	-> {ok, State} | {error, any()}
                +
                +State :: any()
                +
                +

                Unconditionally store the cookie into the cookie store.

                +

                gc

                +
                +
                gc(State) -> {ok, State}
                +
                +State :: any()
                +
                +

                Remove all cookies from the cookie store that are expired.

                +

                Other cookies may be removed as well, at the discretion of the cookie store. For example excess cookies may be removed to reduce the memory footprint.

                +

                session_gc

                +
                +
                session_gc(State) -> {ok, State}
                +
                +State :: any()
                +
                +

                Remove all cookies from the cookie store that have the persistent flag set to false.

                +

                Exports

                + +

                Types

                + +
                +
                cookie() :: #{
                +    name             := binary(),
                +    value            := binary(),
                +    domain           := binary(),
                +    path             := binary(),
                +    creation_time    := calendar:datetime(),
                +    last_access_time := calendar:datetime(),
                +    expiry_time      := calendar:datetime() | infinity,
                +    persistent       := boolean(),
                +    host_only        := boolean(),
                +    secure_only      := boolean(),
                +    http_only        := boolean(),
                +    same_site        := strict | lax | none
                +}
                +
                +

                A cookie.

                +

                This contains the cookie name, value, attributes and flags. This is the representation that the cookie store engine and Gun expects. Cookies do not have to be kept in this format in the cookie store backend.

                +

                store()

                +
                +
                store() :: {module(), StoreState :: any()}
                +
                +

                The cookie store.

                +

                This is a tuple containing the cookie store backend module and its current state.

                +

                Changelog

                +
                • 2.0: Module introduced. +
                • +
                +

                See also

                +

                gun(7), gun_cookies_list(3)

                + + + + + + +
                + +
                + + +

                + Gun + 2.0 + Function Reference + +

                + + + +

                Navigation

                + +

                Version select

                + + +

                Like my work? Donate!

                +

                Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

                +
                + + + + + + + + + +

                Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

                + + + +
                +
                +
                +
                + + + + + + + + + diff --git a/docs/en/gun/2.0/manual/gun_cookies_list/index.html b/docs/en/gun/2.0/manual/gun_cookies_list/index.html new file mode 100644 index 00000000..c7eea531 --- /dev/null +++ b/docs/en/gun/2.0/manual/gun_cookies_list/index.html @@ -0,0 +1,192 @@ + + + + + + + + + + Nine Nines: gun_cookies_list(3) + + + + + + + + + + + + + + + + +
                +
                +
                +
                + +

                gun_cookies_list(3)

                + +

                Name

                +

                gun_cookies_list - Cookie store backend: in-memory, per connection

                +

                Description

                +

                The gun_cookies_list module implements a cookie store backend that keeps all the cookie data in-memory and tied to a specific connection.

                +

                It is possible to implement a custom backend on top of gun_cookies_list in order to add persistence or sharing properties.

                +

                Exports

                +

                This module implements the callbacks defined in gun_cookies(3).

                +

                Types

                +

                opts()

                +
                +
                opts() :: #{
                +}
                +
                +

                Cookie store backend options.

                +

                There are currently no options available for this backend.

                + +

                Changelog

                +
                • 2.0: Module introduced. +
                • +
                +

                Examples

                +
                Open a connection with a cookie store configured
                +
                +
                {ok, ConnPid} = gun:open(Host, Port, #{
                +    cookie_store => gun_cookies_list:init(#{})
                +})
                +
                +

                See also

                +

                gun(7), gun_cookies(3)

                + + + + + + +
                + +
                + + +

                + Gun + 2.0 + Function Reference + +

                + + + +

                Navigation

                + +

                Version select

                + + +

                Like my work? Donate!

                +

                Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

                +
                + + + + + + + + + +

                Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

                + + + +
                +
                +
                +
                + + + + + + + + + diff --git a/docs/en/gun/2.0/manual/index.html b/docs/en/gun/2.0/manual/index.html index 0816163a..70ff07c7 100644 --- a/docs/en/gun/2.0/manual/index.html +++ b/docs/en/gun/2.0/manual/index.html @@ -70,6 +70,10 @@

                Modules

                Dependencies

                • cowlib(7) - Support library for manipulating Web protocols diff --git a/docs/en/ranch/2.0/guide/internals.asciidoc b/docs/en/ranch/2.0/guide/internals.asciidoc index c5bde58f..600920fc 100644 --- a/docs/en/ranch/2.0/guide/internals.asciidoc +++ b/docs/en/ranch/2.0/guide/internals.asciidoc @@ -10,6 +10,11 @@ matter to you. Generic benchmarks found on the web may or may not be of use to you, you can never know until you benchmark your own system. +A third party dive into the internals of Ranch is available should +you be interested: https://baozi.technology/ranch-under-the-hood/[Ranch: what's under the hood?] +We make no claims with regard to its freshness or accuracy but this +is a nice document to read along this section. + === Architecture Ranch is an OTP application. diff --git a/docs/en/ranch/2.0/guide/internals/index.html b/docs/en/ranch/2.0/guide/internals/index.html index 936a4c41..ca802f1f 100644 --- a/docs/en/ranch/2.0/guide/internals/index.html +++ b/docs/en/ranch/2.0/guide/internals/index.html @@ -64,6 +64,7 @@

                  This chapter may not apply to embedded Ranch as embedding allows you to use an architecture specific to your application, which may or may not be compatible with the description of the Ranch application.

                  Note that for everything related to efficiency and performance, you should perform the benchmarks yourself to get the numbers that matter to you. Generic benchmarks found on the web may or may not be of use to you, you can never know until you benchmark your own system.

                  +

                  A third party dive into the internals of Ranch is available should you be interested: Ranch: what's under the hood? We make no claims with regard to its freshness or accuracy but this is a nice document to read along this section.

                  Architecture

                  Ranch is an OTP application.

                  Like all OTP applications, Ranch has a top supervisor. It is responsible for supervising the ranch_server process and all the listeners that will be started.

                  -- cgit v1.2.3