cowboy_req:uri(3)

Name

cowboy_req:uri - Reconstructed URI

Description

uri(Req :: cowboy_req:req())       -> uri(Req, #{})
uri(Req :: cowboy_req:req(), Opts) -> URI :: iodata()

Opts :: #{
    scheme   => iodata()           | undefined,
    host     => iodata()           | undefined,
    port     => inet:port_number() | undefined,
    path     => iodata()           | undefined,
    qs       => iodata()           | undefined,
    fragment => iodata()           | undefined
}

Reconstruct the effective request URI, optionally modifying components.

By default Cowboy will build a URI using the components found in the request. Options allow disabling or replacing individual components.

Arguments

Req

The Req object.

Opts

Map for overriding individual components.

To replace a component, provide its new value as a binary string or an iolist. To disable a component, set its value to undefined.

As this function always returns a valid URI, there are some things to note:

• Disabling the host also disables the scheme and port.
• There is no fragment component by default as these are not sent with the request.
• The port number may not appear in the resulting URI if it is the default port for the given scheme (http: 80; https: 443).

Return value

The reconstructed URI is returned as an iolist or a binary string.

Changelog

• 2.0: Individual components can be replaced or disabled.
• 2.0: Only the URI is returned, it is no longer wrapped in a tuple.
• 2.0: Function introduced. Replaces host_url/1 and url/1.

Examples

With an effective request URI http://example.org/path/to/res?edit=1 we can have:

%% //example.org/path/to/res?edit=1
cowboy_req:uri(Req, #{scheme => undefined}).

%% http://example.org
cowboy_req:uri(Req, #{path => undefined, qs => undefined}).

%% /path/to/res?edit=1
cowboy_req:uri(Req, #{host => undefined}).

%% http://example.org/path/to/res?edit=1#errors
cowboy_req:uri(Req, #{fragment => <<"errors">>}).

%% https://example.org/path/to/res?edit=1
cowboy_req:uri(Req, #{scheme => <<"https">>}).

iolist_to_binary(cowboy_req:uri(Req)).

See also

cowboy_req(3), cowboy_req:scheme(3), cowboy_req:host(3), cowboy_req:port(3), cowboy_req:path(3), cowboy_req:qs(3)