Separate request/4,5,6 into headers/4,5 and request/5,6

This cleaner separation gets rid of the implicit body check
that was causing issues for many users. Now the body is
either given explicitly or it is expected via future
gun:data/3 calls.

7 files changed, 120 insertions, 32 deletions

diff --git a/doc/src/guide/http.asciidoc b/doc/src/guide/http.asciidoc
index 652030a..fb0c7dc 100644
--- a/doc/src/guide/http.asciidoc
+++ b/doc/src/guide/http.asciidoc
@@ -108,7 +108,7 @@ desirable. The request body of a PATCH method may be a partial
 representation or a list of instructions on how to update the
 resource.
 
-The `gun:post/4,5`, `gun:put/4,5` and `gun:patch/4,5` functions
+The functions `gun:post/4,5`, `gun:put/4,5` and `gun:patch/4,5`
 take a body as their fourth argument. These functions do
 not require any body-specific header to be set, although
 it is always recommended to set the content-type header.
@@ -127,13 +127,9 @@ StreamRef = gun:post(ConnPid, "/organizations/ninenines", [
 ], Body).
 ----
 
-The `gun:post/3`, `gun:put/3` and `gun:patch/3` functions
-do not take a body in their arguments. If a body is to be
-provided later on, using the `gun:data/4` function, then
-the request headers must indicate this. This can be done
-by setting the content-length or content-type request
-headers. If these headers are not set then Gun will assume
-the request has no body.
+The functions `gun:post/3,4`, `gun:put/3,4` and `gun:patch/3,4`
+do not take a body in their arguments: the body must be
+provided later on using the `gun:data/4` function.
 
 It is recommended to send the content-length header if you
 know it in advance, although this is not required. If it
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index a210635..1b4e6d7 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -29,6 +29,7 @@ Requests:
 * link:man:gun:post(3)[gun:post(3)] - Process the enclosed representation according to a resource's own semantics
 * link:man:gun:put(3)[gun:put(3)] - Create or replace a resource
 * link:man:gun:delete(3)[gun:delete(3)] - Delete a resource
+* link:man:gun:headers(3)[gun:headers(3)] - Initiate the given request
 * link:man:gun:request(3)[gun:request(3)] - Perform the given request
 * link:man:gun:data(3)[gun:data(3)] - Stream the body of a request
 
@@ -313,6 +314,7 @@ undocumented and must be set to `gun_ws_h`.
 
 == Changelog
 
+* *2.0*: Function `gun:headers/4,5` introduced.
 * *1.3*: Add the CONNECT destination's `protocols` option and
          deprecate the previously introduced `protocol` option.
 * *1.2*: Introduce the type `connect_destination()`.
