From ec73c1b50051718898abbd788946b208ca7469b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 21 Dec 2016 16:12:39 +0100 Subject: Update docs --- .../cowboy_req.delete_resp_header/index.html | 230 ++++++++++++++++ .../2.0/manual/cowboy_req.has_resp_body/index.html | 220 +++++++++++++++ .../manual/cowboy_req.has_resp_header/index.html | 230 ++++++++++++++++ .../cowboy/2.0/manual/cowboy_req.header/index.html | 2 +- .../cowboy/2.0/manual/cowboy_req.push/index.html | 279 +++++++++++++++++++ .../cowboy/2.0/manual/cowboy_req.reply/index.html | 300 ++++++++++++++++++++ .../2.0/manual/cowboy_req.set_resp_body/index.html | 275 +++++++++++++++++++ .../manual/cowboy_req.set_resp_cookie/index.html | 305 +++++++++++++++++++++ .../manual/cowboy_req.set_resp_header/index.html | 256 +++++++++++++++++ .../2.0/manual/cowboy_req.stream_body/index.html | 254 +++++++++++++++++ .../2.0/manual/cowboy_req.stream_reply/index.html | 285 +++++++++++++++++++ docs/en/cowboy/2.0/manual/cowboy_req/index.html | 4 +- docs/en/cowboy/2.0/manual/index.html | 50 ++++ 13 files changed, 2687 insertions(+), 3 deletions(-) create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.push/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.reply/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.stream_body/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/index.html (limited to 'docs/en/cowboy/2.0/manual') diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html new file mode 100644 index 00000000..98fd4fa7 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html @@ -0,0 +1,230 @@ + + + + + + + + + + + + Nine Nines: cowboy_req:delete_resp_header(3) + + + + + + + + + + + + + + + + +

+ + + +

+ +

cowboy_req:delete_resp_header(3)

+ +

Name

cowboy_req:delete_resp_header - Delete a response header

Description

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

Req = cowboy_req:delete_resp_header(<<"content-type">>, Req0),

cowboy_req:has_resp_body(3)

+ +

Name

cowboy_req:has_resp_body - Is there a response body?

Description

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

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).

cowboy_req:has_resp_header(3)

+ +

Name

cowboy_req:has_resp_header - Is the given response header set?

Description

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

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).

cowboy_req:push(3)

+ +

Name

cowboy_req:push - Push a resource to the client

Description

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

cowboy_req:push("/static/style.css", #{
+    <<"accept">> => <<"text/css">>
+}, Req),

Push a resource with a custom host

cowboy_req:push("/static/style.css", #{
+    <<"accept">> => <<"text/css">>
+}, #{host => <<"cdn.example.org">>}, Req),

cowboy_req:reply(3)

+ +

Name

cowboy_req:reply - Send the response

Description

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 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

Req = cowboy_req:reply(404, Req0).

Reply with custom headers

Req = cowboy_req:reply(401, #{
+    <<"www-authenticate">> => <<"Basic realm=\"erlang.org\"">>
+}, Req0).

Reply with custom headers and a body

Req = cowboy_req:reply(200, #{
+    <<"content-type">> => <<"text/plain">>
+}, "Hello world!", Req0).

cowboy_req:set_resp_body(3)

+ +

Name

cowboy_req:set_resp_body - Set the response body

Description

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

Req = cowboy_req:set_resp_body(<<"Hello world!">>, Req0).

Set the response body as an iolist

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

{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

Req = cowboy_req:set_resp_body(<<>>, Req0).

cowboy_req:set_resp_cookie(3)

+ +

Name

cowboy_req:set_resp_cookie - Set a cookie

Description

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()

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

SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0).

Set a cookie with an expiration time

Req = cowboy_req:set_resp_cookie(<<"lang">>, <<"fr-FR">>, [
+    {max_age, 3600}
+], Req0).

Delete a cookie

Req = cowboy_req:set_resp_cookie(<<"sessionid">>, <<>>, [
+    {max_age, 0}
+], Req0).

Set a cookie for a specific domain and path

Req = cowboy_req:set_resp_cookie(<<"inaccount">>, <<"1">>, [
+    {domain, "my.example.org"},
+    {path, "/account"}
+], Req0).

Restrict a cookie to HTTPS

SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [
+    {secure, true}
+], Req0).

Restrict a cookie to HTTP

SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [
+    {http_only, true}
+], Req0).

cowboy_req:set_resp_header(3)

+ +

Name

cowboy_req:set_resp_header - Set a response header

Description

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 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

Req = cowboy_req:set_resp_header(<<"allow">>, "GET", Req0).

Construct a header using iolists

Req = cowboy_req:set_resp_header(<<"allow">>,
+    [allowed_methods(), ", OPTIONS"], Req0).

cowboy_req:stream_body(3)

+ +

Name

cowboy_req:stream_body - Stream the response body

Description

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 +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

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).

cowboy_req:stream_reply(3)

+ +

Name

cowboy_req:stream_reply - Send the response headers

Description

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 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 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

Req = cowboy_req:stream_reply(200, Req0).

Stream the response with custom headers

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).

cowboy_req:delete_resp_header(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:has_resp_body(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:has_resp_header(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:push(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:reply(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:set_resp_body(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:set_resp_cookie(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:set_resp_header(3)

Name

Description