= cowboy(3)
== Name
cowboy - HTTP server
== Description
The `cowboy` module provides convenience functions for
manipulating Ranch listeners.
== Types
=== fields() = [Field]
[source,erlang]
----
Field = atom()
| {atom(), cowboy_constraints:constraint() | [cowboy_constraints:constraint()]}
| {atom(), cowboy_constraints:constraint() | [cowboy_constraints:constraint()], 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()
HTTP status.
A binary status can be used to set a custom message.
=== 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.
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.
== Exports
=== start_http(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}
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.
=== start_spdy(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_spdy:opts():: SPDY protocol options.
Start listening for SPDY 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.
== See also
The http://ninenines.eu/docs/en/ranch/HEAD/guide[Ranch guide]
provides detailed information about how listeners work.
