% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{library(http/http_host): Obtain public server location}

\label{sec:httphost}

This library finds the public address of the running server. This can be
used to construct URLs that are visible from anywhere on the internet.
This module was introduced to deal with OpenID, where a request is
redirected to the OpenID server, which in turn redirects to our server
(see \file{http_openid.pl}).

The address is established from the settings \verb$http:public_host$ and
\verb$http:public_port$ if provided. Otherwise it is deduced from the request.\vspace{0.7cm}

\begin{description}
    \predicate[det]{http_public_url}{2}{+Request, -URL}
True when \arg{URL} is an absolute \arg{URL} for the current request.
Typically, the login page should redirect to this \arg{URL} to avoid
losing the session.

    \predicate[det]{http_public_host_url}{2}{+Request, -URL}
True when \arg{URL} is the public \arg{URL} at which this server can be
contacted. This value is not easy to obtain. See
\predref{http_public_host}{4} for the hardest part: find the host and
port.

    \predicate[det]{http_public_host}{4}{?Request, -Hostname, -Port, +Options}
Current global host and port of the HTTP server. This is the
basis to form absolute address, which we need for redirection
based interaction such as the OpenID protocol. \arg{Options} are:

\begin{description}
    \termitem{global}{+Bool}
If \const{true} (default \const{false}), try to replace a local hostname
by a world-wide accessible name.
\end{description}

This predicate performs the following steps to find the host and
port:

\begin{enumerate}
    \item Use the settings \verb$http:public_host$ and \verb$http:public_port$
    \item Use \verb$X-Forwarded-Host$ header, which applies if this server
runs behind a proxy.
    \item Use the \verb$Host$ header, which applies for HTTP 1.1 if we are
contacted directly.
    \item Use \predref{gethostname}{1} to find the host and
\predref{http_current_server}{2} to find the port.
\end{enumerate}

\begin{arguments}
\arg{Request} & is the current request. If it is left unbound,
and the request is needed, it is obtained with
\predref{http_current_request}{1}. \\
\end{arguments}

    \predicate[det]{http_current_host}{4}{?Request, -Hostname, -Port, +Options}

\begin{tags}
    \tag{deprecated}
Use \predref{http_public_host}{4} (same semantics)
\end{tags}
\end{description}