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:

Protocol relative form
%% //example.org/path/to/res?edit=1
cowboy_req:uri(Req, #{scheme => undefined}).
Serialized origin for use in the origin header
%% http://example.org
cowboy_req:uri(Req, #{path => undefined, qs => undefined}).
HTTP/1.1 origin form (path and query string only)
%% /path/to/res?edit=1
cowboy_req:uri(Req, #{host => undefined}).
Add a fragment to the URI
%% http://example.org/path/to/res?edit=1#errors
cowboy_req:uri(Req, #{fragment => <<"errors">>}).
Ensure the scheme is HTTPS
%% https://example.org/path/to/res?edit=1
cowboy_req:uri(Req, #{scheme => <<"https">>}).
Convert the URI to a binary string
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)

Cowboy 2.6 Function Reference

Navigation

Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.