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)