From 4023e7f4e429179fd9c2cce4487c33646c6bd327 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 14 Jan 2016 13:35:25 +0100 Subject: Convert the documentation to Asciidoc A few small revisions were made, and Erlang.mk has been updated. --- doc/src/guide/resp.ezdoc | 197 ----------------------------------------------- 1 file changed, 197 deletions(-) delete mode 100644 doc/src/guide/resp.ezdoc (limited to 'doc/src/guide/resp.ezdoc') diff --git a/doc/src/guide/resp.ezdoc b/doc/src/guide/resp.ezdoc deleted file mode 100644 index 009756a..0000000 --- a/doc/src/guide/resp.ezdoc +++ /dev/null @@ -1,197 +0,0 @@ -::: Sending a response - -The Req object also allows you to send a response. - -You can only send one response. Any other attempt will -trigger a crash. The response may be sent in one go or -with its body streamed by chunks of arbitrary size. - -You can also set headers or the response body in advance -and Cowboy will use them when you finally do reply. - -:: Reply - -You can send a reply with no particular headers or body. -Cowboy will make sure to send the mandatory headers with -the response. - -``` erlang -Req2 = cowboy_req:reply(200, Req). -``` - -You can define headers to be sent with the response. Note -that header names must be lowercase. Again, Cowboy will -make sure to send the mandatory headers with the response. - -``` erlang -Req2 = cowboy_req:reply(303, [ - {<<"location">>, <<"http://ninenines.eu">>} -], Req). -``` - -You can override headers that Cowboy would send otherwise. -Any header set by the user will be used over the ones set -by Cowboy. For example, you can advertise yourself as a -different server. - -``` erlang -Req2 = cowboy_req:reply(200, [ - {<<"server">>, <<"yaws">>} -], Req). -``` - -We also saw earlier how to force close the connection by -overriding the connection header. - -Finally, you can also send a body with the response. Cowboy -will automatically set the content-length header if you do. -We recommend that you set the content-type header so the -client may know how to read the body. - -``` erlang -Req2 = cowboy_req:reply(200, [ - {<<"content-type">>, <<"text/plain">>} -], "Hello world!", Req). -``` - -Here is the same example but sending HTML this time. - -``` erlang -Req2 = cowboy_req:reply(200, [ - {<<"content-type">>, <<"text/html">>} -], "Hello world!

Hats off!

", Req). -``` - -Note that the reply is sent immediately. - -:: Chunked reply - -You can also stream the response body. First, you need to -initiate the reply by sending the response status code. -Then you can send the body in chunks of arbitrary size. - -``` erlang -Req2 = cowboy_req:chunked_reply(200, Req), -cowboy_req:chunk("Hello...", Req2), -cowboy_req:chunk("chunked...", Req2), -cowboy_req:chunk("world!!", Req2). -``` - -You should make sure to match on `ok` as an error may be -returned. - -While it is possible to send a chunked response without -a content-type header, it is still recommended. You can -set this header or any other just like for normal replies. - -``` erlang -Req2 = cowboy_req:chunked_reply(200, [ - {<<"content-type">>, <<"text/html">>} -], Req), -cowboy_req:chunk("Hello world!", Req2), -cowboy_req:chunk("

Hats off!

", Req2). -``` - -Note that the reply and each chunk following it are sent -immediately. - -:: Preset response headers - -You can define response headers in advance. They will be -merged into the headers given in the reply call. Headers -in the reply call override preset response headers which -override the default Cowboy headers. - -``` erlang -Req2 = cowboy_req:set_resp_header(<<"allow">>, "GET", Req). -``` - -You can check if a response header has already been set. -This will only check the response headers that you set, -and not the ones Cowboy will add when actually sending -the reply. - -``` erlang -cowboy_req:has_resp_header(<<"allow">>, Req). -``` - -It will return `true` if the header is defined, and `false` -otherwise. - -Finally, you can also delete a preset response header if -needed. If you do, it will not be sent. - -``` erlang -Req2 = cowboy_req:delete_resp_header(<<"allow">>, Req). -``` - -:: Preset response body - -You can set the response body in advance. Note that this -body will be ignored if you then choose to send a chunked -reply, or if you send a reply with an explicit body. - -``` erlang -Req2 = cowboy_req:set_resp_body("Hello world!", Req). -``` - -You can also set a fun that will be called when it is time -to send the body. There are three different ways of doing -that. - -If you know the length of the body that needs to be sent, -you should specify it, as it will help clients determine -the remaining download time and allow them to inform the -user. - -``` erlang -F = fun (Socket, Transport) -> - Transport:send(Socket, "Hello world!") -end, -Req2 = cowboy_req:set_resp_body_fun(12, F, Req). -``` - -If you do not know the length of the body, you should use -a chunked response body fun instead. - -``` erlang -F = fun (SendChunk) -> - Body = lists:duplicate(random:uniform(1024, $a)), - SendChunk(Body) -end, -Req2 = cowboy_req:set_resp_body_fun(chunked, F, Req). -``` - -Finally, you can also send data on the socket directly, -without knowing the length in advance. Cowboy may be -forced to close the connection at the end of the response -though depending on the protocol capabilities. - -``` erlang -F = fun (Socket, Transport) -> - Body = lists:duplicate(random:uniform(1024, $a)), - Transport:send(Socket, Body) -end, -Req2 = cowboy_req:set_resp_body_fun(F, Req). -``` - -:: Sending files - -You can send files directly from disk without having to -read them. Cowboy will use the `sendfile` syscall when -possible, which means that the file is sent to the socket -directly from the kernel, which is a lot more performant -than doing it from userland. - -Again, it is recommended to set the size of the file if it -can be known in advance. - -``` erlang -F = fun (Socket, Transport) -> - Transport:sendfile(Socket, "priv/styles.css") -end, -Req2 = cowboy_req:set_resp_body_fun(FileSize, F, Req). -``` - -Please see the Ranch guide for more information about -sending files. -- cgit v1.2.3