diff options
Diffstat (limited to 'doc/src/guide/upgrade_protocol.ezdoc')
-rw-r--r-- | doc/src/guide/upgrade_protocol.ezdoc | 61 |
1 files changed, 0 insertions, 61 deletions
diff --git a/doc/src/guide/upgrade_protocol.ezdoc b/doc/src/guide/upgrade_protocol.ezdoc deleted file mode 100644 index ad2d25a..0000000 --- a/doc/src/guide/upgrade_protocol.ezdoc +++ /dev/null @@ -1,61 +0,0 @@ -::: Protocol upgrades - -Cowboy features many different handlers, each for different purposes. -All handlers have a common entry point: the `init/2` function. -This function returns the name of the protocol that will be -used for processing the request, along with various options. - -Cowboy defines four built-in handler types. Three of them are -implemented as sub protocols. More can be implemented by -writing a custom sub protocol. - -The following table lists the built-in handler types. - -|| Alias Module Description -| -| http - Plain HTTP handler -| long_polling cowboy_long_polling Long-polling handler -| rest cowboy_rest REST handler -| ws cowboy_websocket Websocket handler - -Both the alias or the module name can be used to specify the -kind of handler. In addition, a user-defined module name can -be used. - -``` erlang -init(Req, Opts) -> - {my_protocol, Req, Opts}. -``` - -The `init/2` function can also return some extra options for -handlers that are meant to be long running, for example the -`long_polling` and `ws` handler types. These options can also -be passed on to custom sub protocols. For example the following -`init/2` function defines both a timeout value and enables -process hibernation: - -``` erlang -init(Req, Opts) -> - {my_protocol, Req, Opts, 5000, hibernate}. -``` - -It is up to the sub protocol to implement these (or reject -them if they are not supported). - -The `cowboy_sub_protocol` behavior only requires one callback, -`upgrade/6`. It receives the Req object, the middleware environment, -the handler and options for this request, and the timeout and -hibernate values. The default timeout value is `infinity` and -the default hibernate value is `run`. - -``` erlang -upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) -> - %% ... -``` - -This callback is expected to behave like a middleware. Please -see the corresponding chapter for more information. - -Sub protocols are expected to call the `cowboy_handler:terminate/5` -function when they terminate. This function will make sure that -the optional `terminate/3` callback will be called, if present. |