aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/cowboy.start_clear.asciidoc
blob: 4903426ec673ed3d770d05af822a1762e5e79458 (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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
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)]