path: root/guide
diff options
authorLoïc Hoguin <[email protected]>2013-01-20 15:09:54 +0100
committerLoïc Hoguin <[email protected]>2013-01-20 15:14:13 +0100
commit4b15d8f6e3692caa796e7e7bf0bdfbd977d00e30 (patch)
tree7e657012774c91ab2b879ea9afe3214203483765 /guide
parent9d7f909923c9e7e503df2da804811b89f6a7056c (diff)
First draft done for the request object guide chapter
Diffstat (limited to 'guide')
2 files changed, 116 insertions, 2 deletions
diff --git a/guide/req.md b/guide/req.md
index 503ad65..c039658 100644
--- a/guide/req.md
+++ b/guide/req.md
@@ -72,9 +72,119 @@ and the request object and returns the latter modified.
Request body
+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
+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
+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).
diff --git a/guide/toc.md b/guide/toc.md
index b4131c5..2890172 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -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