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 --- docs/index.xml | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 151 insertions(+), 5 deletions(-) (limited to 'docs/index.xml') diff --git a/docs/index.xml b/docs/index.xml index 622149bf..c18574d4 100644 --- a/docs/index.xml +++ b/docs/index.xml @@ -80,8 +80,9 @@ Copyright (c) 2013-2018, Loïc Hoguin <essen@ninenines.eu> Permiss Gun supports the HTTP/2, HTTP/1.1 and Websocket protocols. Prerequisites 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. +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> Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. @@ -3096,6 +3097,30 @@ Description The module cow_cookie provides functions for parsing and manipulatin Exports cow_cookie:parse_cookie(3) - Parse a cookie header cow_cookie:setcookie(3) - Generate a set-cookie header Types cookie_opts() 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. + + cow_cookie(3) + https://ninenines.eu/docs/en/cowlib/2.9/manual/cow_cookie/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/cowlib/2.9/manual/cow_cookie/ + Name cow_cookie - Cookies +Description The module cow_cookie provides functions for parsing and manipulating cookie headers. +Exports cow_cookie:parse_cookie(3) - Parse a cookie header cow_cookie:parse_set_cookie(3) - Parse a set-cookie header cow_cookie:cookie(3) - Generate a cookie header cow_cookie:setcookie(3) - Generate a set-cookie header Types cookie_attrs() 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. + + + + cow_cookie:cookie(3) + https://ninenines.eu/docs/en/cowlib/2.9/manual/cow_cookie.cookie/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/cowlib/2.9/manual/cow_cookie.cookie/ + 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) + + cow_cookie:parse_cookie(3) https://ninenines.eu/docs/en/cowlib/2.8/manual/cow_cookie.parse_cookie/ @@ -3110,6 +3135,33 @@ An exception is thrown in the event of a parse error. Changelog 1.0: Function introduced. Examples Parse a cookie header Cookies = cow_cookie:parse_cookie(CookieHd). See also cow_cookie(3), cow_cookie:setcookie(3) + + cow_cookie:parse_cookie(3) + https://ninenines.eu/docs/en/cowlib/2.9/manual/cow_cookie.parse_cookie/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/cowlib/2.9/manual/cow_cookie.parse_cookie/ + 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. + + + + cow_cookie:parse_set_cookie(3) + https://ninenines.eu/docs/en/cowlib/2.9/manual/cow_cookie.parse_set_cookie/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/cowlib/2.9/manual/cow_cookie.parse_set_cookie/ + 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. + + cow_cookie:setcookie(3) https://ninenines.eu/docs/en/cowlib/2.8/manual/cow_cookie.setcookie/ @@ -3125,6 +3177,21 @@ Arguments Name Cookie name. Changelog 1.0: Function introduced. Examples Generate a set-cookie header SetCookie = cow_cookie:setcookie(<<"sessionid">>, ID, #{ http_only => true, secure => true }). + + cow_cookie:setcookie(3) + https://ninenines.eu/docs/en/cowlib/2.9/manual/cow_cookie.setcookie/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/cowlib/2.9/manual/cow_cookie.setcookie/ + 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 }). + + Cowboy Function Reference https://ninenines.eu/docs/en/cowboy/2.2/manual/ @@ -8386,6 +8453,18 @@ It is optimized for completeness rather than speed. No value is ignored, they ar Modules cow_cookie(3) - Cookies Dependencies crypto - Crypto functions All these applications must be started before the cowlib application. To start Cowlib and all dependencies at once: + + Cowlib Function Reference + https://ninenines.eu/docs/en/cowlib/2.9/manual/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/cowlib/2.9/manual/ + 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 cow_cookie(3) - Cookies Dependencies crypto - Crypto functions All these applications must be started before the cowlib application. To start Cowlib and all dependencies at once: + + cowlib(7) https://ninenines.eu/docs/en/cowlib/2.8/manual/cowlib_app/ @@ -8398,6 +8477,18 @@ It is optimized for completeness rather than speed. No value is ignored, they ar Modules cow_cookie(3) - Cookies Dependencies crypto - Crypto functions All these applications must be started before the cowlib application. To start Cowlib and all dependencies at once: + + cowlib(7) + https://ninenines.eu/docs/en/cowlib/2.9/manual/cowlib_app/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/cowlib/2.9/manual/cowlib_app/ + 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 cow_cookie(3) - Cookies Dependencies crypto - Crypto functions All these applications must be started before the cowlib application. To start Cowlib and all dependencies at once: + + Gun Function Reference https://ninenines.eu/docs/en/gun/1.0/manual/ @@ -8455,7 +8546,7 @@ Modules gun(3) - Asynchronous HTTP client Dependencies cowlib(7) - Support lib Name gun - HTTP/1.1, HTTP/2 and Websocket client for Erlang/OTP Description Gun is an HTTP client for Erlang/OTP with support for the HTTP/1.1, HTTP/2 and Websocket protocols. Gun aims to provide an easy to use, asynchronous and always-connected client. It maintains a permanent connection to the server and reconnects automatically when necessary. -Modules gun(3) - Asynchronous HTTP client Dependencies cowlib(7) - Support library for manipulating Web protocols ssl - Secure communication over sockets All these applications must be started before the gun application. +Modules gun(3) - Asynchronous HTTP client gun_cookies(3) - Cookie store engine gun_cookies_list(3) - Cookie store backend: in-memory, per connection Dependencies cowlib(7) - Support library for manipulating Web protocols ssl - Secure communication over sockets All these applications must be started before the gun application. @@ -8620,7 +8711,7 @@ Modules gun(3) - Asynchronous HTTP client Dependencies cowlib(7) - Support lib Name gun - HTTP/1.1, HTTP/2 and Websocket client for Erlang/OTP Description Gun is an HTTP client for Erlang/OTP with support for the HTTP/1.1, HTTP/2 and Websocket protocols. Gun aims to provide an easy to use, asynchronous and always-connected client. It maintains a permanent connection to the server and reconnects automatically when necessary. -Modules gun(3) - Asynchronous HTTP client Dependencies cowlib(7) - Support library for manipulating Web protocols ssl - Secure communication over sockets All these applications must be started before the gun application. +Modules gun(3) - Asynchronous HTTP client gun_cookies(3) - Cookie store engine gun_cookies_list(3) - Cookie store backend: in-memory, per connection Dependencies cowlib(7) - Support library for manipulating Web protocols ssl - Secure communication over sockets All these applications must be started before the gun application. @@ -9330,7 +9421,7 @@ Description info(ConnPid) -> Info ConnPid :: pid() Info :: #{ socket =&am https://ninenines.eu/docs/en/gun/2.0/manual/gun.info/ Name gun:info - Obtain information about the connection -Description info(ConnPid) -> Info ConnPid :: pid() Info :: #{ owner => pid(), socket => inet:socket() | ssl:sslsocket(), transport => tcp | tls, protocol => http | http2 | socks | ws, sock_ip => inet:ip_address(), sock_port => inet:port_number(), origin_host => inet:hostname() | inet:ip_address(), origin_port => inet:port_number(), intermediaries => [Intermediary] } Intermediary :: #{ type => connect | socks5, host => inet:hostname() | inet:ip_address(), port => inet:port_number(), transport => tcp | tls, protocol => http | http2 | socks } Obtain information about the connection. +Description info(ConnPid) -> Info ConnPid :: pid() Info :: #{ owner => pid(), socket => inet:socket() | ssl:sslsocket(), transport => tcp | tls, protocol => http | http2 | socks | ws, sock_ip => inet:ip_address(), sock_port => inet:port_number(), origin_host => inet:hostname() | inet:ip_address(), origin_port => inet:port_number(), intermediaries => [Intermediary], cookie_store => gun_cookies:cookie_store() } Intermediary :: #{ type => connect | socks5, host => inet:hostname() | inet:ip_address(), port => inet:port_number(), transport => tcp | tls, protocol => http | http2 | socks } Obtain information about the connection. @@ -9915,6 +10006,61 @@ The behavior of this function depends on the protocol selected. HTTP/1.1 cannot handle Websocket and HTTP requests concurrently. The upgrade, if successful, will result in the complete takeover of the connection. + + gun_cookies(3) + https://ninenines.eu/docs/en/gun/2.0/manual/gun_cookies/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/gun/2.0/manual/gun_cookies/ + 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. + + + + gun_cookies:domain_match(3) + https://ninenines.eu/docs/en/gun/2.0/manual/gun_cookies.domain_match/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/gun/2.0/manual/gun_cookies.domain_match/ + 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). + + + + gun_cookies:path_match(3) + https://ninenines.eu/docs/en/gun/2.0/manual/gun_cookies.path_match/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/gun/2.0/manual/gun_cookies.path_match/ + 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). + + + + gun_cookies_list(3) + https://ninenines.eu/docs/en/gun/2.0/manual/gun_cookies_list/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://ninenines.eu/docs/en/gun/2.0/manual/gun_cookies_list/ + 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. + + gun_data(3) https://ninenines.eu/docs/en/gun/1.0/manual/gun_data/ -- cgit v1.2.3