Add man pages for the reply functions

doc/src/manual/cowboy_req.asciidoc

@@ -73,8 +73,8 @@ Response:
 * link:man:cowboy_req:set_resp_body(3)[cowboy_req:set_resp_body(3)] - Set the response body
 * link:man:cowboy_req:has_resp_body(3)[cowboy_req:has_resp_body(3)] - Is there a response body?
 * link:man:cowboy_req:reply(3)[cowboy_req:reply(3)] - Send the response
-* link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)] - Send the response and stream its body
-* link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)] - Send a chunk of the response body
+* link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)] - Send the response headers
+* link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)] - Stream the response body
 * link:man:cowboy_req:push(3)[cowboy_req:push(3)] - Push a resource to the client
 
 == Types

doc/src/manual/cowboy_req.delete_resp_header.asciidoc

@@ -0,0 +1,55 @@
+= cowboy_req:delete_resp_header(3)
+
+== Name
+
+cowboy_req:delete_resp_header - Delete a response header
+
+== Description
+
+[source,erlang]
+----
+delete_resp_header(Name, Req :: cowboy_req:req()) -> Req
+
+Name :: binary()  %% lowercase; case insensitive
+----
+
+Delete the given response header.
+
+The header name must be given as a lowercase binary string.
+While header names are case insensitive, Cowboy requires them
+to be given as lowercase to function properly.
+
+== Arguments
+
+Name::
+
+Header name as a lowercase binary string.
+
+Req::
+
+The Req object.
+
+== Return value
+
+A new Req object is returned.
+
+The returned Req object must be used from that point onward,
+otherwise the header will still be sent in the response.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Remove the content-type header from the response
+[source,erlang]
+----
+Req = cowboy_req:delete_resp_header(<<"content-type">>, Req0),
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)]

doc/src/manual/cowboy_req.has_resp_body.asciidoc

@@ -0,0 +1,48 @@
+= cowboy_req:has_resp_body(3)
+
+== Name
+
+cowboy_req:has_resp_body - Is there a response body?
+
+== Description
+
+[source,erlang]
+----
+has_resp_body(Req :: cowboy_req:req()) -> boolean()
+----
+
+Return whether a response body has been set.
+
+== Arguments
+
+Req::
+
+The Req object.
+
+== Return value
+
+A boolean indicating whether a response body has been set.
+
+This function will return `false` when an empty response
+body has been set.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Check whether a body has been set
+[source,erlang]
+----
+false = cowboy_req:has_resp_body(Req0),
+Req1 = cowboy_req:set_resp_body(<<"Hello!">>, Req0),
+true = cowboy_req:has_resp_body(Req1),
+Req = cowboy_req:set_resp_body(<<>>, Req1),
+false = cowboy_req:has_resp_body(Req).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:set_resp_body(3)[cowboy_req:set_resp_body(3)]

doc/src/manual/cowboy_req.has_resp_header.asciidoc

@@ -0,0 +1,54 @@
+= cowboy_req:has_resp_header(3)
+
+== Name
+
+cowboy_req:has_resp_header - Is the given response header set?
+
+== Description
+
+[source,erlang]
+----
+has_resp_header(Name, Req :: cowboy_req:req()) -> boolean()
+
+Name :: binary()  %% lowercase; case insensitive
+----
+
+Return whether the given response header has been set.
+
+The header name must be given as a lowercase binary string.
+While header names are case insensitive, Cowboy requires them
+to be given as lowercase to function properly.
+
+== Arguments
+
+Name::
+
+Header name as a lowercase binary string.
+
+Req::
+
+The Req object.
+
+== Return value
+
+A boolean indicating whether the given response header has been set.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Check whether the content-type header has been set
+[source,erlang]
+----
+false = cowboy_req:has_resp_header(<<"content-type">>, Req0),
+Req = cowboy_req:set_resp_header(<<"content-type">>, <<"text/html">>, Req0),
+true = cowboy_req:has_resp_header(<<"content-type">>, Req).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)]

doc/src/manual/cowboy_req.header.asciidoc

