From 849fab7227a2fd1ff5fa4d603ba89037e1c462b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 26 May 2020 09:54:54 +0200 Subject: Cowboy 2.8.0 --- .../en/cowboy/2.8/manual/cowboy_req.uri/index.html | 258 +++++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 docs/en/cowboy/2.8/manual/cowboy_req.uri/index.html (limited to 'docs/en/cowboy/2.8/manual/cowboy_req.uri/index.html') diff --git a/docs/en/cowboy/2.8/manual/cowboy_req.uri/index.html b/docs/en/cowboy/2.8/manual/cowboy_req.uri/index.html new file mode 100644 index 00000000..aa63991f --- /dev/null +++ b/docs/en/cowboy/2.8/manual/cowboy_req.uri/index.html @@ -0,0 +1,258 @@ + + + + + + + + + + Nine Nines: cowboy_req:uri(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

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.8 + 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 GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + -- cgit v1.2.3