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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
== Transports
A transport defines the interface to interact with a socket.
Transports can be used for connecting, listening and accepting
connections, but also for receiving and sending data. Both
passive and active mode are supported, although all sockets
are initialized as passive.
=== TCP transport
The TCP transport is a thin wrapper around `gen_tcp`.
=== SSL transport
The SSL transport is a thin wrapper around `ssl`.
Ranch depends on `ssl` by default so any necessary
dependencies will start when Ranch is started. It is
possible to remove the dependency when the SSL transport
will not be used. Refer to your release build tool's
documentation for more information.
When embedding Ranch listeners that have an SSL transport,
your application must depend on the `ssl` application for
proper behavior.
=== Sending and receiving data
This section assumes that `Transport` is a valid transport handler
(like `ranch_tcp` or `ranch_ssl`) and `Socket` is a connected
socket obtained through the listener.
You can send data to a socket by calling the `Transport:send/2`
function. The data can be given as `iodata()`, which is defined as
`binary() | iolist()`. All the following calls will work:
.Sending data to the socket
[source,erlang]
----
Transport:send(Socket, <<"Ranch is cool!">>).
Transport:send(Socket, "Ranch is cool!").
Transport:send(Socket, ["Ranch", ["is", "cool!"]]).
Transport:send(Socket, ["Ranch", [<<"is">>, "cool!"]]).
----
You can receive data either in passive or in active mode. Passive mode
means that you will perform a blocking `Transport:recv/3` call, while
active mode means that you will receive the data as a message.
By default, all data will be received as binary. It is possible to
receive data as strings, although this is not recommended as binaries
are a more efficient construct, especially for binary protocols.
Receiving data using passive mode requires a single function call. The
first argument is the socket, and the third argument is a timeout duration
before the call returns with `{error, timeout}`.
The second argument is the amount of data in bytes that we want to receive.
The function will wait for data until it has received exactly this amount.
If you are not expecting a precise size, you can specify 0 which will make
this call return as soon as data was read, regardless of its size.
.Receiving data from the socket in passive mode
[source,erlang]
{ok, Data} = Transport:recv(Socket, 0, 5000).
Active mode requires you to inform the socket that you want to receive
data as a message and to write the code to actually receive it.
There are three kinds of active modes: `{active, once}`, `{active, N}`
and `{active, true}`. The first will send a single message before going
back to passive mode; the second will send `N` messages followed by
a `Passive` message when switching back to passive mode; the third
will send messages indefinitely. We recommend not using the `{active, true}`
mode as it could quickly flood your process mailbox. It's better to keep
the data in the socket and read it only when required.
Four different messages can be received:
* Incoming data: `{OK, Socket, Data}`
* Socket closed: `{Closed, Socket}`
* Socket error: `{Error, Socket, Reason}`
* Switch to passive mode: `{Passive, Socket}`
The value of `OK`, `Closed`, `Error` and `Passive` can be different
depending on the transport being used. To be able to properly match
on them you must first call the `Transport:messages/0` function.
.Retrieving the transport's active message identifiers
[source,erlang]
{OK, Closed, Error, Passive} = Transport:messages().
To start receiving messages you will need to call the `Transport:setopts/2`
function, and do so every time you want to receive data.
.Receiving messages from the socket in active mode
[source,erlang]
----
{OK, Closed, Error, Passive} = Transport:messages(),
Transport:setopts(Socket, [{active, once}]),
receive
{OK, Socket, Data} ->
io:format("data received: ~p~n", [Data]);
{Closed, Socket} ->
io:format("socket got closed!~n");
{Error, Socket, Reason} ->
io:format("error happened: ~p~n", [Reason])
end.
----
You can easily integrate active sockets with existing Erlang code as all
you really need is just a few more clauses when receiving messages.
=== Sending files
As in the previous section it is assumed `Transport` is a valid transport
handler and `Socket` is a connected socket obtained through the listener.
To send a whole file, with name `Filename`, over a socket:
.Sending a file by filename
[source,erlang]
{ok, SentBytes} = Transport:sendfile(Socket, Filename).
Or part of a file, with `Offset` greater than or equal to 0, `Bytes` number of
bytes and chunks of size `ChunkSize`:
.Sending part of a file by filename in chunks
[source,erlang]
Opts = [{chunk_size, ChunkSize}],
{ok, SentBytes} = Transport:sendfile(Socket, Filename, Offset, Bytes, Opts).
To improve efficiency when sending multiple parts of the same file it is also
possible to use a file descriptor opened in raw mode:
.Sending a file opened in raw mode
[source,erlang]
{ok, RawFile} = file:open(Filename, [raw, read, binary]),
{ok, SentBytes} = Transport:sendfile(Socket, RawFile, Offset, Bytes, Opts).
=== Upgrading a TCP socket to SSL
A connected TCP socket can be upgraded to a SSL socket via the function
`ranch_ssl:handshake/3`. The socket *must* be in `{active, false}` mode
before telling the client that the server is ready to upgrade in order
to avoid race conditions.
.Performing a TLS handshake on a TCP socket
[source,erlang]
{ok, NewSocket} = ranch_ssl:handshake(Socket, SslOpts, 5000).
=== Writing a transport handler
A transport handler is a module implementing the `ranch_transport` behavior.
It defines a certain number of callbacks that must be written in order to
allow transparent usage of the transport handler.
The behavior doesn't define the socket options available when opening a
socket. These do not need to be common to all transports as it's easy enough
to write different initialization functions for the different transports that
will be used. With one exception though. The `setopts/2` function *must*
implement the `{active, once}` and the `{active, true}` options.
If the transport handler doesn't have a native implementation of `sendfile/5` a
fallback is available, `ranch_transport:sendfile/6`. The extra first argument
is the transport's module. See `ranch_ssl` for an example.
|