@@ -11,7 +11,7 @@ cowboy_req:header - HTTP header
 header(Name, Req)          -> header(Name, Req, undefined)
 header(Name, Req, Default) -> binary() | Default
 
-Name    :: binary()
+Name    :: binary()          %% lowercase; case insensitive
 Req     :: cowboy_req:req()
 Default :: any()
 ----

doc/src/manual/cowboy_req.push.asciidoc

@@ -0,0 +1,98 @@
+= cowboy_req:push(3)
+
+== Name
+
+cowboy_req:push - Push a resource to the client
+
+== Description
+
+[source,erlang]
+----
+push(Path, Headers, Req :: cowboy_req:req())
+    -> push(Path, Headers, Req, #{})
+
+push(Path, Headers, Req :: cowboy_req:req(), Opts)
+    -> ok
+
+Path    :: iodata()                %% case sensitive
+Headers :: cowboy:http_headers()
+Opts    :: cowboy_req:push_opts()
+----
+
+Push a resource to the client.
+
+Cowboy handles push requests the same way as if they came
+from the client, including the creation of a request handling
+process, routing and middlewares and so on.
+
+This function does nothing when the HTTP/1.1 protocol is
+used. You may call it safely without first checking whether
+the connection uses HTTP/2.
+
+The header names must be given as lowercase binary strings.
+While header names are case insensitive, Cowboy requires them
+to be given as lowercase to function properly.
+
+Note that the headers must be the headers the client is expected
+to send if it were to perform the request. They are therefore
+request headers, and not response headers.
+
+By default, Cowboy will use the GET method, an empty query string,
+and take the scheme, host and port directly from the current
+request's URI. You can override them by passing options.
+
+It is not possible to push resources after sending a response.
+Any attempt will result in an error.
+
+== Arguments
+
+Path::
+
+The status code for the response.
+
+Headers::
+
+The response headers.
+
+Header names must be given as lowercase binary strings.
+
+Req::
+
+The Req object.
+
+Opts::
+
+Customize the HTTP method or the URI scheme, host, port
+or query string.
+
+== Return value
+
+The atom `ok` is always returned. It can be safely ignored.
+
+== Changelog
+
+* *2.0*: Function introduced.
+
+== Examples
+
+.Push a resource
+[source,erlang]
+----
+cowboy_req:push("/static/style.css", #{
+    <<"accept">> => <<"text/css">>
+}, Req),
+----
+
+.Push a resource with a custom host
+[source,erlang]
+----
+cowboy_req:push("/static/style.css", #{
+    <<"accept">> => <<"text/css">>
+}, #{host => <<"cdn.example.org">>}, Req),
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]

doc/src/manual/cowboy_req.reply.asciidoc

