Nine Nines: gun_cookies:domain

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
 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
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)
+
+    
+    
+
+    
+    
+    
+    
+
+    
+
+
+
+
+  
+    
+        
+          
+            99s
+          
+          
+            
+            
+              
+                
+                  Articles
+  				  Talks
+  				  Documentation
+  				  Consulting & Training
+                
+               
+              
+                
+                  
+                
+                    
+						
+					
+              
+            
+          
+        
+    
+
+
+
+
+
+
+
+
+
+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
+	
+
+
+
+	
+		User Guide
+	
+	
+		Function Reference
+	
+	
+
+
+Navigation
+
+Version select
+
+	
+	
+	
+		2.0
+	
+		1.3
+	
+		1.2
+	
+		1.1
+	
+		1.0
+	
+
+
+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.
+
+
+
+
+
+
+
+
+      
+        
+          
+            
+              ↑ Scroll to top
+              
+                
+                  Contact us
Contribute to this site
+                
+              
+            
+            
+               
+               Copyright © Loïc Hoguin 2012-2018
+            
+          
+        
+      
+
+    
+    
+  
+
+
+
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)
+
+    
+    
+
+    
+    
+    
+    
+
+    
+
+
+
+
+  
+    
+        
+          
+            99s
+          
+          
+            
+            
+              
+                
+                  Articles
+  				  Talks
+  				  Documentation
+  				  Consulting & Training
+                
+               
+              
+                
+                  
+                
+                    
+						
+					
+              
+            
+          
+        
+    
+
+
+
+
+
+
+
+
+
+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
+	
+
+
+
+	
+		User Guide
+	
+	
+		Function Reference
+	
+	
+
+
+Navigation
+
+Version select
+
+	
+	
+	
+		2.0
+	
+		1.3
+	
+		1.2
+	
+		1.1
+	
+		1.0
+	
+
+
+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.
+
+
+
+
+
+
+
+
+      
+        
+          
+            
+              ↑ Scroll to top
+              
+                
+                  Contact us
Contribute to this site
+                
+              
+            
+            
+               
+               Copyright © Loïc Hoguin 2012-2018
+            
+          
+        
+      
+
+    
+    
+  
+
+
+
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)
+
+    
+    
+
+    
+    
+    
+    
+
+    
+
+
+
+
+  
+    
+        
+          
+            99s
+          
+          
+            
+            
+              
+                
+                  Articles
+  				  Talks
+  				  Documentation
+  				  Consulting & Training
+                
+               
+              
+                
+                  
+                
+                    
+						
+					
+              
+            
+          
+        
+    
+
+
+
+
+
+
+
+
+
+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
+
+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
+
+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
+gun_cookies:domain_match(3) - Cookie domain match
+
+gun_cookies:path_match(3) - Cookie path match
+
+
+Types
+cookie()
+
+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
+	
+
+
+
+	
+		User Guide
+	
+	
+		Function Reference
+	
+	
+
+
+Navigation
+
+Version select
+
+	
+	
+	
+		2.0
+	
+		1.3
+	
+		1.2
+	
+		1.1
+	
+		1.0
+	
+
+
+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.
+
+
+
+
+
+
+
+
+      
+        
+          
+            
+              ↑ Scroll to top
+              
+                
+                  Contact us
Contribute to this site
+                
+              
+            
+            
+               
+               Copyright © Loïc Hoguin 2012-2018
+            
+          
+        
+      
+
+    
+    
+  
+
+
+
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)
+
+    
+    
+
+    
+    
+    
+    
+
+    
+
+
+
+
+  
+    
+        
+          
+            99s
+          
+          
+            
+            
+              
+                
+                  Articles
+  				  Talks
+  				  Documentation
+  				  Consulting & Training
+                
+               
+              
+                
+                  
+                
+                    
+						
+					
+              
+            
+          
+        
+    
+
+
+
+
+
+
+
+
+
+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
+	
+
+
+
+	
+		User Guide
+	
+	
+		Function Reference
+	
+	
+
+
+Navigation
+
+Version select
+
+	
+	
+	
+		2.0
+	
+		1.3
+	
+		1.2
+	
+		1.1
+	
+		1.0
+	
+
+
+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.
+
+
+
+
+
+
+
+
+      
+        
+          
+            
+              ↑ Scroll to top
+              
+                
+                  Contact us
Contribute to this site
+                
+              
+            
+            
+               
+               Copyright © Loïc Hoguin 2012-2018
+            
+          
+        
+      
+
+    
+    
+  
+
+
+
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
 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
-- 
cgit v1.2.3
Supported platforms

License

Features added

Return value

Changelog

Changelog

Modules

Dependencies

gun_cookies:domain_match(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Gun + 2.0 + Function Reference + +

Navigation

Version select

Like my work? Donate!

gun_cookies:path_match(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Gun + 2.0 + Function Reference + +

Navigation

Version select

Like my work? Donate!

gun_cookies(3)

Name

Description

Callbacks

init

query

set_cookie_secure_match

set_cookie_get_exact_match

store

gc

session_gc

Exports

Types

cookie()

store()

Changelog

See also

+ Gun + 2.0 + Function Reference + +

Navigation

Version select

Like my work? Donate!

gun_cookies_list(3)

Name

Description

Exports

Types

opts()

Changelog

Examples

See also

+ Gun + 2.0 + Function Reference + +

Navigation

Version select

Like my work? Donate!

Modules

Dependencies
