From 630bd475e6aa4b9fdde01272236d08305034cb48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 31 Dec 2018 17:08:59 +0100 Subject: 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. --- doc/src/guide/http.asciidoc | 12 ++---- doc/src/manual/gun.asciidoc | 2 + doc/src/manual/gun.headers.asciidoc | 86 +++++++++++++++++++++++++++++++++++++ doc/src/manual/gun.patch.asciidoc | 12 ++++-- doc/src/manual/gun.post.asciidoc | 12 ++++-- doc/src/manual/gun.put.asciidoc | 12 ++++-- doc/src/manual/gun.request.asciidoc | 16 ++----- 7 files changed, 120 insertions(+), 32 deletions(-) create mode 100644 doc/src/manual/gun.headers.asciidoc (limited to 'doc') 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)], -- cgit v1.2.3