diff --git a/doc/src/manual/gun.headers.asciidoc b/doc/src/manual/gun.headers.asciidoc
new file mode 100644
index 0000000..bab1b82
--- /dev/null
+++ b/doc/src/manual/gun.headers.asciidoc
@@ -0,0 +1,86 @@
+= gun:headers(3)
+
+== Name
+
+gun:headers - Initiate the given request
+
+== Description
+
+[source,erlang]
+----
+headers(ConnPid, Method, Path, Headers)
+    -> headers(ConnPid, Method, Path, Headers, #{})
+
+headers(ConnPid, Method, Path, Headers, ReqOpts)
+    -> StreamRef
+
+ConnPid   :: pid()
+Method    :: binary()
+Path      :: iodata()
+Headers   :: [{binary(), iodata()}]
+ReqOpts   :: gun:req_opts()
+StreamRef :: reference()
+----
+
+Initiate the given request.
+
+This is a general purpose function that should only be
+used when other method-specific functions do not apply.
+
+The function `headers/4,5` initiates a request but does
+not send the request body. It must be sent separately
+using link:man:gun:data(3)[gun:data(3)].
+
+== Arguments
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+Method::
+
+Method to be used for the request.
+
+Path::
+
+Path to the resource.
+
+Headers::
+
+Additional request headers.
+
+ReqOpts::
+
+Request options.
+
+== Return value
+
+A reference that identifies the newly created stream is
+returned. It is this reference that must be passed in
+subsequent calls and will be received in messages related
+to this new stream.
+
+== Changelog
+
+* *2.0*: Function introduced.
+
+== Examples
+
+.Initiate a request
+[source,erlang]
+----
+StreamRef = gun:headers(ConnPid, <<"PUT">>,
+    "/lang/fr_FR/hello",
+    [{<<"content-type">>, <<"text/plain">>}]).
+----
+
+== See also
+
+link:man:gun(3)[gun(3)],
+link:man:gun:request(3)[gun:request(3)],
+link:man:gun:await(3)[gun:await(3)],
+link:man:gun:await_body(3)[gun:await_body(3)],
+link:man:gun_push(3)[gun_push(3)],
+link:man:gun_inform(3)[gun_inform(3)],
+link:man:gun_response(3)[gun_response(3)],
+link:man:gun_data(3)[gun_data(3)]
diff --git a/doc/src/manual/gun.patch.asciidoc b/doc/src/manual/gun.patch.asciidoc
index 3f7baa9..c240a4d 100644
--- a/doc/src/manual/gun.patch.asciidoc
+++ b/doc/src/manual/gun.patch.asciidoc
@@ -9,6 +9,9 @@ gun:patch - Apply a set of changes to a resource
 [source,erlang]
 ----
 patch(ConnPid, Path, Headers)
+    -> patch(ConnPid, Path, Headers, #{})
+
+patch(ConnPid, Path, Headers, ReqOpts)
     -> StreamRef
 
 patch(ConnPid, Path, Headers, Body)
@@ -30,10 +33,8 @@ Apply a set of changes to a resource.
 The behavior of this function varies depending on whether
 a body is provided.
 
-The function `patch/3` expects either a content-length
-or content-type header to indicate that a body will be
-sent afterwards. The body can then be sent using
-link:man:gun:data(3)[gun:data(3)].
+The function `patch/3,4` does not send a body. It must be
+sent separately using link:man:gun:data(3)[gun:data(3)].
 
 The function `patch/4,5` sends the entire request, including
 the request body, immediately. It is therefore not possible
@@ -75,6 +76,9 @@ to this new stream.
 
 == Changelog
 
+* *2.0*: Implicit body detection has been removed. The body
+         must now be provided either directly (even if empty)
+         or using separate calls.
 * *1.0*: Function introduced.
 
 == Examples
diff --git a/doc/src/manual/gun.post.asciidoc b/doc/src/manual/gun.post.asciidoc
index e548824..aed8b3f 100644
--- a/doc/src/manual/gun.post.asciidoc
+++ b/doc/src/manual/gun.post.asciidoc
@@ -9,6 +9,9 @@ gun:post - Process the enclosed representation according to a resource's own sem
 [source,erlang]
 ----
 post(ConnPid, Path, Headers)
+    -> post(ConnPid, Path, Headers, #{})
+
+post(ConnPid, Path, Headers, ReqOpts)
     -> StreamRef
 
 post(ConnPid, Path, Headers, Body)
@@ -31,10 +34,8 @@ own semantics.
 The behavior of this function varies depending on whether
 a body is provided.
 
-The function `post/3` expects either a content-length
-or content-type header to indicate that a body will be
-sent afterwards. The body can then be sent using
-link:man:gun:data(3)[gun:data(3)].
+The function `post/3,4` does not send a body. It must be
+sent separately using link:man:gun:data(3)[gun:data(3)].
 
 The function `post/4,5` sends the entire request, including
 the request body, immediately. It is therefore not possible
@@ -73,6 +74,9 @@ to this new stream.
 
 == Changelog
 
+* *2.0*: Implicit body detection has been removed. The body
+         must now be provided either directly (even if empty)
+         or using separate calls.
 * *1.0*: Function introduced.
 
 == Examples
diff --git a/doc/src/manual/gun.put.asciidoc b/doc/src/manual/gun.put.asciidoc
index 4f0cb39..a60849b 100644
--- a/doc/src/manual/gun.put.asciidoc
+++ b/doc/src/manual/gun.put.asciidoc
@@ -9,6 +9,9 @@ gun:put - Create or replace a resource
 [source,erlang]
 ----
 put(ConnPid, Path, Headers)
+    -> put(ConnPid, Path, Headers, #{})
+
+put(ConnPid, Path, Headers, ReqOpts)
     -> StreamRef
 
 put(ConnPid, Path, Headers, Body)
@@ -30,10 +33,8 @@ Create or replace a resource.
 The behavior of this function varies depending on whether
 a body is provided.
 
-The function `put/3` expects either a content-length
-or content-type header to indicate that a body will be
-sent afterwards. The body can then be sent using
-link:man:gun:data(3)[gun:data(3)].
+The function `put/3,4` does not send a body. It must be
+sent separately using link:man:gun:data(3)[gun:data(3)].
 
 The function `put/4,5` sends the entire request, including
 the request body, immediately. It is therefore not possible
@@ -72,6 +73,9 @@ to this new stream.
 
 == Changelog
 
+* *2.0*: Implicit body detection has been removed. The body
+         must now be provided either directly (even if empty)
+         or using separate calls.
 * *1.0*: Function introduced.
 
 == Examples
diff --git a/doc/src/manual/gun.request.asciidoc b/doc/src/manual/gun.request.asciidoc
index ec169ac..f5c1cd8 100644
--- a/doc/src/manual/gun.request.asciidoc
+++ b/doc/src/manual/gun.request.asciidoc
@@ -8,9 +8,6 @@ gun:request - Perform the given request
 
 [source,erlang]
 ----
-request(ConnPid, Method, Path, Headers)
-    -> StreamRef
-
 request(ConnPid, Method, Path, Headers, Body)
     -> request(ConnPid, Method, Path, Headers, Body, #{})
 
@@ -31,15 +28,6 @@ Perform the given request.
 This is a general purpose function that should only be
 used when other method-specific functions do not apply.
 
-The behavior of this function varies depending on whether
-a body is provided.
-
-The function `request/4` expects either a content-length
-or content-type header to indicate that a body will be
-sent afterwards. Gun will assume the request has no body
-otherwise. The body can then be sent using
-link:man:gun:data(3)[gun:data(3)].
-
 The function `request/5,6` sends the entire request, including
 the request body, immediately. It is therefore not possible
 to use link:man:gun:data(3)[gun:data(3)] after that. You
@@ -81,6 +69,9 @@ to this new stream.
 
 == Changelog
 
+* *2.0*: Implicit body detection has been removed. The body
+         must now be provided either directly (even if empty)
+         or using link:man:gun:headers(3)[gun:headers(3)].
 * *1.0*: Function introduced.
 
 == Examples
@@ -97,6 +88,7 @@ StreamRef = gun:request(ConnPid, <<"PUT">>,
 == See also
 
 link:man:gun(3)[gun(3)],
+link:man:gun:headers(3)[gun:headers(3)],
 link:man:gun:await(3)[gun:await(3)],
 link:man:gun:await_body(3)[gun:await_body(3)],
 link:man:gun_push(3)[gun_push(3)],