mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 04:30:25 +00:00
Update manual for the cowboy module
This commit separates the documentation of the functions into separate manual pages, with at least one example per function and a lot more details about parameters, return values and related functions and modules. It also includes a changelog indicating when the function was added or changed. The inspiration for this comes mainly from the PHP documentation and feedback from users.
This commit is contained in:
Loïc Hoguin
parent
31cabe0fb9
commit
0424724062
5 changed files with 455 additions and 53 deletions
|
|
@ -9,80 +9,91 @@ cowboy - HTTP server
|
|||
The `cowboy` module provides convenience functions for
|
||||
manipulating Ranch listeners.
|
||||
|
||||
== Exports
|
||||
|
||||
* link:man:cowboy:start_clear(3)[cowboy:start_clear(3)] - Listen for connections using plain TCP
|
||||
* link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] - Listen for connections using TLS
|
||||
* link:man:cowboy:stop_listener(3)[cowboy:stop_listener(3)] - Stop the given listener
|
||||
* link:man:cowboy:set_env(3)[cowboy:set_env(3)] - Update a listener's environment value
|
||||
|
||||
== Types
|
||||
|
||||
=== fields() = [Field]
|
||||
=== fields()
|
||||
|
||||
[source,erlang]
|
||||
----
|
||||
Field = atom()
|
||||
| {atom(), cowboy_constraints:constraint() | [cowboy_constraints:constraint()]}
|
||||
| {atom(), cowboy_constraints:constraint() | [cowboy_constraints:constraint()], any()}]
|
||||
fields() :: [Name
|
||||
| {Name, Constraints}
|
||||
| {Name, Constraints, Default}]
|
||||
|
||||
Name :: atom()
|
||||
Constraints :: Constraint | [Constraint]
|
||||
Constraint :: cowboy_constraints:constraint()
|
||||
Default :: any()
|
||||
----
|
||||
|
||||
Fields for match operations. Constraint(s) and default value are optional.
|
||||
Fields description for match operations.
|
||||
|
||||
=== http_headers() = [{binary(), iodata()}]
|
||||
This type is used in link:man:cowboy_router(3)[cowboy_router]
|
||||
for matching bindings and in the match functions found in
|
||||
link:man:cowboy_req(3)[cowboy_req].
|
||||
|
||||
HTTP headers as a list of key/values.
|
||||
=== http_headers()
|
||||
|
||||
=== http_status() = non_neg_integer() | binary()
|
||||
[source,erlang]
|
||||
----
|
||||
http_headers() :: #{binary() => iodata()}
|
||||
----
|
||||
|
||||
HTTP status.
|
||||
HTTP headers.
|
||||
|
||||
A binary status can be used to set a custom message.
|
||||
=== http_status()
|
||||
|
||||
=== http_version() = \'HTTP/1.1' | \'HTTP/1.0'
|
||||
[source,erlang]
|
||||
----
|
||||
http_status() :: non_neg_integer() | binary()
|
||||
----
|
||||
|
||||
HTTP response status.
|
||||
|
||||
A binary status can be used to set a reason phrase. Note
|
||||
however that HTTP/2 only sends the status code and drops
|
||||
the reason phrase entirely.
|
||||
|
||||
=== http_version()
|
||||
|
||||
[source,erlang]
|
||||
----
|
||||
http_version() :: 'HTTP/2' | 'HTTP/1.1' | 'HTTP/1.0'
|
||||
----
|
||||
|
||||
HTTP version.
|
||||
|
||||
=== `onresponse_fun() = fun((http_status(), http_headers(), iodata(), cowboy_req:req()) -> cowboy_req:req())`
|
||||
Note that semantically, HTTP/1.1 and HTTP/2 are equivalent.
|
||||
|
||||
Fun called immediately before sending the response.
|
||||
=== opts()
|
||||
|
||||
It can perform any operation on the Req object, including
|
||||
reading the request body or replying. If a reply is sent, it
|
||||
overrides the reply initially sent. The callback will not be
|
||||
called again for the new reply.
|
||||
[source,erlang]
|
||||
----
|
||||
opts() :: map()
|
||||
----
|
||||
|
||||
== Exports
|
||||
Options for the HTTP/1.1, HTTP/2 and Websocket protocols.
|
||||
|
||||
=== start_http(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}
|
||||
The protocol options are in a map containing all the options for
|
||||
the different protocols that may be involved when connecting
|
||||
to the listener, including HTTP/1.1 and HTTP/2 but also
|
||||
subprotocols like Websocket.
|
||||
// @todo For Websocket this might change in the future.
|
||||
|
||||
Ref = ranch:ref():: Listener name.
|
||||
NbAcceptors = non_neg_integer():: Number of acceptor processes.
|
||||
TransOpts = ranch_tcp:opts():: TCP transport options.
|
||||
ProtoOpts = cowboy_protocol:opts():: HTTP protocol options.
|
||||
|
||||
Start listening for HTTP connections. Returns the pid for this
|
||||
listener's supervisor.
|
||||
|
||||
=== start_https(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}
|
||||
|
||||
Ref = ranch:ref():: Listener name.
|
||||
NbAcceptors = non_neg_integer():: Number of acceptor processes.
|
||||
TransOpts = ranch_ssl:opts():: SSL transport options.
|
||||
ProtoOpts = cowboy_protocol:opts():: HTTP protocol options.
|
||||
|
||||
Start listening for HTTPS connections. Returns the pid for this
|
||||
listener's supervisor.
|
||||
|
||||
=== stop_listener(Ref) -> ok | {error, not_found}
|
||||
|
||||
Ref = ranch:ref():: Listener name.
|
||||
|
||||
Stop a previously started listener.
|
||||
|
||||
=== set_env(Ref, Name, Value) -> ok
|
||||
|
||||
Ref = ranch:ref():: Listener name.
|
||||
Name = atom():: Name of environment value.
|
||||
Value = any():: Environment value.
|
||||
|
||||
Set or update an environment value for an already running listener.
|
||||
This will take effect on all subsequent connections.
|
||||
The HTTP/1.1 options are documented in the
|
||||
link:man:cowboy_http(3)[cowboy_http(3)] manual;
|
||||
the HTTP/2 options in
|
||||
link:man:cowboy_http2(3)[cowboy_http2(3)];
|
||||
and the Websocket options in
|
||||
link:man:cowboy_websocket(3)[cowboy_websocket(3)].
|
||||
|
||||
== See also
|
||||
|
||||
The http://ninenines.eu/docs/en/ranch/HEAD/guide[Ranch guide]
|
||||
provides detailed information about how listeners work.
|
||||
link:man:cowboy(7)[cowboy(7)],
|
||||
link:man:ranch(3)[ranch(3)]
|
||||
|
|
|
|||
79
doc/src/manual/cowboy.set_env.asciidoc
Normal file
79
doc/src/manual/cowboy.set_env.asciidoc
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
= cowboy:set_env(3)
|
||||
|
||||
== Name
|
||||
|
||||
cowboy:set_env - Update a listener's environment value
|
||||
|
||||
== Description
|
||||
|
||||
[source,erlang]
|
||||
----
|
||||
set_env(Name :: ranch:ref(),
|
||||
Key :: atom(),
|
||||
Value :: any())
|
||||
-> ok
|
||||
----
|
||||
|
||||
Set or update an environment value for a previously started
|
||||
listener.
|
||||
|
||||
This is most useful for updating the routes dynamically,
|
||||
without having to restart the listener.
|
||||
|
||||
The new value will only be available to new connections.
|
||||
Pre-existing connections will still use the old value.
|
||||
|
||||
== Arguments
|
||||
|
||||
Name::
|
||||
|
||||
The name of the listener to update.
|
||||
+
|
||||
The name of the listener is the first argument given to the
|
||||
link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
|
||||
link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] or
|
||||
link:man:ranch:start_listener(3)[ranch:start_listener(3)] function.
|
||||
|
||||
Key::
|
||||
|
||||
The key in the environment map. Common keys include `dispatch`
|
||||
and `middlewares`.
|
||||
|
||||
Value::
|
||||
|
||||
The new value.
|
||||
|
||||
The type of the value differs depending on the key.
|
||||
|
||||
== Return value
|
||||
|
||||
The atom `ok` is returned on success.
|
||||
|
||||
An `exit:badarg` exception is thrown when the listener does
|
||||
not exist.
|
||||
|
||||
== Changelog
|
||||
|
||||
* *1.0*: Function introduced.
|
||||
|
||||
== Examples
|
||||
|
||||
.Update a listener's routes
|
||||
[source,erlang]
|
||||
----
|
||||
Dispatch = cowboy_router:compile([
|
||||
{'_', [
|
||||
{"/", toppage_h, []},
|
||||
{"/ws", websocket_h, []}
|
||||
]}
|
||||
]),
|
||||
|
||||
cowboy:set_env(example, dispatch, Dispatch).
|
||||
----
|
||||
|
||||
== See also
|
||||
|
||||
link:man:cowboy(3)[cowboy(3)],
|
||||
link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
|
||||
link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
|
||||
link:man:ranch:set_protocol_options(3)[ranch:set_protocol_options(3)]
|
||||
126
doc/src/manual/cowboy.start_clear.asciidoc
Normal file
126
doc/src/manual/cowboy.start_clear.asciidoc
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
= cowboy:start_clear(3)
|
||||
|
||||
== Name
|
||||
|
||||
cowboy:start_clear - Listen for connections using plain TCP
|
||||
|
||||
== Description
|
||||
|
||||
[source,erlang]
|
||||
----
|
||||
start_clear(Name :: ranch:ref(),
|
||||
NumAcceptors :: non_neg_integer(),
|
||||
TransportOpts :: ranch_tcp:opts(),
|
||||
ProtocolOpts :: opts())
|
||||
-> {ok, ListenerPid :: pid()}
|
||||
| {error, any()}
|
||||
----
|
||||
|
||||
Start listening for connections over a clear TCP channel.
|
||||
|
||||
Both HTTP/1.1 and HTTP/2 are supported on this listener.
|
||||
HTTP/2 has two methods of establishing a connection over
|
||||
a clear TCP channel. Both the upgrade and the prior knowledge
|
||||
methods are supported.
|
||||
|
||||
== Arguments
|
||||
|
||||
Name::
|
||||
|
||||
The listener name is used to refer to this listener in
|
||||
future calls, for example when stopping it or when
|
||||
updating the routes defined.
|
||||
+
|
||||
It can be any Erlang term. An atom is generally good enough,
|
||||
for example `api`, `my_app_clear` or `my_app_tls`.
|
||||
|
||||
NumAcceptors::
|
||||
|
||||
The number of acceptors is the number of processes that
|
||||
will accept connections. Tweak this value to improve the
|
||||
accept rate for incoming connections.
|
||||
+
|
||||
The ideal value is between 10 and 100 on most systems.
|
||||
Larger values may have the opposite effect and reduce the
|
||||
accept rate. It's generally safe to start with a value of
|
||||
100 (or 10 on low memory systems). Then, when accept rates
|
||||
become a concern, measure the performance and update the
|
||||
value accordingly.
|
||||
+
|
||||
This value is unrelated to the maximum number of concurrent
|
||||
connections.
|
||||
|
||||
TransportOpts::
|
||||
|
||||
The transport options are where the TCP options, including
|
||||
the listener's port number, are defined. Transport options
|
||||
are provided as a list of keys and values, for example
|
||||
`[{port, 8080}]`.
|
||||
+
|
||||
The available options are documented in the
|
||||
link:man:ranch_tcp(3)[ranch_tcp(3)] manual.
|
||||
|
||||
ProtocolOpts::
|
||||
|
||||
The protocol options are in a map containing all the options for
|
||||
the different protocols that may be involved when connecting
|
||||
to the listener, including HTTP/1.1 and HTTP/2 but also
|
||||
subprotocols like Websocket.
|
||||
// @todo For Websocket this might change in the future.
|
||||
+
|
||||
The HTTP/1.1 options are documented in the
|
||||
link:man:cowboy_http(3)[cowboy_http(3)] manual;
|
||||
the HTTP/2 options in
|
||||
link:man:cowboy_http2(3)[cowboy_http2(3)];
|
||||
and the Websocket options in
|
||||
link:man:cowboy_websocket(3)[cowboy_websocket(3)].
|
||||
|
||||
== Return value
|
||||
|
||||
An ok tuple is returned on success. It contains the pid of
|
||||
the top-level supervisor for the listener.
|
||||
|
||||
An error tuple is returned on error. The error reason may
|
||||
be any Erlang term.
|
||||
|
||||
A common error is `eaddrinuse`. It indicates that the port
|
||||
configured for Cowboy is already in use.
|
||||
|
||||
== Changelog
|
||||
|
||||
* *2.0*: HTTP/2 support added.
|
||||
* *2.0*: Function introduced. Replaces `cowboy:start_http/4`.
|
||||
|
||||
== Examples
|
||||
|
||||
.Start a listener
|
||||
[source,erlang]
|
||||
----
|
||||
Dispatch = cowboy_router:compile([
|
||||
{'_', [
|
||||
{"/", toppage_h, []}
|
||||
]}
|
||||
]),
|
||||
|
||||
{ok, _} = cowboy:start_clear(example, 100, [{port, 8080}], #{
|
||||
env => #{dispatch => Dispatch}
|
||||
}).
|
||||
----
|
||||
|
||||
.Start a listener on a random port
|
||||
[source,erlang]
|
||||
----
|
||||
Name = example,
|
||||
|
||||
{ok, _} = cowboy:start_clear(Name, 100, [], #{
|
||||
env => #{dispatch => Dispatch}
|
||||
}),
|
||||
|
||||
Port = ranch:get_port(Name).
|
||||
----
|
||||
|
||||
== See also
|
||||
|
||||
link:man:cowboy(3)[cowboy(3)],
|
||||
link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
|
||||
link:man:ranch(3)[ranch(3)]
|
||||
131
doc/src/manual/cowboy.start_tls.asciidoc
Normal file
131
doc/src/manual/cowboy.start_tls.asciidoc
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
= cowboy:start_tls(3)
|
||||
|
||||
== Name
|
||||
|
||||
cowboy:start_tls - Listen for connections using TLS
|
||||
|
||||
== Description
|
||||
|
||||
[source,erlang]
|
||||
----
|
||||
start_tls(Name :: ranch:ref(),
|
||||
NumAcceptors :: non_neg_integer(),
|
||||
TransportOpts :: ranch_ssl:opts(),
|
||||
ProtocolOpts :: opts())
|
||||
-> {ok, ListenerPid :: pid()}
|
||||
| {error, any()}
|
||||
----
|
||||
|
||||
Start listening for connections over a secure TLS channel.
|
||||
|
||||
Both HTTP/1.1 and HTTP/2 are supported on this listener.
|
||||
The ALPN TLS extension must be used to initiate an HTTP/2
|
||||
connection.
|
||||
|
||||
== Arguments
|
||||
|
||||
Name::
|
||||
|
||||
The listener name is used to refer to this listener in
|
||||
future calls, for example when stopping it or when
|
||||
updating the routes defined.
|
||||
+
|
||||
It can be any Erlang term. An atom is generally good enough,
|
||||
for example `api`, `my_app_clear` or `my_app_tls`.
|
||||
|
||||
NumAcceptors::
|
||||
|
||||
The number of acceptors is the number of processes that
|
||||
will accept connections. Tweak this value to improve the
|
||||
accept rate for incoming connections.
|
||||
+
|
||||
The ideal value is between 10 and 100 on most systems.
|
||||
Larger values may have the opposite effect and reduce the
|
||||
accept rate. It's generally safe to start with a value of
|
||||
100 (or 10 on low memory systems). Then, when accept rates
|
||||
become a concern, measure the performance and update the
|
||||
value accordingly.
|
||||
+
|
||||
This value is unrelated to the maximum number of concurrent
|
||||
connections.
|
||||
|
||||
TransportOpts::
|
||||
|
||||
The transport options are where the TCP options, including
|
||||
the listener's port number, are defined. They also contain
|
||||
the TLS options, like the server's certificate. Transport options
|
||||
are provided as a list of keys and values, for example
|
||||
`[{port, 8443}, {certfile, "path/to/cert.pem"}]`.
|
||||
+
|
||||
The available options are documented in the
|
||||
link:man:ranch_ssl(3)[ranch_ssl(3)] manual.
|
||||
|
||||
ProtocolOpts::
|
||||
|
||||
The protocol options are in a map containing all the options for
|
||||
the different protocols that may be involved when connecting
|
||||
to the listener, including HTTP/1.1 and HTTP/2 but also
|
||||
subprotocols like Websocket.
|
||||
// @todo For Websocket this might change in the future.
|
||||
+
|
||||
The HTTP/1.1 options are documented in the
|
||||
link:man:cowboy_http(3)[cowboy_http(3)] manual;
|
||||
the HTTP/2 options in
|
||||
link:man:cowboy_http2(3)[cowboy_http2(3)];
|
||||
and the Websocket options in
|
||||
link:man:cowboy_websocket(3)[cowboy_websocket(3)].
|
||||
|
||||
== Return value
|
||||
|
||||
An ok tuple is returned on success. It contains the pid of
|
||||
the top-level supervisor for the listener.
|
||||
|
||||
An error tuple is returned on error. The error reason may
|
||||
be any Erlang term.
|
||||
|
||||
A common error is `eaddrinuse`. It indicates that the port
|
||||
configured for Cowboy is already in use.
|
||||
|
||||
== Changelog
|
||||
|
||||
* *2.0*: HTTP/2 support added.
|
||||
* *2.0*: Function introduced. Replaces `cowboy:start_https/4`.
|
||||
|
||||
== Examples
|
||||
|
||||
.Start a listener
|
||||
[source,erlang]
|
||||
----
|
||||
Dispatch = cowboy_router:compile([
|
||||
{'_', [
|
||||
{"/", toppage_h, []}
|
||||
]}
|
||||
]),
|
||||
|
||||
{ok, _} = cowboy:start_tls(example, 100, [
|
||||
{port, 8443},
|
||||
{cert, "path/to/cert.pem"}
|
||||
], #{
|
||||
env => #{dispatch => Dispatch}
|
||||
}).
|
||||
----
|
||||
|
||||
.Start a listener on a random port
|
||||
[source,erlang]
|
||||
----
|
||||
Name = example,
|
||||
|
||||
{ok, _} = cowboy:start_tls(Name, 100, [
|
||||
{cert, "path/to/cert.pem"}
|
||||
], #{
|
||||
env => #{dispatch => Dispatch}
|
||||
}),
|
||||
|
||||
Port = ranch:get_port(Name).
|
||||
----
|
||||
|
||||
== See also
|
||||
|
||||
link:man:cowboy(3)[cowboy(3)],
|
||||
link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
|
||||
link:man:ranch(3)[ranch(3)]
|
||||
55
doc/src/manual/cowboy.stop_listener.asciidoc
Normal file
55
doc/src/manual/cowboy.stop_listener.asciidoc
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
= cowboy:stop_listener(3)
|
||||
|
||||
== Name
|
||||
|
||||
cowboy:stop_listener - Stop the given listener
|
||||
|
||||
== Description
|
||||
|
||||
[source,erlang]
|
||||
----
|
||||
stop_listener(Name :: ranch:ref())
|
||||
-> ok | {error, not_found}.
|
||||
----
|
||||
|
||||
Stop a previously started listener.
|
||||
|
||||
Alias of link:man:ranch:stop_listener(3)[ranch:stop_listener(3)].
|
||||
|
||||
== Arguments
|
||||
|
||||
Name::
|
||||
|
||||
The name of the listener to be stopped.
|
||||
+
|
||||
The name of the listener is the first argument given to the
|
||||
link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
|
||||
link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] or
|
||||
link:man:ranch:start_listener(3)[ranch:start_listener(3)] function.
|
||||
|
||||
== Return value
|
||||
|
||||
The atom `ok` is returned on success.
|
||||
|
||||
The `{error, not_found}` tuple is returned when the listener
|
||||
does not exist.
|
||||
|
||||
== Changelog
|
||||
|
||||
* *1.0*: Function introduced.
|
||||
|
||||
== Examples
|
||||
|
||||
.Stop a listener
|
||||
[source,erlang]
|
||||
----
|
||||
ok = cowboy:stop_listener(example).
|
||||
----
|
||||
|
||||
== See also
|
||||
|
||||
link:man:cowboy(3)[cowboy(3)],
|
||||
link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
|
||||
link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
|
||||
link:man:ranch(3)[ranch(3)],
|
||||
link:man:ranch:start_listener(3)[ranch:start_listener(3)]
|
||||
Loading…
Add table
Add a link
Reference in a new issue