diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/manual/cowboy.asciidoc | 111 | ||||
| -rw-r--r-- | doc/src/manual/cowboy.set_env.asciidoc | 79 | ||||
| -rw-r--r-- | doc/src/manual/cowboy.start_clear.asciidoc | 126 | ||||
| -rw-r--r-- | doc/src/manual/cowboy.start_tls.asciidoc | 131 | ||||
| -rw-r--r-- | doc/src/manual/cowboy.stop_listener.asciidoc | 55 |
5 files changed, 452 insertions, 50 deletions
diff --git a/doc/src/manual/cowboy.asciidoc b/doc/src/manual/cowboy.asciidoc index 10e3696..6aad091 100644 --- a/doc/src/manual/cowboy.asciidoc +++ b/doc/src/manual/cowboy.asciidoc @@ -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. - -=== http_headers() = [{binary(), iodata()}] - -HTTP headers as a list of key/values. - -=== http_status() = non_neg_integer() | binary() +Fields description for match operations. -HTTP status. +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]. -A binary status can be used to set a custom message. +=== http_headers() -=== http_version() = \'HTTP/1.1' | \'HTTP/1.0' - -HTTP version. - -=== `onresponse_fun() = fun((http_status(), http_headers(), iodata(), cowboy_req:req()) -> cowboy_req:req())` - -Fun called immediately before sending the response. +[source,erlang] +---- +http_headers() :: #{binary() => iodata()} +---- -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. +HTTP headers. -== Exports +=== http_status() -=== start_http(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()} +[source,erlang] +---- +http_status() :: non_neg_integer() | binary() +---- -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. +HTTP response status. -Start listening for HTTP connections. Returns the pid for this -listener's supervisor. +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. -=== start_https(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()} +=== http_version() -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. +[source,erlang] +---- +http_version() :: 'HTTP/2' | 'HTTP/1.1' | 'HTTP/1.0' +---- -Start listening for HTTPS connections. Returns the pid for this -listener's supervisor. +HTTP version. -=== stop_listener(Ref) -> ok | {error, not_found} +Note that semantically, HTTP/1.1 and HTTP/2 are equivalent. -Ref = ranch:ref():: Listener name. +=== opts() -Stop a previously started listener. +[source,erlang] +---- +opts() :: map() +---- -=== set_env(Ref, Name, Value) -> ok +Options for the HTTP/1.1, HTTP/2 and Websocket protocols. -Ref = ranch:ref():: Listener name. -Name = atom():: Name of environment value. -Value = any():: Environment value. +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. -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)] diff --git a/doc/src/manual/cowboy.set_env.asciidoc b/doc/src/manual/cowboy.set_env.asciidoc new file mode 100644 index 0000000..0e67e3e --- /dev/null +++ b/doc/src/manual/cowboy.set_env.asciidoc @@ -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)] diff --git a/doc/src/manual/cowboy.start_clear.asciidoc b/doc/src/manual/cowboy.start_clear.asciidoc new file mode 100644 index 0000000..4903426 --- /dev/null +++ b/doc/src/manual/cowboy.start_clear.asciidoc @@ -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)] diff --git a/doc/src/manual/cowboy.start_tls.asciidoc b/doc/src/manual/cowboy.start_tls.asciidoc new file mode 100644 index 0000000..b85abe6 --- /dev/null +++ b/doc/src/manual/cowboy.start_tls.asciidoc @@ -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)] diff --git a/doc/src/manual/cowboy.stop_listener.asciidoc b/doc/src/manual/cowboy.stop_listener.asciidoc new file mode 100644 index 0000000..7998189 --- /dev/null +++ b/doc/src/manual/cowboy.stop_listener.asciidoc @@ -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)] |