mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 12:40:25 +00:00
116 lines
2.8 KiB
Text
116 lines
2.8 KiB
Text
= cowboy_req:uri(3)
|
|
|
|
== Name
|
|
|
|
cowboy_req:uri - Reconstructed URI
|
|
|
|
== Description
|
|
|
|
[source,erlang]
|
|
----
|
|
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
|
|
[source,erlang]
|
|
----
|
|
%% //example.org/path/to/res?edit=1
|
|
cowboy_req:uri(Req, #{scheme => undefined}).
|
|
----
|
|
|
|
.Serialized origin for use in the origin header
|
|
[source,erlang]
|
|
----
|
|
%% http://example.org
|
|
cowboy_req:uri(Req, #{path => undefined, qs => undefined}).
|
|
----
|
|
|
|
.HTTP/1.1 origin form (path and query string only)
|
|
[source,erlang]
|
|
----
|
|
%% /path/to/res?edit=1
|
|
cowboy_req:uri(Req, #{host => undefined}).
|
|
----
|
|
|
|
.Add a fragment to the URI
|
|
[source,erlang]
|
|
----
|
|
%% http://example.org/path/to/res?edit=1#errors
|
|
cowboy_req:uri(Req, #{fragment => <<"errors">>}).
|
|
----
|
|
|
|
.Ensure the scheme is HTTPS
|
|
[source,erlang]
|
|
----
|
|
%% https://example.org/path/to/res?edit=1
|
|
cowboy_req:uri(Req, #{scheme => <<"https">>}).
|
|
----
|
|
|
|
.Convert the URI to a binary string
|
|
[source,erlang]
|
|
----
|
|
iolist_to_binary(cowboy_req:uri(Req)).
|
|
----
|
|
|
|
== See also
|
|
|
|
link:man:cowboy_req(3)[cowboy_req(3)],
|
|
link:man:cowboy_req:scheme(3)[cowboy_req:scheme(3)],
|
|
link:man:cowboy_req:host(3)[cowboy_req:host(3)],
|
|
link:man:cowboy_req:port(3)[cowboy_req:port(3)],
|
|
link:man:cowboy_req:path(3)[cowboy_req:path(3)],
|
|
link:man:cowboy_req:qs(3)[cowboy_req:qs(3)]
|