@@ -0,0 +1,115 @@
+= cowboy_req:reply(3)
+
+== Name
+
+cowboy_req:reply - Send the response
+
+== Description
+
+[source,erlang]
+----
+reply(Status, Req :: cowboy_req:req())
+    -> reply(StatusCode, #{}, Req)
+
+reply(Status, Headers, Req :: cowboy_req:req())
+    -> Req
+
+reply(Status, Headers, Body, Req :: cowboy_req:req())
+    -> Req
+
+Status  :: cowboy:http_status()
+Headers :: cowboy:http_headers()
+Body    :: cowboy_req:resp_body()
+----
+
+Send the response.
+
+The header names must be given as lowercase binary strings.
+While header names are case insensitive, Cowboy requires them
+to be given as lowercase to function properly.
+
+Cowboy does not allow duplicate header names. Headers set
+by this function may overwrite those set by `set_resp_header/3`.
+
+Use link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)]
+instead of this function to set cookies.
+
+The `reply/2,3` functions will send the body set previously,
+if any. The `reply/4` function always sends the given body,
+overriding any previously set.
+
+You do not need to set the content-length header when
+sending a response body. Cowboy takes care of it automatically.
+You should however provide a content-type header.
+
+No further data can be transmitted after this function
+returns. This includes the push mechanism. Attempting to
+send two replies, or to push resources after a reply has
+been sent, will result in an error.
+
+== Arguments
+
+Status::
+
+The status code for the response.
+
+Headers::
+
+The response headers.
+
+Header names must be given as lowercase binary strings.
+
+Body::
+
+The body can be either a binary value, an iolist or a
+`sendfile` tuple telling Cowboy to send the contents of
+a file.
+
+Req::
+
+The Req object.
+
+== Return value
+
+A new Req object is returned.
+
+The returned Req object should be used from that point onward
+as it contains updated information about the state of the request.
+
+== Changelog
+
+* *2.0*: Only the Req is returned, it is no longer wrapped in a tuple.
+* *1.0*: Function introduced.
+
+== Examples
+
+.Reply
+[source,erlang]
+----
+Req = cowboy_req:reply(404, Req0).
+----
+
+.Reply with custom headers
+[source,erlang]
+----
+Req = cowboy_req:reply(401, #{
+    <<"www-authenticate">> => <<"Basic realm=\"erlang.org\"">>
+}, Req0).
+----
+
+.Reply with custom headers and a body
+[source,erlang]
+----
+Req = cowboy_req:reply(200, #{
+    <<"content-type">> => <<"text/plain">>
+}, "Hello world!", Req0).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)],
+link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:set_resp_body(3)[cowboy_req:set_resp_body(3)],
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)],
+link:man:cowboy_req:push(3)[cowboy_req:push(3)]

doc/src/manual/cowboy_req.set_resp_body.asciidoc

@@ -0,0 +1,90 @@
+= cowboy_req:set_resp_body(3)
+
+== Name
+
+cowboy_req:set_resp_body - Set the response body
+
+== Description
+
+[source,erlang]
+----
+set_resp_body(Body, Req :: cowboy_req:req())
+	-> Req
+
+Body :: cowboy_req:resp_body()
+----
+
+Set the response body.
+
+The response body will be sent when a reply is initiated.
+Note that the functions `stream_reply/2,3` and `reply/4`
+will override the body set by this function.
+
+This function can also be used to remove a response body
+that was set previously. To do so, simply call this function
+with an empty body.
+
+== Arguments
+
+Body::
+
+The body can be either a binary value, an iolist or a
+`sendfile` tuple telling Cowboy to send the contents of
+a file.
+
+Req::
+
+The Req object.
+
+== Return value
+
+A new Req object is returned.
+
+The returned Req object must be used from that point onward,
+otherwise the body will not be sent in the response.
+
+== Changelog
+
+* *2.0*: The function now accepts a `sendfile` tuple.
+* *2.0*: The `set_resp_body_fun/2,3` functions were removed.
+* *1.0*: Function introduced.
+
+== Examples
+
+.Set the response body
+[source,erlang]
+----
+Req = cowboy_req:set_resp_body(<<"Hello world!">>, Req0).
+----
+
+.Set the response body as an iolist
+[source,erlang]
+----
+Req = cowboy_req:set_resp_body([
+    "<html><head><title>",
+    page_title(),
+    "</title></head><body>",
+    page_body(),
+    "</body></html>"
+], Req0).
+----
+
+.Tell Cowboy to send data from a file
+[source,erlang]
+----
+{ok, #file_info{size=Size}} = file:read_file_info(Filename),
+Req = cowboy_req:set_resp_body({sendfile, 0, Size, Filename}, Req0).
+----
+
+.Clear any previously set response body
+[source,erlang]
+----
+Req = cowboy_req:set_resp_body(<<>>, Req0).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]

doc/src/manual/cowboy_req.set_resp_cookie.asciidoc

