From 92b54aacc0de5446dd5497c39897b0bbff72e626 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 13 Jun 2018 09:54:12 +0200 Subject: Rebuild using Asciideck --- docs/en/cowboy/2.4/guide/handlers/index.html | 106 +++++++++------------------ 1 file changed, 36 insertions(+), 70 deletions(-) (limited to 'docs/en/cowboy/2.4/guide/handlers/index.html') diff --git a/docs/en/cowboy/2.4/guide/handlers/index.html b/docs/en/cowboy/2.4/guide/handlers/index.html index 255cc546..78f64505 100644 --- a/docs/en/cowboy/2.4/guide/handlers/index.html +++ b/docs/en/cowboy/2.4/guide/handlers/index.html @@ -62,91 +62,57 @@

Handlers

-

Handlers are Erlang modules that handle HTTP requests.

-
+

Handlers are Erlang modules that handle HTTP requests.

Plain HTTP handlers

-
-

The most basic handler in Cowboy implements the mandatory -init/2 callback, manipulates the request, optionally -sends a response and then returns.

-

This callback receives the Req object and the initial -state defined in the router configuration.

-

A handler that does nothing would look like this:

-
-
-
init(Req, State) ->
-    {ok, Req, State}.
-

Despite sending no reply, a 204 No Content response will be -sent to the client, as Cowboy makes sure that a response is -sent for every request.

-

We need to use the Req object to reply.

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

Cowboy will immediately send a response when cowboy:reply/4 -is called.

-

We then return a 3-tuple. ok means that the handler ran -successfully. We also give the modified Req back to Cowboy.

-

The last value of the tuple is a state that will be used -in every subsequent callbacks to this handler. Plain HTTP -handlers only have one additional callback, the optional -and rarely used terminate/3.

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

Cowboy will immediately send a response when cowboy:reply/4 is called.

+

We then return a 3-tuple. ok means that the handler ran successfully. We also give the modified Req back to Cowboy.

+

The last value of the tuple is a state that will be used in every subsequent callbacks to this handler. Plain HTTP handlers only have one additional callback, the optional and rarely used terminate/3.

Other handlers

-
-

The init/2 callback can also be used to inform Cowboy -that this is a different kind of handler and that Cowboy -should switch to it. To do this you simply need to return -the module name of the handler type you want to switch to.

-

Cowboy comes with three handler types you can switch to: -cowboy_rest, cowboy_websocket -and cowboy_loop. In addition to those you -can define your own handler types.

-

Switching is simple. Instead of returning ok, you simply -return the name of the handler type you want to use. The -following snippet switches to a Websocket handler:

-
-
-
init(Req, State) ->
-    {cowboy_websocket, Req, State}.
-
- -
+
init(Req, State) ->
+    {cowboy_websocket, Req, State}.
+

Cleaning up

-
-

All handler types provide the optional terminate/3 callback.

-
-
-
terminate(_Reason, _Req, _State) ->
-    ok.
-

This callback is strictly reserved for any required cleanup. -You cannot send a response from this function. There is no -other return value.

-

This callback is optional because it is rarely necessary. -Cleanup should be done in separate processes directly (by -monitoring the handler process to detect when it exits).

-

Cowboy does not reuse processes for different requests. The -process will terminate soon after this call returns.

-
- +
terminate(_Reason, _Req, _State) ->
+    ok.
+ +

This callback is strictly reserved for any required cleanup. You cannot send a response from this function. There is no other return value.

+

This callback is optional because it is rarely necessary. Cleanup should be done in separate processes directly (by monitoring the handler process to detect when it exits).

+

Cowboy does not reuse processes for different requests. The process will terminate soon after this call returns.

+ -- cgit v1.2.3