aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/ranch.recv_proxy_header.asciidoc
blob: 9f23bde6e1c9c308f2e8d684003685861a1a0b86 (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
= ranch:recv_proxy_header(3)

== Name

ranch:recv_proxy_header - Receive the PROXY protocol header

== Description

[source,erlang]
----
recv_proxy_header(ranch:ref(), timeout())
    -> {ok, ranch_proxy_header:proxy_info()}
     | {error, Reason :: atom()}
     | {error, protocol_error, HumanReadable :: atom()}
----

Receive the PROXY protocol header.

This function must be called before `ranch:handshake/1,2`
on newly accepted connections to read and parse the PROXY
protocol header, if any.

== Arguments

Ref::

The listener name.

Timeout::

Receive timeout in milliseconds.

== Return value

An `ok` tuple is returned containing PROXY header information
on success.

An `error` 2-tuple is returned when a socket error occurs.

An `error` 3-tuple is returned when a protocol error occurs
and Ranch was not able to parse the PROXY header information.
The third element contains a human-readable description of
the error.

== Changelog

* *1.7*: Function introduced.

== Examples

.Receive the PROXY protocol header
[source,erlang]
----
start_link(Ref, _, Transport, Opts) ->
    Pid = proc_lib:spawn_link(?MODULE, init,
        [Ref, Transport, Opts]),
    {ok, Pid}.

init(Ref, Transport, Opts) ->
    {ok, ProxyInfo} = ranch:recv_proxy_header(Ref, 1000),
    {ok, Socket} = ranch:handshake(Ref),
    loop(#state{ref=Ref, socket=Socket, transport=Transport,
        proxy_info=ProxyInfo, opts=Opts}).
----

== See also

link:man:ranch:start_listener(3)[ranch:start_listener(3)],
link:man:ranch:handshake(3)[ranch:handshake(3)],
link:man:ranch:remove_connection(3)[ranch:remove_connection(3)],
link:man:ranch(3)[ranch(3)]