@@ -0,0 +1,115 @@
+= cowboy_req:set_resp_cookie(3)
+
+== Name
+
+cowboy_req:set_resp_cookie - Set a cookie
+
+== Description
+
+[source,erlang]
+----
+set_resp_cookie(Name, Value, Req :: cowboy_req:req())
+    -> set_resp_cookie(Name, Value, [], Req)
+
+set_resp_cookie(Name, Value, Opts, Req :: cowboy_req:req())
+    -> Req
+
+Name  :: iodata()                  %% case sensitive
+Value :: iodata()                  %% case sensitive
+Opts  :: cow_cookie:cookie_opts()
+----
+
+// @todo I am not particularly happy about the fact that the name is iodata().
+
+Set a cookie to be sent with the response.
+
+Note that cookie names are case sensitive.
+
+== Arguments
+
+Name::
+
+Cookie name.
+
+Value::
+
+Cookie value.
+
+Opts::
+
+Optional cookie options.
+
+Req::
+
+The Req object.
+
+== Return value
+
+A new Req object is returned.
+
+The returned Req object must be used from that point onward,
+otherwise the cookie will not be sent in the response.
+
+== Changelog
+
+* *2.0*: `set_resp_cookie/3` introduced as an alias to `set_resp_cookie/4` with no options.
+* *1.0*: Function introduced.
+
+== Examples
+
+.Set a session cookie
+[source,erlang]
+----
+SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0).
+----
+
+.Set a cookie with an expiration time
+[source,erlang]
+----
+Req = cowboy_req:set_resp_cookie(<<"lang">>, <<"fr-FR">>, [
+    {max_age, 3600}
+], Req0).
+----
+
+.Delete a cookie
+[source,erlang]
+----
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, <<>>, [
+    {max_age, 0}
+], Req0).
+----
+
+.Set a cookie for a specific domain and path
+[source,erlang]
+----
+Req = cowboy_req:set_resp_cookie(<<"inaccount">>, <<"1">>, [
+    {domain, "my.example.org"},
+    {path, "/account"}
+], Req0).
+----
+
+.Restrict a cookie to HTTPS
+[source,erlang]
+----
+SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [
+    {secure, true}
+], Req0).
+----
+
+.Restrict a cookie to HTTP
+[source,erlang]
+----
+SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [
+    {http_only, true}
+], Req0).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]

doc/src/manual/cowboy_req.set_resp_header.asciidoc

@@ -0,0 +1,78 @@
+= cowboy_req:set_resp_header(3)
+
+== Name
+
+cowboy_req:set_resp_header - Set a response header
+
+== Description
+
+[source,erlang]
+----
+set_resp_header(Name, Value, Req :: cowboy_req:req())
+	-> Req
+
+Name  :: binary()  %% lowercase; case insensitive
+Value :: iodata()  %% case depends on header
+----
+
+Set a header to be sent with the response.
+
+The header name must be given as a lowercase binary string.
+While header names are case insensitive, Cowboy requires them
+to be given as lowercase to function properly.
+
+Cowboy does not allow duplicate header names. Headers set
+by this function may be overwritten by those set from the
+reply functions.
+
+Use link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)]
+instead of this function to set cookies.
+
+== Arguments
+
+Name::
+
+Header name as a lowercase binary string.
+
+Value::
+
+Header value.
+
+Req::
+
+The Req object.
+
+== Return value
+
+A new Req object is returned.
+
+The returned Req object must be used from that point onward,
+otherwise the header will not be sent in the response.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Set a header in the response
+[source,erlang]
+----
+Req = cowboy_req:set_resp_header(<<"allow">>, "GET", Req0).
+----
+
+.Construct a header using iolists
+[source,erlang]
+----
+Req = cowboy_req:set_resp_header(<<"allow">>,
+    [allowed_methods(), ", OPTIONS"], Req0).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)],
+link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)],
+link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)],
+link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]

doc/src/manual/cowboy_req.stream_body.asciidoc

