mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-14 20:30:23 +00:00
First draft done for the request object guide chapter
This commit is contained in:
Loïc Hoguin
parent
9d7f909923
commit
4b15d8f6e3
2 changed files with 116 additions and 2 deletions
114
guide/req.md
114
guide/req.md
|
|
@ -72,9 +72,119 @@ and the request object and returns the latter modified.
|
|||
Request body
|
||||
------------
|
||||
|
||||
@todo Describe.
|
||||
Cowboy will not read the request body until you ask it to.
|
||||
If you don't, then Cowboy will simply discard it. It will
|
||||
not take extra memory space until you start reading it.
|
||||
|
||||
Cowboy has a few utility functions for dealing with the
|
||||
request body.
|
||||
|
||||
The function `has_body/1` will return whether the request
|
||||
contains a body. Note that some clients may not send the
|
||||
right headers while still sending a body, but as Cowboy has
|
||||
no way of detecting it this function will return `false`.
|
||||
|
||||
The function `body_length/1` retrieves the size of the
|
||||
request body. If the body is compressed, the value returned
|
||||
here is the compressed size. If a `Transfer-Encoding` header
|
||||
was passed in the request, then Cowboy will return a size
|
||||
of `undefined`, as it has no way of knowing it.
|
||||
|
||||
If you know the request contains a body, and that it is
|
||||
of appropriate size, then you can read it directly with
|
||||
either `body/1` or `body_qs/1`. Otherwise, you will want
|
||||
to stream it with `stream_body/1` and `skip_body/1`, with
|
||||
the streaming process optionally initialized using `init_stream/4`.
|
||||
|
||||
Multipart request body
|
||||
----------------------
|
||||
|
||||
Cowboy provides facilities for dealing with multipart bodies.
|
||||
They are typically used for uploading files. You can use two
|
||||
functions to process these bodies, `multipart_data/1` and
|
||||
`multipart_skip/1`.
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
@todo Describe.
|
||||
You can send a response by calling the `reply/{2,3,4}` function.
|
||||
It takes the status code for the response (usually `200`),
|
||||
an optional list of headers, an optional body and the request
|
||||
object.
|
||||
|
||||
The following snippet sends a simple response with no headers
|
||||
specified but with a body.
|
||||
|
||||
``` erlang
|
||||
{ok, Req2} = cowboy_req:reply(200, [], "Hello world!", Req).
|
||||
```
|
||||
|
||||
If this is the only line in your handler then make sure to return
|
||||
the `Req2` variable to Cowboy so it can know you replied.
|
||||
|
||||
If you want to send HTML you'll need to specify the `Content-Type`
|
||||
header so the client can properly interpret it.
|
||||
|
||||
``` erlang
|
||||
{ok, Req2} = cowboy_req:reply(200,
|
||||
[{<<"content-type">>, <<"text/html">>}],
|
||||
"<html><head>Hello world!</head><body><p>Hats off!</p></body></html>",
|
||||
Req).
|
||||
```
|
||||
|
||||
You only need to make sure to follow conventions and to use a
|
||||
lowercase header name.
|
||||
|
||||
Chunked response
|
||||
----------------
|
||||
|
||||
You can also send chunked responses using `chunked_reply/{2,3}`.
|
||||
Chunked responses allow you to send the body in chunks of various
|
||||
sizes. It is the recommended way of performing streaming if the
|
||||
client supports it.
|
||||
|
||||
You must first initiate the response by calling the aforementioned
|
||||
function, then you can call `chunk/2` as many times as needed.
|
||||
The following snippet sends a body in three chunks.
|
||||
|
||||
``` erlang
|
||||
{ok, Req2} = cowboy_req:chunked_reply(200, Req),
|
||||
ok = cowboy_req:chunk("Hello...", Req2),
|
||||
ok = cowboy_req:chunk("chunked...", Req2),
|
||||
ok = cowboy_req:chunk("world!!", Req2).
|
||||
```
|
||||
|
||||
As you can see the call to `chunk/2` does not return a modified
|
||||
request object. It may return an error, however, so you should
|
||||
make sure that you match the return value on `ok`.
|
||||
|
||||
Response preconfiguration
|
||||
-------------------------
|
||||
|
||||
Cowboy allows you to set response cookies, headers or body
|
||||
in advance without having to send the response at the same time.
|
||||
Then, when you decide to send it, all these informations will be
|
||||
built into the resulting response.
|
||||
|
||||
Some of the functions available for this purpose also give you
|
||||
additional functionality, like `set_resp_cookie/4` which will build
|
||||
the appropriate `Set-Cookie` header, or `set_resp_body_fun/{2,3}`
|
||||
which allows you to stream the response body.
|
||||
|
||||
Note that any value given directly to `reply/{2,3,4}` will
|
||||
override all preset values. This means for example that you
|
||||
can set a default body and then override it when you decide
|
||||
to send a reply.
|
||||
|
||||
Reducing the memory footprint
|
||||
-----------------------------
|
||||
|
||||
When you are done reading information from the request object
|
||||
and know you are not going to access it anymore, for example
|
||||
when using long-polling or Websocket, you can use the `compact/1`
|
||||
function to remove most of the data from the request object and
|
||||
free memory.
|
||||
|
||||
``` erlang
|
||||
Req2 = cowboy_req:compact(Req).
|
||||
```
|
||||
|
|
|
|||
|
|
@ -37,7 +37,11 @@ Cowboy User Guide
|
|||
* Purpose
|
||||
* Request
|
||||
* Request body
|
||||
* Multipart request body
|
||||
* Response
|
||||
* Chunked response
|
||||
* Response preconfiguration
|
||||
* Reducing the memory footprint
|
||||
* [Hooks](hooks.md)
|
||||
* On request
|
||||
* On response
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue