diff options
authorLoïc Hoguin <[email protected]>2017-07-20 18:28:06 +0200
committerLoïc Hoguin <[email protected]>2017-07-20 18:28:06 +0200
commit3099fc1d9f33e791cc1edfd585bbfb2d4be30a92 (patch)
parente4cab480dc2562378d9d046069bce2e5ab90dabd (diff)
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.
5 files changed, 0 insertions, 115 deletions
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]
-// @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:
-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 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.
-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
-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.
-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
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.