From 3099fc1d9f33e791cc1edfd585bbfb2d4be30a92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 20 Jul 2017 18:28:06 +0200 Subject: Remove cowboy_sub_protocol from the documentation This will be reintroduced in a future release once the interface stabilizes. For the time being it will be an internal module only. --- doc/src/guide/book.asciidoc | 3 -- doc/src/guide/handlers.asciidoc | 11 ----- doc/src/guide/sub_protocols.asciidoc | 73 ----------------------------- doc/src/manual/cowboy_app.asciidoc | 1 - doc/src/manual/cowboy_sub_protocol.asciidoc | 27 ----------- 5 files changed, 115 deletions(-) delete mode 100644 doc/src/guide/sub_protocols.asciidoc delete mode 100644 doc/src/manual/cowboy_sub_protocol.asciidoc (limited to 'doc') diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc index 162f28d..8178803 100644 --- a/doc/src/guide/book.asciidoc +++ b/doc/src/guide/book.asciidoc @@ -73,9 +73,6 @@ include::streams.asciidoc[Streams] include::middlewares.asciidoc[Middlewares] -// @todo Rather have two chapters, custom handlers and custom protocol upgrades -include::sub_protocols.asciidoc[Sub protocols] - = Additional information include::migrating_from_1.0.asciidoc[Migrating from Cowboy 1.0 to 2.0] diff --git a/doc/src/guide/handlers.asciidoc b/doc/src/guide/handlers.asciidoc index e073dfb..fe6f462 100644 --- a/doc/src/guide/handlers.asciidoc +++ b/doc/src/guide/handlers.asciidoc @@ -68,17 +68,6 @@ init(Req, State) -> {cowboy_websocket, Req, State}. ---- -You can also switch to your own custom handler type: - -[source,erlang] ----- -init(Req, State) -> - {my_handler_type, Req, State}. ----- - -How to implement a custom handler type is described in the -xref:sub_protocols[Sub protocols] chapter. - === Cleaning up All handler types provide the optional `terminate/3` callback. diff --git a/doc/src/guide/sub_protocols.asciidoc b/doc/src/guide/sub_protocols.asciidoc deleted file mode 100644 index 83fa975..0000000 --- a/doc/src/guide/sub_protocols.asciidoc +++ /dev/null @@ -1,73 +0,0 @@ -[[sub_protocols]] -== Sub protocols - -Sub protocols are used for creating new types of handlers that -provide extra functionality in a reusable way. Cowboy uses this -mechanism to provide its loop, REST and Websocket handlers. - -This chapter will explain how to create your own sub protocols -and handler types. - -=== Usage - -To switch to a sub protocol, the `init/2` callback must return -the name of the sub protocol module. Everything past this point -is handled by the sub protocol. - -[source,erlang] ----- -init(Req, State) -> - {cowboy_websocket, Req, State}. ----- - -The returned tuple may also have a fourth element containing -options for the sub protocol. No option is universal. While -it will usually be a map of options, it doesn't have to be. -For example loop handlers accept the atom `hibernate`. - -The following snippet switches to the `my_protocol` sub -protocol, sets the timeout value to 5 seconds and enables -hibernation: - -[source,erlang] ----- -init(Req, State) -> - {my_protocol, Req, State, #{ - timeout => 5000, - compress => true}}. ----- - -Sub protocols should ignore unknown options so as to not waste -resources doing unnecessary validation. - -=== Upgrade - -After the `init/2` function returns, Cowboy will call either -the `upgrade/4` or the `upgrade/5` function. The former is called -when no options were given; the latter when they were given. - -The function is named `upgrade` because it mimics the mechanism -of HTTP protocol upgrades. For some sub protocols, like Websocket, -an actual upgrade is performed. For others, like REST, this is -only an upgrade at Cowboy's level and the client has nothing to -do about it. - -The upgrade callback receives the Req object, the middleware -environment, the handler and its state, and for `upgrade/5` -also the aformentioned options. - -[source,erlang] ----- -upgrade(Req, Env, Handler, State) -> - %% Sub protocol code here. - -upgrade(Req, Env, Handler, State, Opts) -> - %% Sub protocol code here. ----- - -These callbacks are expected to behave like middlewares and to -return an updated environment and Req object. - -Sub protocols are expected to call the `cowboy_handler:terminate/4` -function when they terminate. This function will make sure that -the optional `terminate/3` callback is called, if present. diff --git a/doc/src/manual/cowboy_app.asciidoc b/doc/src/manual/cowboy_app.asciidoc index 4c5ad69..bc67959 100644 --- a/doc/src/manual/cowboy_app.asciidoc +++ b/doc/src/manual/cowboy_app.asciidoc @@ -43,7 +43,6 @@ Behaviors: * link:man:cowboy_middleware(3)[cowboy_middleware(3)] - Middlewares * link:man:cowboy_rest(3)[cowboy_rest(3)] - REST handlers * link:man:cowboy_stream(3)[cowboy_stream(3)] - Stream handlers -// @todo * link:man:cowboy_sub_protocol(3)[cowboy_sub_protocol(3)] - Sub protocols * link:man:cowboy_websocket(3)[cowboy_websocket(3)] - Websocket handlers Middlewares: diff --git a/doc/src/manual/cowboy_sub_protocol.asciidoc b/doc/src/manual/cowboy_sub_protocol.asciidoc deleted file mode 100644 index 8146a44..0000000 --- a/doc/src/manual/cowboy_sub_protocol.asciidoc +++ /dev/null @@ -1,27 +0,0 @@ -= cowboy_sub_protocol(3) - -== Name - -cowboy_sub_protocol - sub protocol - -== Description - -The `cowboy_sub_protocol` behaviour defines the interface used -by modules that implement a protocol on top of HTTP. - -== Callbacks - -=== upgrade(Req, Env, Handler, HandlerOpts) -> {ok, Req, Env} | {suspend, Module, Function, Args} | {stop, Req} - -Req = cowboy_req:req():: The Req object. -Env = env():: The request environment. -Handler = module():: Handler module. -Opts = any():: Handler options. -Module = module():: MFA to call when resuming the process. -Function = atom():: MFA to call when resuming the process. -Args = [any()]:: MFA to call when resuming the process. - -Upgrade the protocol. - -Please refer to the `cowboy_middleware` manual for a -description of the return values. -- cgit v1.2.3