1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
= 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)]
|
