aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/cowboy.asciidoc
blob: cd83b3df84c5583f9c66cb1b70cc0d8800c35705 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
= 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.