@@ -0,0 +1,77 @@
+= cowboy_req:stream_body(3)
+
+== Name
+
+cowboy_req:stream_body - Stream the response body
+
+== Description
+
+[source,erlang]
+----
+stream_body(Data, IsFin, Req :: cowboy_req:req()) -> ok
+
+Data  :: iodata()
+IsFin :: fin | nofin
+----
+
+Stream the response body.
+
+This function may be called as many times as needed after
+initiating a response using the
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]
+function.
+
+The second argument indicates if this call is the final
+call. Use the `nofin` value until you know no more data
+will be sent. The final call should use `fin` (possibly
+with an empty data value).
+
+Note that not using `fin` for the final call is not an
+error; Cowboy will take care of it when the request
+handler terminates if needed. Depending on the resource
+it may however be more efficient to do it as early as
+possible.
+
+You do not need to handle HEAD requests specifically as
+Cowboy will ensure no data is sent when you call this function.
+
+== Arguments
+
+Data::
+
+The data to be sent.
+
+IsFin::
+
+A flag indicating whether this is the final piece of data
+to be sent.
+
+Req::
+
+The Req object.
+
+== Return value
+
+The atom `ok` is always returned. It can be safely ignored.
+
+== Changelog
+
+* *2.0*: Function introduced. Replaces `chunk/2`.
+
+== Examples
+
+.Stream the response body
+[source,erlang]
+----
+Req = cowboy_req:stream_reply(200, #{
+    <<"content-type">> => <<"text/plain">>
+}, Req0),
+cowboy_req:stream_body(<<"Hello\n">>, nofin, Req),
+timer:sleep(1000),
+cowboy_req:stream_body(<<"World!\n">>, fin, Req).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]

doc/src/manual/cowboy_req.stream_reply.asciidoc

@@ -0,0 +1,107 @@
+= cowboy_req:stream_reply(3)
+
+== Name
+
+cowboy_req:stream_reply - Send the response headers
+
+== Description
+
+[source,erlang]
+----
+stream_reply(Status, Req :: cowboy_req:req())
+    -> stream_reply(StatusCode, #{}, Req)
+
+stream_reply(Status, Headers, Req :: cowboy_req:req())
+    -> Req
+
+Status  :: cowboy:http_status()
+Headers :: cowboy:http_headers()
+----
+
+Send the response headers.
+
+The header names must be given as lowercase binary strings.
+While header names are case insensitive, Cowboy requires them
+to be given as lowercase to function properly.
+
+Cowboy does not allow duplicate header names. Headers set
+by this function may overwrite those set by `set_resp_header/3`.
+
+Use link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)]
+instead of this function to set cookies.
+
+If a response body was set before calling this function,
+it will not be sent.
+
+Use link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)]
+to stream the response body.
+
+You may want to set the content-length header when using
+this function, if it is known in advance. This will allow
+clients using HTTP/2 and HTTP/1.0 to process the response
+more efficiently.
+
+The streaming method varies depending on the protocol being
+used. HTTP/2 will use the usual DATA frames. HTTP/1.1 will
+use chunked transfer-encoding. HTTP/1.0 will send the body
+unmodified and close the connection at the end if no
+content-length was set.
+
+It is not possible to push resources after this function
+returns. Any attempt will result in an error.
+
+== Arguments
+
+Status::
+
+The status code for the response.
+
+Headers::
+
+The response headers.
+
+Header names must be given as lowercase binary strings.
+
+Req::
+
+The Req object.
+
+== Return value
+
+A new Req object is returned.
+
+The returned Req object must be used from that point onward
+in order to be able to stream the response body.
+
+== Changelog
+
+* *2.0*: Only the Req is returned, it is no longer wrapped in a tuple.
+* *2.0*: Function introduced. Replaces `chunked_reply/1,2`.
+
+== Examples
+
+.Initiate the response
+[source,erlang]
+----
+Req = cowboy_req:stream_reply(200, Req0).
+----
+
+.Stream the response with custom headers
+[source,erlang]
+----
+Req = cowboy_req:stream_reply(200, #{
+    <<"content-type">> => <<"text/plain">>
+}, Req0),
+cowboy_req:stream_body(<<"Hello\n">>, nofin, Req),
+timer:sleep(1000),
+cowboy_req:stream_body(<<"World!\n">>, fin, Req).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)],
+link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
+link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)],
+link:man:cowboy_req:push(3)[cowboy_req:push(3)]