diff options
Diffstat (limited to 'doc/src/guide/handlers.ezdoc')
-rw-r--r-- | doc/src/guide/handlers.ezdoc | 99 |
1 files changed, 0 insertions, 99 deletions
diff --git a/doc/src/guide/handlers.ezdoc b/doc/src/guide/handlers.ezdoc deleted file mode 100644 index 9336488..0000000 --- a/doc/src/guide/handlers.ezdoc +++ /dev/null @@ -1,99 +0,0 @@ -::: Handlers - -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^req and the options -defined during the ^"router configuration^routing^. - -A handler that does nothing would look like this: - -``` erlang -init(Req, _Opts) -> - {ok, Req, #state{}}. -``` - -Despite sending no reply, a `204 No Content` reply will be -sent to the client, as Cowboy makes sure that a reply is -sent for every request. - -We need to use the Req object for sending a reply. - -``` erlang -init(Req, _Opts) -> - Req2 = cowboy_req:reply(200, [ - {<<"content-type">>, <<"text/plain">>} - ], <<"Hello World!">>, Req), - {ok, Req2, #state{}}. -``` - -As you can see we return a 3-tuple. `ok` means that the -handler ran successfully. The Req object is returned as -it may have been modified as is the case here: replying -returns a modified Req object that you need to return -back to Cowboy for proper operations. - -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 -`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^rest_handlers^, ^"cowboy_websocket^ws_handlers^ -and ^"cowboy_loop^loop_handlers^. 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: - -``` erlang -init(Req, _Opts) -> - {cowboy_websocket, Req, #state{}}. -``` - -You can also switch to your own custom handler type: - -``` erlang -init(Req, _Opts) -> - {my_handler_type, Req, #state{}}. -``` - -How to implement a custom handler type is described in the -^"Sub protocols^sub_protocols chapter. - -:: Cleaning up - -All handlers coming with Cowboy allow the use of the optional -`terminate/3` callback. - -``` erlang -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. - -If you used the process dictionary, timers, monitors or may -be receiving messages, then you can use this function to clean -them up, as Cowboy might reuse the process for the next -keep-alive request. - -Note that while this function may be called in a Websocket -handler, it is generally not useful to do any clean up as -the process terminates immediately after calling this callback -when using Websocket. |