= 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)]