|
|
@@ -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).
|
|
|
+```
|
Loïc Hoguin