diff options
| author | Loïc Hoguin <[email protected]> | 2016-08-29 12:39:49 +0200 |
|---|---|---|
| committer | Loïc Hoguin <[email protected]> | 2016-08-29 12:40:03 +0200 |
| commit | c807880f7ac73f813b2660ea81a00f7712a4e793 (patch) | |
| tree | ba1d09e9b177f230665a80513b33fbd532000ce4 /docs/en | |
| parent | b1df25a7d9cda697513650659b781b55b40898f8 (diff) | |
| download | ninenines.eu-c807880f7ac73f813b2660ea81a00f7712a4e793.tar.gz ninenines.eu-c807880f7ac73f813b2660ea81a00f7712a4e793.tar.bz2 ninenines.eu-c807880f7ac73f813b2660ea81a00f7712a4e793.zip | |
Add old mailing list archives
Diffstat (limited to 'docs/en')
46 files changed, 1278 insertions, 1589 deletions
diff --git a/docs/en/cowboy/2.0/guide/erlang_beginners.asciidoc b/docs/en/cowboy/2.0/guide/erlang_beginners.asciidoc deleted file mode 100644 index b9a6c655..00000000 --- a/docs/en/cowboy/2.0/guide/erlang_beginners.asciidoc +++ /dev/null @@ -1,36 +0,0 @@ -[[erlang_beginners]] -== Erlang for beginners - -Chances are you are interested in using Cowboy, but have -no idea how to write an Erlang program. Fear not! This -chapter will help you get started. - -We recommend two books for beginners. You should read them -both at some point, as they cover Erlang from two entirely -different perspectives. - -=== Learn You Some Erlang for Great Good! - -The quickest way to get started with Erlang is by reading -a book with the funny name of http://learnyousomeerlang.com[LYSE], -as we affectionately call it. - -It will get right into the syntax and quickly answer the questions -a beginner would ask themselves, all the while showing funny -pictures and making insightful jokes. - -You can read an early version of the book online for free, -but you really should buy the much more refined paper and -ebook versions. - -=== Programming Erlang - -After writing some code, you will probably want to understand -the very concepts that make Erlang what it is today. These -are best explained by Joe Armstrong, the godfather of Erlang, -in his book http://pragprog.com/book/jaerlang2/programming-erlang[Programming Erlang]. - -Instead of going into every single details of the language, -Joe focuses on the central concepts behind Erlang, and shows -you how they can be used to write a variety of different -applications. diff --git a/docs/en/cowboy/2.0/guide/erlang_beginners/index.html b/docs/en/cowboy/2.0/guide/erlang_beginners/index.html deleted file mode 100644 index 4632dca9..00000000 --- a/docs/en/cowboy/2.0/guide/erlang_beginners/index.html +++ /dev/null @@ -1,175 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - -<head> - <meta charset="utf-8"> - <meta name="viewport" content="width=device-width, initial-scale=1.0"> - <meta name="description" content=""> - <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - - <meta name="generator" content="Hugo 0.15" /> - - <title>Nine Nines: Erlang for beginners</title> - - <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> - - <link href="/css/bootstrap.min.css" rel="stylesheet"> - <link href="/css/99s.css" rel="stylesheet"> - - <link rel="shortcut icon" href="/img/ico/favicon.ico"> - <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> - <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> - <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> - - -</head> - - -<body class=""> - <header id="page-head"> - <div id="topbar" class="container"> - <div class="row"> - <div class="span2"> - <h1 id="logo"><a href="/" title="99s">99s</a></h1> - </div> - <div class="span10"> - - <div id="side-header"> - <nav> - <ul> - <li><a title="Hear my thoughts" href="/articles">Articles</a></li> - <li><a title="Watch my talks" href="/talks">Talks</a></li> - <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> - <li><a title="Request my services" href="/services">Consulting & Training</a></li> - </ul> - </nav> - <ul id="social"> - <li> - <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> - </li> - <li> - <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> - </li> - <li> - <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> - </li> - </ul> - </div> - </div> - </div> - </div> - - -</header> - -<div id="contents" class="two_col"> -<div class="container"> -<div class="row"> -<div id="docs" class="span9 maincol"> - -<h1 class="lined-header"><span>Erlang for beginners</span></h1> - -<div class="paragraph"><p>Chances are you are interested in using Cowboy, but have
-no idea how to write an Erlang program. Fear not! This
-chapter will help you get started.</p></div>
-<div class="paragraph"><p>We recommend two books for beginners. You should read them
-both at some point, as they cover Erlang from two entirely
-different perspectives.</p></div>
-<div class="sect1">
-<h2 id="_learn_you_some_erlang_for_great_good">Learn You Some Erlang for Great Good!</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The quickest way to get started with Erlang is by reading
-a book with the funny name of <a href="http://learnyousomeerlang.com">LYSE</a>,
-as we affectionately call it.</p></div>
-<div class="paragraph"><p>It will get right into the syntax and quickly answer the questions
-a beginner would ask themselves, all the while showing funny
-pictures and making insightful jokes.</p></div>
-<div class="paragraph"><p>You can read an early version of the book online for free,
-but you really should buy the much more refined paper and
-ebook versions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_programming_erlang">Programming Erlang</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>After writing some code, you will probably want to understand
-the very concepts that make Erlang what it is today. These
-are best explained by Joe Armstrong, the godfather of Erlang,
-in his book <a href="http://pragprog.com/book/jaerlang2/programming-erlang">Programming Erlang</a>.</p></div>
-<div class="paragraph"><p>Instead of going into every single details of the language,
-Joe focuses on the central concepts behind Erlang, and shows
-you how they can be used to write a variety of different
-applications.</p></div>
-</div>
-</div>
- - - -</div> - -<div class="span3 sidecol"> - - -<h3> - Cowboy - 2.0 - - User Guide -</h3> - -<ul> - - <li><a href="/docs/en/cowboy/2.0/guide">User Guide</a></li> - - - <li><a href="/docs/en/cowboy/2.0/manual">Function Reference</a></li> - - -</ul> - -<h4 id="docs-nav">Navigation</h4> - -<h4>Version select</h4> -<ul> - - - - <li><a href="/docs/en/cowboy/1.0/guide">1.0</a></li> - - <li><a href="/docs/en/cowboy/2.0/guide">2.0</a></li> - -</ul> - -</div> -</div> -</div> -</div> - - <footer> - <div class="container"> - <div class="row"> - <div class="span6"> - <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> - <nav> - <ul> - <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> - </ul> - </nav> - </div> - <div class="span6 credits"> - <p><img src="/img/footer_logo.png"></p> - <p>Copyright © Loïc Hoguin 2012-2016</p> - </div> - </div> - </div> - </footer> - - - <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> - <script src="/js/bootstrap-carousel.js"></script> - <script src="/js/bootstrap-dropdown.js"></script> - <script src="/js/custom.js"></script> - </body> -</html> - - diff --git a/docs/en/cowboy/2.0/guide/erlang_web.asciidoc b/docs/en/cowboy/2.0/guide/erlang_web.asciidoc index 702e0437..e42f8fbb 100644 --- a/docs/en/cowboy/2.0/guide/erlang_web.asciidoc +++ b/docs/en/cowboy/2.0/guide/erlang_web.asciidoc @@ -1,6 +1,10 @@ [[erlang_web]] == Erlang and the Web +Erlang is the ideal platform for writing Web applications. +Its features are a perfect match for the requirements of +modern Web applications. + === The Web is concurrent When you access a website there is little concurrency @@ -130,7 +134,7 @@ their applications to be always available and if it's having too many issues they just move on. Despite this, when developers choose a product to use for building -web applications, their only concern seem to be "Is it fast?", +web applications, their only concern seems to be "Is it fast?", and they look around for synthetic benchmarks showing which one is the fastest at sending "Hello world" with only a handful concurrent connections. Web benchmarks haven't been representative @@ -146,15 +150,15 @@ Erlang is built for fault tolerance. When writing code in any other language, you have to check all the return values and act accordingly to avoid any unforeseen issues. If you're lucky, you won't miss anything important. When writing Erlang code, you can just check -the success condition and ignore all errors. If an error happen, +the success condition and ignore all errors. If an error happens, the Erlang process crashes and is then restarted by a special process called a supervisor. -The Erlang developer thus has no need to fear about unhandled +Erlang developers thus have no need to fear unhandled errors, and can focus on handling only the errors that should give some feedback to the user and let the system take care of -the rest. This also has the advantage of allowing him to write -a lot less code, and letting him sleep at night. +the rest. This also has the advantage of allowing them to write +a lot less code, and let them sleep at night. Erlang's fault tolerance oriented design is the first piece of what makes it the best choice for the omnipresent, always available @@ -168,9 +172,38 @@ down, or even a data center entirely. Fault tolerance and distribution are important today, and will be vital in the future of the Web. Erlang is ready. -=== Erlang is the ideal platform for the Web +=== Learn Erlang + +If you are new to Erlang, you may want to grab a book or +two to get started. Those are my recommendations as the +author of Cowboy. + +==== The Erlanger Playbook + +The Erlanger Playbook is an ebook I am currently writing, +which covers a number of different topics from code to +documentation to testing Erlang applications. It also has +an Erlang section where it covers directly the building +blocks and patterns, rather than details like the syntax. + +You can most likely read it as a complete beginner, but +you will need a companion book to make the most of it. +Buy it from the http://ninenines.eu[Nine Nines website]. + +==== Programming Erlang + +This book is from one of the creator of Erlang, Joe +Armstrong. It provides a very good explanation of what +Erlang is and why it is so. It serves as a very good +introduction to the language and platform. + +The book is http://pragprog.com/book/jaerlang2/programming-erlang[Programming Erlang], +and it also features a chapter on Cowboy. + +==== Learn You Some Erlang for Great Good! -Erlang provides all the important features that the Web requires -or will require in the near future. Erlang is a perfect match -for the Web, and it only makes sense to use it to build web -applications. +http://learnyousomeerlang.com[LYSE] is a much more complete +book covering many aspects of Erlang, while also providing +stories and humor. Be warned: it's pretty verbose. It comes +with a free online version and a more refined paper and +ebook version. diff --git a/docs/en/cowboy/2.0/guide/erlang_web/index.html b/docs/en/cowboy/2.0/guide/erlang_web/index.html index 8206392a..111e2698 100644 --- a/docs/en/cowboy/2.0/guide/erlang_web/index.html +++ b/docs/en/cowboy/2.0/guide/erlang_web/index.html @@ -69,6 +69,9 @@ <h1 class="lined-header"><span>Erlang and the Web</span></h1> +<div class="paragraph"><p>Erlang is the ideal platform for writing Web applications.
+Its features are a perfect match for the requirements of
+modern Web applications.</p></div>
<div class="sect1">
<h2 id="_the_web_is_concurrent">The Web is concurrent</h2>
<div class="sectionbody">
@@ -185,7 +188,7 @@ tend to not stick around when problems arise. Users today want their applications to be always available and if it’s having
too many issues they just move on.</p></div>
<div class="paragraph"><p>Despite this, when developers choose a product to use for building
-web applications, their only concern seem to be "Is it fast?",
+web applications, their only concern seems to be "Is it fast?",
and they look around for synthetic benchmarks showing which one
is the fastest at sending "Hello world" with only a handful
concurrent connections. Web benchmarks haven’t been representative
@@ -199,14 +202,14 @@ Erlang.</p></div> language, you have to check all the return values and act accordingly
to avoid any unforeseen issues. If you’re lucky, you won’t miss
anything important. When writing Erlang code, you can just check
-the success condition and ignore all errors. If an error happen,
+the success condition and ignore all errors. If an error happens,
the Erlang process crashes and is then restarted by a special
process called a supervisor.</p></div>
-<div class="paragraph"><p>The Erlang developer thus has no need to fear about unhandled
+<div class="paragraph"><p>Erlang developers thus have no need to fear unhandled
errors, and can focus on handling only the errors that should
give some feedback to the user and let the system take care of
-the rest. This also has the advantage of allowing him to write
-a lot less code, and letting him sleep at night.</p></div>
+the rest. This also has the advantage of allowing them to write
+a lot less code, and let them sleep at night.</p></div>
<div class="paragraph"><p>Erlang’s fault tolerance oriented design is the first piece of
what makes it the best choice for the omnipresent, always available
Web.</p></div>
@@ -219,12 +222,39 @@ vital in the future of the Web. Erlang is ready.</p></div> </div>
</div>
<div class="sect1">
-<h2 id="_erlang_is_the_ideal_platform_for_the_web">Erlang is the ideal platform for the Web</h2>
+<h2 id="_learn_erlang">Learn Erlang</h2>
<div class="sectionbody">
-<div class="paragraph"><p>Erlang provides all the important features that the Web requires
-or will require in the near future. Erlang is a perfect match
-for the Web, and it only makes sense to use it to build web
-applications.</p></div>
+<div class="paragraph"><p>If you are new to Erlang, you may want to grab a book or
+two to get started. Those are my recommendations as the
+author of Cowboy.</p></div>
+<div class="sect3">
+<h4 id="_the_erlanger_playbook">The Erlanger Playbook</h4>
+<div class="paragraph"><p>The Erlanger Playbook is an ebook I am currently writing,
+which covers a number of different topics from code to
+documentation to testing Erlang applications. It also has
+an Erlang section where it covers directly the building
+blocks and patterns, rather than details like the syntax.</p></div>
+<div class="paragraph"><p>You can most likely read it as a complete beginner, but
+you will need a companion book to make the most of it.
+Buy it from the <a href="http://ninenines.eu">Nine Nines website</a>.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_programming_erlang">Programming Erlang</h4>
+<div class="paragraph"><p>This book is from one of the creator of Erlang, Joe
+Armstrong. It provides a very good explanation of what
+Erlang is and why it is so. It serves as a very good
+introduction to the language and platform.</p></div>
+<div class="paragraph"><p>The book is <a href="http://pragprog.com/book/jaerlang2/programming-erlang">Programming Erlang</a>,
+and it also features a chapter on Cowboy.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_learn_you_some_erlang_for_great_good">Learn You Some Erlang for Great Good!</h4>
+<div class="paragraph"><p><a href="http://learnyousomeerlang.com">LYSE</a> is a much more complete
+book covering many aspects of Erlang, while also providing
+stories and humor. Be warned: it’s pretty verbose. It comes
+with a free online version and a more refined paper and
+ebook version.</p></div>
+</div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/guide/getting_started.asciidoc b/docs/en/cowboy/2.0/guide/getting_started.asciidoc index 679d9fe3..e9a27567 100644 --- a/docs/en/cowboy/2.0/guide/getting_started.asciidoc +++ b/docs/en/cowboy/2.0/guide/getting_started.asciidoc @@ -13,11 +13,14 @@ Cowboy, writing your first application and generating your first release. At the end of this chapter you should know everything you need to push your first Cowboy application to production. -=== Bootstrap +=== Prerequisites We are going to use the https://github.com/ninenines/erlang.mk[Erlang.mk] -build system. It also offers bootstrap features allowing us to -quickly get started without having to deal with minute details. +build system. If you are using Windows, please check the +http://erlang.mk/guide/installation.html[Installation instructions] +to get your environment setup before you continue. + +=== Bootstrap First, let's create the directory for our application. @@ -29,7 +32,7 @@ Then we need to download Erlang.mk. Either use the following command or download it manually. [source,bash] -$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk +$ wget https://erlang.mk/erlang.mk We can now bootstrap our application. Since we are going to generate a release, we will also bootstrap it at the same time. @@ -58,9 +61,8 @@ handler. === Cowboy setup -Modifying the 'Makefile' allows the build system to know it needs to -fetch and compile Cowboy. To do that we simply need to add two lines -to our Makefile to make it look like this: +We will modify the 'Makefile' to tell the build system it needs to +fetch and compile Cowboy: [source,make] ---- @@ -79,10 +81,9 @@ listen for connections. === Listening for connections -We will do this when our application starts. It's a two step process. -First we need to define and compile the dispatch list, a list of -routes that Cowboy will use to map requests to handler modules. -Then we tell Cowboy to listen for connections. +First we define the routes that Cowboy will use to map requests +to handler modules, and then we start the listener. This is best +done at application startup. Open the 'src/hello_erlang_app.erl' file and add the necessary code to the `start/2` function to make it look like this: @@ -93,19 +94,19 @@ start(_Type, _Args) -> Dispatch = cowboy_router:compile([ {'_', [{"/", hello_handler, []}]} ]), - {ok, _} = cowboy:start_http(my_http_listener, 100, [{port, 8080}], - [{env, [{dispatch, Dispatch}]}] + {ok, _} = cowboy:start_clear(my_http_listener, 100, + [{port, 8080}], + #{env => #{dispatch => Dispatch}} ), hello_erlang_sup:start_link(). ---- -The dispatch list is explained in great details in the -xref:routing[Routing] chapter. For this tutorial we map the -path `/` to the handler module `hello_handler`. This module -doesn't exist yet, we still have to write it. +Routes are explained in details in the xref:routing[Routing] +chapter. For this tutorial we map the path `/` to the handler +module `hello_handler`. This module doesn't exist yet. -If you build and start the release, then open http://localhost:8080 -in your browser, you will get an error because the module is missing. +Build and start the release, then open http://localhost:8080 +in your browser. You will get a 500 error because the module is missing. Any other URL, like http://localhost:8080/test, will result in a 404 error. @@ -115,26 +116,26 @@ Cowboy features different kinds of handlers, including REST and Websocket handlers. For this tutorial we will use a plain HTTP handler. -First, let's generate a handler from a template. +Generate a handler from a template: [source,bash] $ make new t=cowboy_http n=hello_handler -You can then open the 'src/hello_handler.erl' file and modify +Then, open the 'src/hello_handler.erl' file and modify the `init/2` function like this to send a reply. [source,erlang] ---- -init(Req, Opts) -> - Req2 = cowboy_req:reply(200, - [{<<"content-type">>, <<"text/plain">>}], +init(Req0, State) -> + Req = cowboy_req:reply(200, + #{<<"content-type">> => <<"text/plain">>}, <<"Hello Erlang!">>, - Req), - {ok, Req2, Opts}. + Req0), + {ok, Req, State}. ---- What the above code does is send a `200 OK` reply, with the -`content-type` header set to `text/plain` and the response +Content-type header set to `text/plain` and the response body set to `Hello Erlang!`. If you run the release and open http://localhost:8080 diff --git a/docs/en/cowboy/2.0/guide/getting_started/index.html b/docs/en/cowboy/2.0/guide/getting_started/index.html index 065d5572..85cd039d 100644 --- a/docs/en/cowboy/2.0/guide/getting_started/index.html +++ b/docs/en/cowboy/2.0/guide/getting_started/index.html @@ -80,11 +80,17 @@ Cowboy, writing your first application and generating your first release. At the end of this chapter you should know everything
you need to push your first Cowboy application to production.</p></div>
<div class="sect1">
-<h2 id="_bootstrap">Bootstrap</h2>
+<h2 id="_prerequisites">Prerequisites</h2>
<div class="sectionbody">
<div class="paragraph"><p>We are going to use the <a href="https://github.com/ninenines/erlang.mk">Erlang.mk</a>
-build system. It also offers bootstrap features allowing us to
-quickly get started without having to deal with minute details.</p></div>
+build system. If you are using Windows, please check the
+<a href="http://erlang.mk/guide/installation.html">Installation instructions</a>
+to get your environment setup before you continue.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_bootstrap">Bootstrap</h2>
+<div class="sectionbody">
<div class="paragraph"><p>First, let’s create the directory for our application.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
@@ -100,7 +106,7 @@ command or download it manually.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ wget https<span style="color: #990000">:</span>//raw<span style="color: #990000">.</span>githubusercontent<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk/master/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
+<pre><tt>$ wget https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
<div class="paragraph"><p>We can now bootstrap our application. Since we are going to generate
a release, we will also bootstrap it at the same time.</p></div>
<div class="listingblock">
@@ -131,20 +137,10 @@ handler.</p></div> <div class="sect1">
<h2 id="_cowboy_setup">Cowboy setup</h2>
<div class="sectionbody">
-<div class="paragraph"><p>Modifying the <em>Makefile</em> allows the build system to know it needs to
-fetch and compile Cowboy. To do that we simply need to add two lines
-to our Makefile to make it look like this:</p></div>
+<div class="paragraph"><p>We will modify the <em>Makefile</em> to tell the build system it needs to
+fetch and compile Cowboy:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PROJECT =</span> hello_erlang
-
-<span style="color: #009900">DEPS =</span> cowboy
-<span style="color: #009900">dep_cowboy_commit =</span> master
-
-include erlang.mk</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>If you run <code>make run</code> now, Cowboy will be included in the release
and started automatically. This is not enough however, as Cowboy
doesn’t do anything by default. We still need to tell Cowboy to
@@ -154,10 +150,9 @@ listen for connections.</p></div> <div class="sect1">
<h2 id="_listening_for_connections">Listening for connections</h2>
<div class="sectionbody">
-<div class="paragraph"><p>We will do this when our application starts. It’s a two step process.
-First we need to define and compile the dispatch list, a list of
-routes that Cowboy will use to map requests to handler modules.
-Then we tell Cowboy to listen for connections.</p></div>
+<div class="paragraph"><p>First we define the routes that Cowboy will use to map requests
+to handler modules, and then we start the listener. This is best
+done at application startup.</p></div>
<div class="paragraph"><p>Open the <em>src/hello_erlang_app.erl</em> file and add the necessary
code to the <code>start/2</code> function to make it look like this:</p></div>
<div class="listingblock">
@@ -169,16 +164,16 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
{<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">hello_handler</span>, []}]}
]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_http</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #993399">100</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}],
- [{<span style="color: #FF6600">env</span>, [{<span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>}]}]
+ {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #993399">100</span>,
+ [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}],
+ #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}}
),
<span style="font-weight: bold"><span style="color: #000000">hello_erlang_sup:start_link</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The dispatch list is explained in great details in the
-<a href="../routing">Routing</a> chapter. For this tutorial we map the
-path <code>/</code> to the handler module <code>hello_handler</code>. This module
-doesn’t exist yet, we still have to write it.</p></div>
-<div class="paragraph"><p>If you build and start the release, then open <a href="http://localhost:8080">http://localhost:8080</a>
-in your browser, you will get an error because the module is missing.
+<div class="paragraph"><p>Routes are explained in details in the <a href="../routing">Routing</a>
+chapter. For this tutorial we map the path <code>/</code> to the handler
+module <code>hello_handler</code>. This module doesn’t exist yet.</p></div>
+<div class="paragraph"><p>Build and start the release, then open <a href="http://localhost:8080">http://localhost:8080</a>
+in your browser. You will get a 500 error because the module is missing.
Any other URL, like <a href="http://localhost:8080/test">http://localhost:8080/test</a>, will result in a
404 error.</p></div>
</div>
@@ -189,28 +184,28 @@ Any other URL, like <a href="http://localhost:8080/test">http://localhost:8080/t <div class="paragraph"><p>Cowboy features different kinds of handlers, including REST
and Websocket handlers. For this tutorial we will use a plain
HTTP handler.</p></div>
-<div class="paragraph"><p>First, let’s generate a handler from a template.</p></div>
+<div class="paragraph"><p>Generate a handler from a template:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ make new <span style="color: #009900">t</span><span style="color: #990000">=</span>cowboy_http <span style="color: #009900">n</span><span style="color: #990000">=</span>hello_handler</tt></pre></div></div>
-<div class="paragraph"><p>You can then open the <em>src/hello_handler.erl</em> file and modify
+<div class="paragraph"><p>Then, open the <em>src/hello_handler.erl</em> file and modify
the <code>init/2</code> function like this to send a reply.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>,
- [{<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>}],
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>,
+ #{<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>},
<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello Erlang!"</span><span style="color: #990000">>></span>,
- <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req2</span>, <span style="color: #009900">Opts</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+ <span style="color: #009900">Req0</span>),
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>What the above code does is send a <code>200 OK</code> reply, with the
-<code>content-type</code> header set to <code>text/plain</code> and the response
+Content-type header set to <code>text/plain</code> and the response
body set to <code>Hello Erlang!</code>.</p></div>
<div class="paragraph"><p>If you run the release and open <a href="http://localhost:8080">http://localhost:8080</a>
in your browser, you should get a nice <code>Hello Erlang!</code> displayed!</p></div>
diff --git a/docs/en/cowboy/2.0/guide/handlers.asciidoc b/docs/en/cowboy/2.0/guide/handlers.asciidoc index b6cefddc..a59b8cf6 100644 --- a/docs/en/cowboy/2.0/guide/handlers.asciidoc +++ b/docs/en/cowboy/2.0/guide/handlers.asciidoc @@ -9,42 +9,42 @@ The most basic handler in Cowboy implements the mandatory `init/2` callback, manipulates the request, optionally sends a response and then returns. -This callback receives the xref:req[Req object] and the options -defined during the xref:routing[router configuration]. +This callback receives the xref:req[Req object] and the initial +state defined in the xref:routing[router configuration]. A handler that does nothing would look like this: [source,erlang] ---- -init(Req, _Opts) -> - {ok, Req, #state{}}. +init(Req, State) -> + {ok, Req, State}. ---- -Despite sending no reply, a `204 No Content` reply will be -sent to the client, as Cowboy makes sure that a reply is +Despite sending no reply, a `204 No Content` response will be +sent to the client, as Cowboy makes sure that a response is sent for every request. -We need to use the Req object for sending a reply. +We need to use the Req object to reply. [source,erlang] ---- -init(Req, _Opts) -> - Req2 = cowboy_req:reply(200, [ +init(Req0, State) -> + Req = cowboy_req:reply(200, [ {<<"content-type">>, <<"text/plain">>} - ], <<"Hello World!">>, Req), - {ok, Req2, #state{}}. + ], <<"Hello World!">>, Req0), + {ok, Req, State}. ---- -As you can see we return a 3-tuple. `ok` means that the -handler ran successfully. The Req object is returned as -it may have been modified as is the case here: replying -returns a modified Req object that you need to return -back to Cowboy for proper operations. +Cowboy will immediately send a response when `cowboy:reply/4` +is called. + +We then return a 3-tuple. `ok` means that the handler ran +successfully. We also give the modified Req back to Cowboy. The last value of the tuple is a state that will be used in every subsequent callbacks to this handler. Plain HTTP handlers only have one additional callback, the optional -`terminate/3`. +and rarely used `terminate/3`. === Other handlers @@ -64,16 +64,16 @@ following snippet switches to a Websocket handler: [source,erlang] ---- -init(Req, _Opts) -> - {cowboy_websocket, Req, #state{}}. +init(Req, State) -> + {cowboy_websocket, Req, State}. ---- You can also switch to your own custom handler type: [source,erlang] ---- -init(Req, _Opts) -> - {my_handler_type, Req, #state{}}. +init(Req, State) -> + {my_handler_type, Req, State}. ---- How to implement a custom handler type is described in the @@ -81,12 +81,12 @@ xref:sub_protocols[Sub protocols] chapter. === Cleaning up -All handlers coming with Cowboy allow the use of the optional -`terminate/3` callback. +With the exception of Websocket handlers, all handler types +provide the optional `terminate/3` callback. [source,erlang] ---- -terminate(_Reason, Req, State) -> +terminate(_Reason, _Req, _State) -> ok. ---- @@ -94,12 +94,9 @@ This callback is strictly reserved for any required cleanup. You cannot send a response from this function. There is no other return value. -If you used the process dictionary, timers, monitors or may -be receiving messages, then you can use this function to clean -them up, as Cowboy might reuse the process for the next -keep-alive request. +This callback is optional because it is rarely necessary. +Cleanup should be done in separate processes directly (by +monitoring the handler process to detect when it exits). -Note that while this function may be called in a Websocket -handler, it is generally not useful to do any clean up as -the process terminates immediately after calling this callback -when using Websocket. +Cowboy does not reuse processes for different requests. The +process will terminate soon after this call returns. diff --git a/docs/en/cowboy/2.0/guide/handlers/index.html b/docs/en/cowboy/2.0/guide/handlers/index.html index 4d42be27..790b7d28 100644 --- a/docs/en/cowboy/2.0/guide/handlers/index.html +++ b/docs/en/cowboy/2.0/guide/handlers/index.html @@ -76,39 +76,38 @@ <div class="paragraph"><p>The most basic handler in Cowboy implements the mandatory
<code>init/2</code> callback, manipulates the request, optionally
sends a response and then returns.</p></div>
-<div class="paragraph"><p>This callback receives the <a href="../req">Req object</a> and the options
-defined during the <a href="../routing">router configuration</a>.</p></div>
+<div class="paragraph"><p>This callback receives the <a href="../req">Req object</a> and the initial
+state defined in the <a href="../routing">router configuration</a>.</p></div>
<div class="paragraph"><p>A handler that does nothing would look like this:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Despite sending no reply, a <code>204 No Content</code> reply will be
-sent to the client, as Cowboy makes sure that a reply is
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Despite sending no reply, a <code>204 No Content</code> response will be
+sent to the client, as Cowboy makes sure that a response is
sent for every request.</p></div>
-<div class="paragraph"><p>We need to use the Req object for sending a reply.</p></div>
+<div class="paragraph"><p>We need to use the Req object to reply.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, [
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, [
{<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>}
- ], <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello World!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req2</span>, <span style="color: #008080">#state</span>{}}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>As you can see we return a 3-tuple. <code>ok</code> means that the
-handler ran successfully. The Req object is returned as
-it may have been modified as is the case here: replying
-returns a modified Req object that you need to return
-back to Cowboy for proper operations.</p></div>
+ ], <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello World!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Cowboy will immediately send a response when <code>cowboy:reply/4</code>
+is called.</p></div>
+<div class="paragraph"><p>We then return a 3-tuple. <code>ok</code> means that the handler ran
+successfully. We also give the modified Req back to Cowboy.</p></div>
<div class="paragraph"><p>The last value of the tuple is a state that will be used
in every subsequent callbacks to this handler. Plain HTTP
handlers only have one additional callback, the optional
-<code>terminate/3</code>.</p></div>
+and rarely used <code>terminate/3</code>.</p></div>
</div>
</div>
<div class="sect1">
@@ -130,16 +129,16 @@ following snippet switches to a Websocket handler:</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}}<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>You can also switch to your own custom handler type:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">my_handler_type</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}}<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">my_handler_type</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>How to implement a custom handler type is described in the
<a href="../sub_protocols">Sub protocols</a> chapter.</p></div>
</div>
@@ -147,26 +146,23 @@ http://www.gnu.org/software/src-highlite --> <div class="sect1">
<h2 id="_cleaning_up">Cleaning up</h2>
<div class="sectionbody">
-<div class="paragraph"><p>All handlers coming with Cowboy allow the use of the optional
-<code>terminate/3</code> callback.</p></div>
+<div class="paragraph"><p>With the exception of Websocket handlers, all handler types
+provide the optional <code>terminate/3</code> callback.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">_Reason</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">_Reason</span>, <span style="color: #009900">_Req</span>, <span style="color: #009900">_State</span>) <span style="color: #990000">-></span>
<span style="color: #FF6600">ok</span><span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>This callback is strictly reserved for any required cleanup.
You cannot send a response from this function. There is no
other return value.</p></div>
-<div class="paragraph"><p>If you used the process dictionary, timers, monitors or may
-be receiving messages, then you can use this function to clean
-them up, as Cowboy might reuse the process for the next
-keep-alive request.</p></div>
-<div class="paragraph"><p>Note that while this function may be called in a Websocket
-handler, it is generally not useful to do any clean up as
-the process terminates immediately after calling this callback
-when using Websocket.</p></div>
+<div class="paragraph"><p>This callback is optional because it is rarely necessary.
+Cleanup should be done in separate processes directly (by
+monitoring the handler process to detect when it exits).</p></div>
+<div class="paragraph"><p>Cowboy does not reuse processes for different requests. The
+process will terminate soon after this call returns.</p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/guide/index.html b/docs/en/cowboy/2.0/guide/index.html index 53dab6d1..79927caf 100644 --- a/docs/en/cowboy/2.0/guide/index.html +++ b/docs/en/cowboy/2.0/guide/index.html @@ -100,14 +100,11 @@ <a href="getting_started/">Getting started</a>
</p>
</li>
+</ul></div>
+<div class="ulist"><ul>
<li>
<p>
-<a href="overview/">Request overview</a>
-</p>
-</li>
-<li>
-<p>
-<a href="erlang_beginners/">Erlang for beginners</a>
+<a href="flow_diagram/">Flow diagram</a>
</p>
</li>
</ul></div>
@@ -119,24 +116,29 @@ <div class="ulist"><ul>
<li>
<p>
-<a href="routing/">routing</a>
+<a href="listeners/">Listeners</a>
</p>
</li>
<li>
<p>
-<a href="constraints/">Constraints</a>
+<a href="streams/">Streams</a>
</p>
</li>
<li>
<p>
-<a href="static_files/">Static files</a>
+<a href="routing/">Routing</a>
+</p>
+</li>
+<li>
+<p>
+<a href="constraints/">Constraints</a>
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
-<h2 id="_request_and_response">Request and response</h2>
+<h2 id="_handlers">Handlers</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
@@ -151,7 +153,19 @@ </li>
<li>
<p>
-<a href="req/">The Req object</a>
+<a href="static_files/">Static files</a>
+</p>
+</li>
+</ul></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_request_and_response">Request and response</h2>
+<div class="sectionbody">
+<div class="ulist"><ul>
+<li>
+<p>
+<a href="req/">Request details</a>
</p>
</li>
<li>
@@ -230,6 +244,8 @@ <a href="architecture/">Architecture</a>
</p>
</li>
+</ul></div>
+<div class="ulist"><ul>
<li>
<p>
<a href="broken_clients/">Dealing with broken clients</a>
@@ -245,6 +261,8 @@ <a href="sub_protocols/">Sub protocols</a>
</p>
</li>
+</ul></div>
+<div class="ulist"><ul>
<li>
<p>
<a href="hooks/">Hooks</a>
diff --git a/docs/en/cowboy/2.0/guide/introduction.asciidoc b/docs/en/cowboy/2.0/guide/introduction.asciidoc index 9cdcbc99..d262b5ce 100644 --- a/docs/en/cowboy/2.0/guide/introduction.asciidoc +++ b/docs/en/cowboy/2.0/guide/introduction.asciidoc @@ -3,9 +3,13 @@ Cowboy is a small, fast and modular HTTP server written in Erlang. -Cowboy aims to provide a complete HTTP stack, including its derivatives -Websocket and REST. Cowboy currently supports HTTP/1.0, HTTP/1.1, HTTP/2, -Websocket (all implemented drafts + standard) and Webmachine-based REST. +Cowboy aims to provide a complete xref:modern_web[modern Web stack]. +This includes HTTP/1.1, HTTP/2, Websocket, Server-Sent Events and +Webmachine-based REST. + +Cowboy comes with functions for introspection and tracing, enabling +developers to know precisely what is happening at any time. Its modular +design also easily enable developers to add instrumentation. Cowboy is a high quality project. It has a small code base, is very efficient (both in latency and memory use) and can easily be embedded @@ -13,7 +17,7 @@ in another application. Cowboy is clean Erlang code. It includes hundreds of tests and its code is fully compliant with the Dialyzer. It is also well documented and -features both a Function Reference and a User Guide. +features a Function Reference, a User Guide and numerous Tutorials. === Prerequisites @@ -24,21 +28,34 @@ will be detailed throughout the guide. === Supported platforms -Cowboy is tested and supported on Linux. +Cowboy is tested and supported on Linux, FreeBSD, Windows and OSX. Cowboy has been reported to work on other platforms, but we make no guarantee that the experience will be safe and smooth. You are advised to perform the necessary testing and security audits prior to deploying on other platforms. -Cowboy is developed for Erlang/OTP 17.0, 17.1.2 and 17.3. By the time -this branch gets released the target version will probably be 18.0 and -above. +Cowboy is developed for Erlang/OTP 19.0 and newer. + +=== License + +Cowboy uses the ISC License. + +---- +Copyright (c) 2011-2016, Loïc Hoguin <[email protected]> -Cowboy may be compiled on other Erlang versions with small source code -modifications but there is no guarantee that it will work as expected. +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. -Cowboy uses the maps data type which was introduced in Erlang 17.0. +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +---- === Versioning @@ -49,8 +66,10 @@ Cowboy uses http://semver.org/[Semantic Versioning 2.0.0]. In the HTTP protocol, the method name is case sensitive. All standard method names are uppercase. -Header names are case insensitive. Cowboy converts all the request -header names to lowercase, and expects your application to provide -lowercase header names in the response. +Header names are case insensitive. When using HTTP/1.1, Cowboy converts +all the request header names to lowercase. HTTP/2 requires clients to +send them as lowercase. Any other header name is expected to be provided +lowercased, including when querying information about the request or +when sending responses. The same applies to any other case insensitive value. diff --git a/docs/en/cowboy/2.0/guide/introduction/index.html b/docs/en/cowboy/2.0/guide/introduction/index.html index 1a43c339..f302a75f 100644 --- a/docs/en/cowboy/2.0/guide/introduction/index.html +++ b/docs/en/cowboy/2.0/guide/introduction/index.html @@ -70,15 +70,18 @@ <h1 class="lined-header"><span>Introduction</span></h1> <div class="paragraph"><p>Cowboy is a small, fast and modular HTTP server written in Erlang.</p></div>
-<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack, including its derivatives
-Websocket and REST. Cowboy currently supports HTTP/1.0, HTTP/1.1, HTTP/2,
-Websocket (all implemented drafts + standard) and Webmachine-based REST.</p></div>
+<div class="paragraph"><p>Cowboy aims to provide a complete <a href="../modern_web">modern Web stack</a>.
+This includes HTTP/1.1, HTTP/2, Websocket, Server-Sent Events and
+Webmachine-based REST.</p></div>
+<div class="paragraph"><p>Cowboy comes with functions for introspection and tracing, enabling
+developers to know precisely what is happening at any time. Its modular
+design also easily enable developers to add instrumentation.</p></div>
<div class="paragraph"><p>Cowboy is a high quality project. It has a small code base, is very
efficient (both in latency and memory use) and can easily be embedded
in another application.</p></div>
<div class="paragraph"><p>Cowboy is clean Erlang code. It includes hundreds of tests and its code
is fully compliant with the Dialyzer. It is also well documented and
-features both a Function Reference and a User Guide.</p></div>
+features a Function Reference, a User Guide and numerous Tutorials.</p></div>
<div class="sect1">
<h2 id="_prerequisites">Prerequisites</h2>
<div class="sectionbody">
@@ -90,17 +93,34 @@ will be detailed throughout the guide.</p></div> <div class="sect1">
<h2 id="_supported_platforms">Supported platforms</h2>
<div class="sectionbody">
-<div class="paragraph"><p>Cowboy is tested and supported on Linux.</p></div>
+<div class="paragraph"><p>Cowboy is tested and supported on Linux, FreeBSD, Windows and OSX.</p></div>
<div class="paragraph"><p>Cowboy has been reported to work on other platforms, but we make no
guarantee that the experience will be safe and smooth. You are advised
to perform the necessary testing and security audits prior to deploying
on other platforms.</p></div>
-<div class="paragraph"><p>Cowboy is developed for Erlang/OTP 17.0, 17.1.2 and 17.3. By the time
-this branch gets released the target version will probably be 18.0 and
-above.</p></div>
-<div class="paragraph"><p>Cowboy may be compiled on other Erlang versions with small source code
-modifications but there is no guarantee that it will work as expected.</p></div>
-<div class="paragraph"><p>Cowboy uses the maps data type which was introduced in Erlang 17.0.</p></div>
+<div class="paragraph"><p>Cowboy is developed for Erlang/OTP 19.0 and newer.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_license">License</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Cowboy uses the ISC License.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>Copyright (c) 2011-2016, Loïc Hoguin <[email protected]>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.</code></pre>
+</div></div>
</div>
</div>
<div class="sect1">
@@ -114,9 +134,11 @@ modifications but there is no guarantee that it will work as expected.</p></div> <div class="sectionbody">
<div class="paragraph"><p>In the HTTP protocol, the method name is case sensitive. All standard
method names are uppercase.</p></div>
-<div class="paragraph"><p>Header names are case insensitive. Cowboy converts all the request
-header names to lowercase, and expects your application to provide
-lowercase header names in the response.</p></div>
+<div class="paragraph"><p>Header names are case insensitive. When using HTTP/1.1, Cowboy converts
+all the request header names to lowercase. HTTP/2 requires clients to
+send them as lowercase. Any other header name is expected to be provided
+lowercased, including when querying information about the request or
+when sending responses.</p></div>
<div class="paragraph"><p>The same applies to any other case insensitive value.</p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc b/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc index 58c42233..c0195ea0 100644 --- a/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc +++ b/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc @@ -1,6 +1,8 @@ [[loop_handlers]] == Loop handlers +// @todo This description needs to be updated. + Loop handlers are a special kind of HTTP handlers used when the response can not be sent right away. The handler enters instead a receive loop waiting for the right message before it can send @@ -36,8 +38,8 @@ This snippet enables the loop handler. [source,erlang] ---- -init(Req, _Opts) -> - {cowboy_loop, Req, #state{}}. +init(Req, State) -> + {cowboy_loop, Req, State}. ---- However it is largely recommended that you set a timeout @@ -46,8 +48,8 @@ also makes the process hibernate. [source,erlang] ---- -init(Req, _Opts) -> - {cowboy_loop, Req, #state{}, 30000, hibernate}. +init(Req, State) -> + {cowboy_loop, Req, State, 30000, hibernate}. ---- === Receive loop @@ -64,8 +66,8 @@ message otherwise. [source,erlang] ---- info({reply, Body}, Req, State) -> - Req2 = cowboy_req:reply(200, [], Body, Req), - {stop, Req2, State}; + cowboy_req:reply(200, [], Body, Req), + {stop, Req, State}; info(_Msg, Req, State) -> {ok, Req, State, hibernate}. ---- @@ -99,9 +101,9 @@ and the loop is stopped by sending an `eof` message. [source,erlang] ---- -init(Req, _Opts) -> +init(Req, State) -> Req2 = cowboy_req:chunked_reply(200, [], Req), - {cowboy_loop, Req2, #state{}}. + {cowboy_loop, Req2, State}. info(eof, Req, State) -> {stop, Req, State}; diff --git a/docs/en/cowboy/2.0/guide/loop_handlers/index.html b/docs/en/cowboy/2.0/guide/loop_handlers/index.html index d3081aac..9b25dc97 100644 --- a/docs/en/cowboy/2.0/guide/loop_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/loop_handlers/index.html @@ -101,8 +101,8 @@ process enter hibernation until a message is received.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}}<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>However it is largely recommended that you set a timeout
value. The next example sets a timeout value of 30s and
also makes the process hibernate.</p></div>
@@ -111,8 +111,8 @@ also makes the process hibernate.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}, <span style="color: #993399">30000</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #993399">30000</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
</div>
</div>
<div class="sect1">
@@ -131,8 +131,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">info</span></span>({<span style="color: #FF6600">reply</span>, <span style="color: #009900">Body</span>}, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, [], <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req2</span>, <span style="color: #009900">State</span>};
+ <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, [], <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>),
+ {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">_Msg</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>Do note that the <code>reply</code> tuple here may be any message
@@ -163,9 +163,9 @@ and the loop is stopped by sending an <code>eof</code> message.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
<span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:chunked_reply</span></span>(<span style="color: #993399">200</span>, [], <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req2</span>, <span style="color: #008080">#state</span>{}}<span style="color: #990000">.</span>
+ {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req2</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span>
<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #FF6600">eof</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
{<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
diff --git a/docs/en/cowboy/2.0/guide/modern_web.asciidoc b/docs/en/cowboy/2.0/guide/modern_web.asciidoc index 732972f0..6c43adb0 100644 --- a/docs/en/cowboy/2.0/guide/modern_web.asciidoc +++ b/docs/en/cowboy/2.0/guide/modern_web.asciidoc @@ -1,164 +1,58 @@ [[modern_web]] == The modern Web -Let's take a look at various technologies from the beginnings -of the Web up to this day, and get a preview of what's -coming next. +// @todo Link to related xrefs. -Cowboy is compatible with all the technology cited in this -chapter except of course HTTP/2.0 which has no implementation -in the wild at the time of writing. +Cowboy is a server for the modern Web. This chapter explains +what it means and details all the standards involved. -=== The prehistoric Web +Cowboy supports all the standards listed in this document. -HTTP was initially created to serve HTML pages and only -had the GET method for retrieving them. This initial -version is documented and is sometimes called HTTP/0.9. -HTTP/1.0 defined the GET, HEAD and POST methods, and -was able to send data with POST requests. - -HTTP/1.0 works in a very simple way. A TCP connection -is first established to the server. Then a request is -sent. Then the server sends a response back and closes -the connection. - -Suffice to say, HTTP/1.0 is not very efficient. Opening -a TCP connection takes some time, and pages containing -many assets load much slower than they could because of -this. - -Most improvements done in recent years focused on reducing -this load time and reducing the latency of the requests. - -=== HTTP/1.1 - -HTTP/1.1 quickly followed and added a keep-alive mechanism -to allow using the same connection for many requests, as -well as streaming capabilities, allowing an endpoint to send -a body in well defined chunks. - -HTTP/1.1 defines the OPTIONS, GET, HEAD, POST, PUT, DELETE, -TRACE and CONNECT methods. The PATCH method was added in more -recent years. It also improves the caching capabilities with -the introduction of many headers. - -HTTP/1.1 still works like HTTP/1.0 does, except the connection -can be kept alive for subsequent requests. This however allows -clients to perform what is called as pipelining: sending many -requests in a row, and then processing the responses which will -be received in the same order as the requests. - -=== REST - -The design of HTTP/1.1 was influenced by the REST architectural -style. REST, or REpresentational State Transfer, is a style of -architecture for loosely connected distributed systems. - -REST defines constraints that systems must obey to in order to -be RESTful. A system which doesn't follow all the constraints -cannot be considered RESTful. - -REST is a client-server architecture with a clean separation -of concerns between the client and the server. They communicate -by referencing resources. Resources can be identified, but -also manipulated. A resource representation has a media type -and information about whether it can be cached and how. Hypermedia -determines how resources are related and how they can be used. -REST is also stateless. All requests contain the complete -information necessary to perform the action. - -HTTP/1.1 defines all the methods, headers and semantics required -to implement RESTful systems. - -REST is most often used when designing web application APIs -which are generally meant to be used by executable code directly. - -=== XmlHttpRequest - -Also know as AJAX, this technology allows Javascript code running -on a web page to perform asynchronous requests to the server. -This is what started the move from static websites to dynamic -web applications. - -XmlHttpRequest still performs HTTP requests under the hood, -and then waits for a response, but the Javascript code can -continue to run until the response arrives. It will then receive -the response through a callback previously defined. - -This is of course still requests initiated by the client, -the server still had no way of pushing data to the client -on its own, so new technology appeared to allow that. - -=== Long-polling - -Polling was a technique used to overcome the fact that the server -cannot push data directly to the client. Therefore the client had -to repeatedly create a connection, make a request, get a response, -then try again a few seconds later. This is overly expensive and -adds an additional delay before the client receives the data. - -Polling was necessary to implement message queues and other -similar mechanisms, where a user must be informed of something -when it happens, rather than when he refreshes the page next. -A typical example would be a chat application. - -Long-polling was created to reduce the server load by creating -less connections, but also to improve latency by getting the -response back to the client as soon as it becomes available -on the server. - -Long-polling works in a similar manner to polling, except the -request will not get a response immediately. Instead the server -leaves it open until it has a response to send. After getting -the response, the client creates a new request and gets back -to waiting. - -You probably guessed by now that long-polling is a hack, and -like most hacks it can suffer from unforeseen issues, in this -case it doesn't always play well with proxies. +=== HTTP/2 -=== HTML5 +HTTP/2 is the most efficient protocol for consuming Web +services. It enables clients to keep a connection open +for long periods of time; to send requests concurrently; +to reduce the size of requests through HTTP headers +compression; and more. The protocol is binary, greatly +reducing the resources needed to parse it. -HTML5 is, of course, the HTML version after HTML4. But HTML5 -emerged to solve a specific problem: dynamic web applications. +HTTP/2 also enables the server to push messages to the +client. This can be used for various purposes, including +the sending of related resources before the client requests +them, in an effort to reduce latency. This can also be used +to enable bidirectional communication. -HTML was initially created to write web pages which compose -a website. But soon people and companies wanted to use HTML -to write more and more complex websites, eventually known as -web applications. They are for example your news reader, your -email client in the browser, or your video streaming website. +Cowboy provides transparent support for HTTP/2. Clients +that know it can use it; others fall back to HTTP/1.1 +automatically. -Because HTML wasn't enough, they started using proprietary -solutions, often implemented using plug-ins. This wasn't -perfect of course, but worked well enough for most people. +HTTP/2 is compatible with the HTTP/1.1 semantics. -However, the needs for a standard solution eventually became -apparent. The browser needed to be able to play media natively. -It needed to be able to draw anything. It needed an efficient -way of streaming events to the server, but also receiving -events from the server. +HTTP/2 is defined by RFC 7540 and RFC 7541. -The solution went on to become HTML5. At the time of writing -it is being standardized. +=== HTTP/1.1 -=== EventSource +HTTP/1.1 is the previous version of the HTTP protocol. +The protocol itself is text-based and suffers from numerous +issues and limitations. In particular it is not possible +to execute requests concurrently (though pipelining is +sometimes possible), and it's also sometimes difficult +to detect that a client disconnected. -EventSource, sometimes also called Server-Sent Events, is a -technology allowing servers to push data to HTML5 applications. +HTTP/1.1 does provide very good semantics for interacting +with Web services. It defines the standard methods, headers +and status codes used by HTTP/1.1 and HTTP/2 clients and +servers. -EventSource is one-way communication channel from the server -to the client. The client has no means to talk to the server -other than by using HTTP requests. +HTTP/1.1 also defines compatibility with an older version +of the protocol, HTTP/1.0, which was never really standardized +across implementations. -It consists of a Javascript object allowing setting up an -EventSource connection to the server, and a very small protocol -for sending events to the client on top of the HTTP/1.1 -connection. - -EventSource is a lightweight solution that only works for -UTF-8 encoded text data. Binary data and text data encoded -differently are not allowed by the protocol. A heavier but -more generic approach can be found in Websocket. +The core of HTTP/1.1 is defined by RFC 7230, RFC 7231, +RFC 7232, RFC 7233, RFC 7234 and RFC 7235. Numerous RFCs +and other specifications exist defining additional HTTP +methods, status codes, headers or semantics. === Websocket @@ -180,21 +74,48 @@ A Websocket connection can be used to transfer any kind of data, small or big, text or binary. Because of this Websocket is sometimes used for communication between systems. -=== HTTP/2 +Websocket messages have no semantics on their own. Websocket +is closer to TCP in that aspect, and requires you to design +and implement your own protocol on top of it; or adapt an +existing protocol to Websocket. + +The Websocket protocol is defined by RFC 6455. + +=== Long-lived requests + +Cowboy provides an interface that can be used to support +long-polling or to stream large amounts of data reliably, +including using Server-Sent Events. + +Long-polling is a mechanism in which the client performs +a request which may not be immediately answered by the +server. It allows clients to request resources that may +not currently exist, but are expected to be created soon, +and which will be returned as soon as they are. + +Long-polling is essentially a hack, but it is widely used +to overcome limitations on older clients and servers. + +Server-Sent Events is a small protocol defined as a media +type, `text/event-stream`, along with a new HTTP header, +`Last-Event-ID`. It is defined in the EventSource W3C +specification. + +Cowboy provides an interface known as loop handlers that +facilitates the implementation of long-polling or stream +mechanisms. It works regardless of the underlying protocol. + +=== REST + +REST, or REpresentational State Transfer, is a style of +architecture for loosely connected distributed systems. +It can easily be implemented on top of HTTP. + +REST is essentially a set of constraints to be followed. +Many of these constraints are purely architectural and +solved by simply using HTTP. Some constraints must be +explicitly followed by the developer. -HTTP/2 is an attempt to reduce page loading time by opening a -single connection per server, keeping it open for subsequent -requests, and also by compressing the HTTP headers to reduce -the size of requests. - -HTTP/2 is compatible with HTTP/1.1 semantics, and is actually -just a different way of performing HTTP requests and responses, -by using binary frames instead of a text-based protocol. -HTTP/2 also allows the server to send extra responses following -a request. This is meant to allow sending the resources -associated with the request before the client requests them, -saving latency when loading websites. - -Browsers make use of TLS Application-Layer Protocol Negotiation -extension to upgrade to an HTTP/2 connection seamlessly if the -server supports it. +Cowboy provides an interface known as REST handlers that +simplifies the implementation of a REST API on top of +the HTTP protocol. diff --git a/docs/en/cowboy/2.0/guide/modern_web/index.html b/docs/en/cowboy/2.0/guide/modern_web/index.html index 69761906..26f1b213 100644 --- a/docs/en/cowboy/2.0/guide/modern_web/index.html +++ b/docs/en/cowboy/2.0/guide/modern_web/index.html @@ -69,153 +69,50 @@ <h1 class="lined-header"><span>The modern Web</span></h1> -<div class="paragraph"><p>Let’s take a look at various technologies from the beginnings
-of the Web up to this day, and get a preview of what’s
-coming next.</p></div>
-<div class="paragraph"><p>Cowboy is compatible with all the technology cited in this
-chapter except of course HTTP/2.0 which has no implementation
-in the wild at the time of writing.</p></div>
+<div class="paragraph"><p>Cowboy is a server for the modern Web. This chapter explains
+what it means and details all the standards involved.</p></div>
+<div class="paragraph"><p>Cowboy supports all the standards listed in this document.</p></div>
<div class="sect1">
-<h2 id="_the_prehistoric_web">The prehistoric Web</h2>
+<h2 id="_http_2">HTTP/2</h2>
<div class="sectionbody">
-<div class="paragraph"><p>HTTP was initially created to serve HTML pages and only
-had the GET method for retrieving them. This initial
-version is documented and is sometimes called HTTP/0.9.
-HTTP/1.0 defined the GET, HEAD and POST methods, and
-was able to send data with POST requests.</p></div>
-<div class="paragraph"><p>HTTP/1.0 works in a very simple way. A TCP connection
-is first established to the server. Then a request is
-sent. Then the server sends a response back and closes
-the connection.</p></div>
-<div class="paragraph"><p>Suffice to say, HTTP/1.0 is not very efficient. Opening
-a TCP connection takes some time, and pages containing
-many assets load much slower than they could because of
-this.</p></div>
-<div class="paragraph"><p>Most improvements done in recent years focused on reducing
-this load time and reducing the latency of the requests.</p></div>
+<div class="paragraph"><p>HTTP/2 is the most efficient protocol for consuming Web
+services. It enables clients to keep a connection open
+for long periods of time; to send requests concurrently;
+to reduce the size of requests through HTTP headers
+compression; and more. The protocol is binary, greatly
+reducing the resources needed to parse it.</p></div>
+<div class="paragraph"><p>HTTP/2 also enables the server to push messages to the
+client. This can be used for various purposes, including
+the sending of related resources before the client requests
+them, in an effort to reduce latency. This can also be used
+to enable bidirectional communication.</p></div>
+<div class="paragraph"><p>Cowboy provides transparent support for HTTP/2. Clients
+that know it can use it; others fall back to HTTP/1.1
+automatically.</p></div>
+<div class="paragraph"><p>HTTP/2 is compatible with the HTTP/1.1 semantics.</p></div>
+<div class="paragraph"><p>HTTP/2 is defined by RFC 7540 and RFC 7541.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_http_1_1">HTTP/1.1</h2>
<div class="sectionbody">
-<div class="paragraph"><p>HTTP/1.1 quickly followed and added a keep-alive mechanism
-to allow using the same connection for many requests, as
-well as streaming capabilities, allowing an endpoint to send
-a body in well defined chunks.</p></div>
-<div class="paragraph"><p>HTTP/1.1 defines the OPTIONS, GET, HEAD, POST, PUT, DELETE,
-TRACE and CONNECT methods. The PATCH method was added in more
-recent years. It also improves the caching capabilities with
-the introduction of many headers.</p></div>
-<div class="paragraph"><p>HTTP/1.1 still works like HTTP/1.0 does, except the connection
-can be kept alive for subsequent requests. This however allows
-clients to perform what is called as pipelining: sending many
-requests in a row, and then processing the responses which will
-be received in the same order as the requests.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rest">REST</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The design of HTTP/1.1 was influenced by the REST architectural
-style. REST, or REpresentational State Transfer, is a style of
-architecture for loosely connected distributed systems.</p></div>
-<div class="paragraph"><p>REST defines constraints that systems must obey to in order to
-be RESTful. A system which doesn’t follow all the constraints
-cannot be considered RESTful.</p></div>
-<div class="paragraph"><p>REST is a client-server architecture with a clean separation
-of concerns between the client and the server. They communicate
-by referencing resources. Resources can be identified, but
-also manipulated. A resource representation has a media type
-and information about whether it can be cached and how. Hypermedia
-determines how resources are related and how they can be used.
-REST is also stateless. All requests contain the complete
-information necessary to perform the action.</p></div>
-<div class="paragraph"><p>HTTP/1.1 defines all the methods, headers and semantics required
-to implement RESTful systems.</p></div>
-<div class="paragraph"><p>REST is most often used when designing web application APIs
-which are generally meant to be used by executable code directly.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_xmlhttprequest">XmlHttpRequest</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Also know as AJAX, this technology allows Javascript code running
-on a web page to perform asynchronous requests to the server.
-This is what started the move from static websites to dynamic
-web applications.</p></div>
-<div class="paragraph"><p>XmlHttpRequest still performs HTTP requests under the hood,
-and then waits for a response, but the Javascript code can
-continue to run until the response arrives. It will then receive
-the response through a callback previously defined.</p></div>
-<div class="paragraph"><p>This is of course still requests initiated by the client,
-the server still had no way of pushing data to the client
-on its own, so new technology appeared to allow that.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_long_polling">Long-polling</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Polling was a technique used to overcome the fact that the server
-cannot push data directly to the client. Therefore the client had
-to repeatedly create a connection, make a request, get a response,
-then try again a few seconds later. This is overly expensive and
-adds an additional delay before the client receives the data.</p></div>
-<div class="paragraph"><p>Polling was necessary to implement message queues and other
-similar mechanisms, where a user must be informed of something
-when it happens, rather than when he refreshes the page next.
-A typical example would be a chat application.</p></div>
-<div class="paragraph"><p>Long-polling was created to reduce the server load by creating
-less connections, but also to improve latency by getting the
-response back to the client as soon as it becomes available
-on the server.</p></div>
-<div class="paragraph"><p>Long-polling works in a similar manner to polling, except the
-request will not get a response immediately. Instead the server
-leaves it open until it has a response to send. After getting
-the response, the client creates a new request and gets back
-to waiting.</p></div>
-<div class="paragraph"><p>You probably guessed by now that long-polling is a hack, and
-like most hacks it can suffer from unforeseen issues, in this
-case it doesn’t always play well with proxies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_html5">HTML5</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>HTML5 is, of course, the HTML version after HTML4. But HTML5
-emerged to solve a specific problem: dynamic web applications.</p></div>
-<div class="paragraph"><p>HTML was initially created to write web pages which compose
-a website. But soon people and companies wanted to use HTML
-to write more and more complex websites, eventually known as
-web applications. They are for example your news reader, your
-email client in the browser, or your video streaming website.</p></div>
-<div class="paragraph"><p>Because HTML wasn’t enough, they started using proprietary
-solutions, often implemented using plug-ins. This wasn’t
-perfect of course, but worked well enough for most people.</p></div>
-<div class="paragraph"><p>However, the needs for a standard solution eventually became
-apparent. The browser needed to be able to play media natively.
-It needed to be able to draw anything. It needed an efficient
-way of streaming events to the server, but also receiving
-events from the server.</p></div>
-<div class="paragraph"><p>The solution went on to become HTML5. At the time of writing
-it is being standardized.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_eventsource">EventSource</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>EventSource, sometimes also called Server-Sent Events, is a
-technology allowing servers to push data to HTML5 applications.</p></div>
-<div class="paragraph"><p>EventSource is one-way communication channel from the server
-to the client. The client has no means to talk to the server
-other than by using HTTP requests.</p></div>
-<div class="paragraph"><p>It consists of a Javascript object allowing setting up an
-EventSource connection to the server, and a very small protocol
-for sending events to the client on top of the HTTP/1.1
-connection.</p></div>
-<div class="paragraph"><p>EventSource is a lightweight solution that only works for
-UTF-8 encoded text data. Binary data and text data encoded
-differently are not allowed by the protocol. A heavier but
-more generic approach can be found in Websocket.</p></div>
+<div class="paragraph"><p>HTTP/1.1 is the previous version of the HTTP protocol.
+The protocol itself is text-based and suffers from numerous
+issues and limitations. In particular it is not possible
+to execute requests concurrently (though pipelining is
+sometimes possible), and it’s also sometimes difficult
+to detect that a client disconnected.</p></div>
+<div class="paragraph"><p>HTTP/1.1 does provide very good semantics for interacting
+with Web services. It defines the standard methods, headers
+and status codes used by HTTP/1.1 and HTTP/2 clients and
+servers.</p></div>
+<div class="paragraph"><p>HTTP/1.1 also defines compatibility with an older version
+of the protocol, HTTP/1.0, which was never really standardized
+across implementations.</p></div>
+<div class="paragraph"><p>The core of HTTP/1.1 is defined by RFC 7230, RFC 7231,
+RFC 7232, RFC 7233, RFC 7234 and RFC 7235. Numerous RFCs
+and other specifications exist defining additional HTTP
+methods, status codes, headers or semantics.</p></div>
</div>
</div>
<div class="sect1">
@@ -235,25 +132,48 @@ alive.</p></div> <div class="paragraph"><p>A Websocket connection can be used to transfer any kind of data,
small or big, text or binary. Because of this Websocket is
sometimes used for communication between systems.</p></div>
+<div class="paragraph"><p>Websocket messages have no semantics on their own. Websocket
+is closer to TCP in that aspect, and requires you to design
+and implement your own protocol on top of it; or adapt an
+existing protocol to Websocket.</p></div>
+<div class="paragraph"><p>The Websocket protocol is defined by RFC 6455.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_http_2">HTTP/2</h2>
+<h2 id="_long_lived_requests">Long-lived requests</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Cowboy provides an interface that can be used to support
+long-polling or to stream large amounts of data reliably,
+including using Server-Sent Events.</p></div>
+<div class="paragraph"><p>Long-polling is a mechanism in which the client performs
+a request which may not be immediately answered by the
+server. It allows clients to request resources that may
+not currently exist, but are expected to be created soon,
+and which will be returned as soon as they are.</p></div>
+<div class="paragraph"><p>Long-polling is essentially a hack, but it is widely used
+to overcome limitations on older clients and servers.</p></div>
+<div class="paragraph"><p>Server-Sent Events is a small protocol defined as a media
+type, <code>text/event-stream</code>, along with a new HTTP header,
+<code>Last-Event-ID</code>. It is defined in the EventSource W3C
+specification.</p></div>
+<div class="paragraph"><p>Cowboy provides an interface known as loop handlers that
+facilitates the implementation of long-polling or stream
+mechanisms. It works regardless of the underlying protocol.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_rest">REST</h2>
<div class="sectionbody">
-<div class="paragraph"><p>HTTP/2 is an attempt to reduce page loading time by opening a
-single connection per server, keeping it open for subsequent
-requests, and also by compressing the HTTP headers to reduce
-the size of requests.</p></div>
-<div class="paragraph"><p>HTTP/2 is compatible with HTTP/1.1 semantics, and is actually
-just a different way of performing HTTP requests and responses,
-by using binary frames instead of a text-based protocol.
-HTTP/2 also allows the server to send extra responses following
-a request. This is meant to allow sending the resources
-associated with the request before the client requests them,
-saving latency when loading websites.</p></div>
-<div class="paragraph"><p>Browsers make use of TLS Application-Layer Protocol Negotiation
-extension to upgrade to an HTTP/2 connection seamlessly if the
-server supports it.</p></div>
+<div class="paragraph"><p>REST, or REpresentational State Transfer, is a style of
+architecture for loosely connected distributed systems.
+It can easily be implemented on top of HTTP.</p></div>
+<div class="paragraph"><p>REST is essentially a set of constraints to be followed.
+Many of these constraints are purely architectural and
+solved by simply using HTTP. Some constraints must be
+explicitly followed by the developer.</p></div>
+<div class="paragraph"><p>Cowboy provides an interface known as REST handlers that
+simplifies the implementation of a REST API on top of
+the HTTP protocol.</p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/guide/req.asciidoc b/docs/en/cowboy/2.0/guide/req.asciidoc index 09d442af..2dd0a86b 100644 --- a/docs/en/cowboy/2.0/guide/req.asciidoc +++ b/docs/en/cowboy/2.0/guide/req.asciidoc @@ -1,155 +1,294 @@ ++++ +title = "The Req object" ++++ + [[req]] == The Req object -The Req object is this variable that you will use to obtain -information about a request, read the body of the request -and send a response. +The Req object is a variable used for obtaining information +about a request, read its body or send a response. + +It is not really an object in the object-oriented sense. +It is a simple map that can be directly accessed or +used when calling functions from the `cowboy_req` module. + +The Req object is the subject of a few different chapters. +In this chapter we will learn about the Req object and +look at how to retrieve information about the request. + +=== Direct access + +The Req map contains a number of fields which are documented +and can be accessed directly. They are the fields that have +a direct mapping to HTTP: the request `method`; the HTTP +`version` used; the effective URI components `scheme`, +`host`, `port`, `path` and `qs`; the request `headers`; +and the connection `peer` address and port. + +Note that the `version` field can be used to determine +whether a connection is using HTTP/2. + +To access a field, you can simply match in the function +head. The following example sends a simple "Hello world!" +response when the `method` is GET, and a 405 error +otherwise. + +[source,erlang] +---- +init(Req0=#{method := <<"GET">>}, State) -> + Req = cowboy_req:reply(200, #{ + <<"content-type">> => <<"text/plain">> + }, <<"Hello world!">>, Req0), + {ok, Req, State}; +init(Req0, State) -> + Req = cowboy_req:reply(405, #{ + <<"allow">> => <<"GET">> + }, Req0), + {ok, Req, State}. +---- + +Any other field is internal and should not be accessed. +They may change in future releases, including maintenance +releases, without notice. + +Modifying the Req object, while allowed, is not recommended +unless strictly necessary. If adding new fields, make sure +to namespace the field names so that no conflict can occur +with future Cowboy updates or third party projects. + +// @todo There are currently no tests for direct access. -=== A special variable +=== Introduction to the cowboy_req interface -While we call it an "object", it is not an object in the -OOP sense of the term. In fact it is completely opaque -to you and the only way you can perform operations using -it is by calling the functions from the `cowboy_req` -module. +// @todo Link to cowboy_req manual -Almost all the calls to the `cowboy_req` module will -return an updated request object. Just like you would -keep the updated `State` variable in a gen_server, -you MUST keep the updated `Req` variable in a Cowboy -handler. Cowboy will use this object to know whether -a response has been sent when the handler has finished -executing. +Functions in the `cowboy_req` module provide access to +the request information but also various operations that +are common when dealing with HTTP requests. -The Req object allows accessing both immutable and -mutable state. This means that calling some of the -functions twice will not produce the same result. -For example, when streaming the request body, the -function will return the body by chunks, one at a -time, until there is none left. +All the functions that begin with a verb indicate an action. +Other functions simply return the corresponding value +(sometimes that value does need to be built, but the +cost of the operation is equivalent to retrieving a value). -=== Overview of the cowboy_req interface +Some of the `cowboy_req` functions return an updated Req +object. They are the read, reply, set and delete functions. +While ignoring the returned Req will not cause incorrect +behavior for some of them, it is highly recommended to +always keep and use the last returned Req object. The +manual for `cowboy_req` details these functions and what +modifications are done to the Req object. -With the exception of functions manipulating the request -body, all functions return a single value. Depending on -the function this can be the requested value (method, -host, path, ...), a boolean (has_body, has_resp_header...) -a new Req object (set_resp_body, set_resp_header...), or -simply the atom `ok` (chunk, continue, ...). +Some of the calls to `cowboy_req` have side effects. This +is the case of the read and reply functions. Cowboy reads +the request body or replies immediately when the function +is called. -The request body reading functions may return `{Result, Req}` -or `{Result, Value, Req}`. The functions in this category -are `body/{1,2}`, `body_qs/{1,2}`, `part/{1,2}`, `part_body/{1,2}`. +All functions will crash if something goes wrong. There +is usually no need to catch these errors, Cowboy will +send the appropriate 4xx or 5xx response depending on +where the crash occurred. -This chapter covers the access functions mainly. Cookies, -request body and response functions are covered in their -own chapters. +=== Request method -=== Request +The request method can be retrieved directly: -When a client performs a request, it first sends a few required -values. They are sent differently depending on the protocol -being used, but the intent is the same. They indicate to the -server the type of action it wants to do and how to locate -the resource to perform it on. +[source, erlang] +#{method := Method} = Req. -The method identifies the action. Standard methods include -GET, HEAD, OPTIONS, PATCH, POST, PUT, DELETE. Method names -are case sensitive. +Or using a function: [source,erlang] Method = cowboy_req:method(Req). -The host, port and path parts of the URL identify the resource -being accessed. The host and port information may not be -available if the client uses HTTP/1.0. +The method is a case sensitive binary string. Standard +methods include GET, HEAD, OPTIONS, PATCH, POST, PUT +or DELETE. + +=== HTTP version + +The HTTP version is informational. It does not indicate that +the client implements the protocol well or fully. + +There is typically no need to change behavior based on the +HTTP version: Cowboy already does it for you. + +It can be useful in some cases, though. For example, one may +want to redirect HTTP/1.1 clients to use Websocket, while HTTP/2 +clients keep using HTTP/2. + +The HTTP version can be retrieved directly: + +[source,erlang] +#{version := Version} = Req. + +Or using a function: [source,erlang] +Version = cowboy_req:version(Req). + +Cowboy defines the `'HTTP/1.0'`, `'HTTP/1.1'` and `'HTTP/2'` +versions. Custom protocols can define their own values as +atoms. + +=== Effective request URI + +The scheme, host, port, path and query string components +of the effective request URI can all be retrieved directly: + +[source,erlang] +---- +#{ + scheme := Scheme, + host := Host, + port := Port, + path := Path, + qs := Qs +} = Req. +---- + +Or using the related functions: + +[source,erlang] +Scheme = cowboy_req:scheme(Req), Host = cowboy_req:host(Req), Port = cowboy_req:port(Req), Path = cowboy_req:path(Req). +Qs = cowboy_req:qs(Req). + +The scheme and host are lowercased case insensitive binary +strings. The port is an integer representing the port number. +The path and query string are case sensitive binary strings. + +Cowboy defines only the <<"http">> and <<"https">> schemes. +They are chosen so that the scheme will only be <<"https">> +for requests on secure HTTP/1.1 or HTTP/2 connections. +// @todo Is that tested well? -The version used by the client can of course also be obtained. +The effective request URI itself can be reconstructed with +the `cowboy_req:uri/1,2` function. By default, an absolute +URI is returned: [source,erlang] -Version = cowboy_req:version(Req). +%% scheme://host[:port]/path[?qs] +URI = cowboy_req:uri(Req). + +Options are available to either disable or replace some +or all of the components. Various URIs or URI formats can +be generated this way, including the origin form: + +[source,erlang] +%% /path[?qs] +URI = cowboy_req:uri(Req, #{host => undefined}). + +The protocol relative form: + +[source,erlang] +%% //host[:port]/path[?qs] +URI = cowboy_req:uri(Req, #{scheme => undefined}). -Do note however that clients claiming to implement one version -of the protocol does not mean they implement it fully, or even -properly. +The absolute URI without a query string: + +[source,erlang] +URI = cowboy_req:uri(Req, #{qs => undefined}). + +A different host: + +[source,erlang] +URI = cowboy_req:uri(Req, #{host => <<"example.org">>}). + +And any other combination. === Bindings -After routing the request, bindings are available. Bindings -are these parts of the host or path that you chose to extract -when defining the routes of your application. +// @todo Bindings should probably be a map themselves. -You can fetch a single binding. The value will be `undefined` -if the binding doesn't exist. +Bindings are the host and path components that you chose +to extract when defining the routes of your application. +They are only available after the routing. + +Cowboy provides functions to retrieve one or all bindings. + +To retrieve a single value: [source,erlang] -Binding = cowboy_req:binding(my_binding, Req). +Value = cowboy_req:binding(userid, Req). -If you need a different value when the binding doesn't exist, -you can change the default. +When attempting to retrieve a value that was not bound, +`undefined` will be returned. A different default value +can be provided: [source,erlang] -Binding = cowboy_req:binding(my_binding, Req, 42). +Value = cowboy_req:binding(userid, Req, 42). -You can also obtain all bindings in one call. They will be -returned as a list of key/value tuples. +To retrieve everything that was bound: [source,erlang] -AllBindings = cowboy_req:bindings(Req). +Bindings = cowboy_req:bindings(Req). + +They are returned as a list of key/value pairs, with +keys being atoms. + +// ... + +The Cowboy router also allows you to capture many host +or path segments at once using the `...` qualifier. -If you used `...` at the beginning of the route's pattern -for the host, you can retrieve the matched part of the host. -The value will be `undefined` otherwise. +To retrieve the segments captured from the host name: [source,erlang] HostInfo = cowboy_req:host_info(Req). -Similarly, if you used `...` at the end of the route's -pattern for the path, you can retrieve the matched part, -or get `undefined` otherwise. +And the path segments: [source,erlang] PathInfo = cowboy_req:path_info(Req). -=== Query string +Cowboy will return `undefined` if `...` was not used +in the route. -The raw query string can be obtained directly. +=== Query parameters -[source,erlang] -Qs = cowboy_req:qs(Req). - -You can parse the query string and then use standard library -functions to access individual values. +Cowboy provides two functions to access query parameters. +You can use the first to get the entire list of parameters. [source,erlang] QsVals = cowboy_req:parse_qs(Req), {_, Lang} = lists:keyfind(<<"lang">>, 1, QsVals). -You can match the query string into a map. +Cowboy will only parse the query string, and not do any +transformation. This function may therefore return duplicates, +or parameter names without an associated value. The order of +the list returned is undefined. + +When a query string is `key=1&key=2`, the list returned will +contain two parameters of name `key`. + +The same is true when trying to use the PHP-style suffix `[]`. +When a query string is `key[]=1&key[]=2`, the list returned will +contain two parameters of name `key[]`. + +When a query string is simply `key`, Cowboy will return the +list `[{<<"key">>, true}]`, using `true` to indicate that the +parameter `key` was defined, but with no value. + +The second function Cowboy provides allows you to match out +only the parameters you are interested in, and at the same +time do any post processing you require using ^constraints^. +This function returns a map. [source,erlang] #{id := ID, lang := Lang} = cowboy_req:match_qs([id, lang], Req). -You can use constraints to validate the values while matching -them. The following snippet will crash if the `id` value is -not an integer number or if the `lang` value is empty. Additionally -the `id` value will be converted to an integer term, saving -you a conversion step. +Constraints can be applied automatically. The following +snippet will crash when the `id` parameter is not an integer, +or when the `lang` parameter is empty. At the same time, the +value for `id` will be converted to an integer term: [source,erlang] QsMap = cowboy_req:match_qs([{id, int}, {lang, nonempty}], Req). -Note that in the case of duplicate query string keys, the map -value will become a list of the different values. - -Read more about ^constraints^. - -A default value can be provided. The default will be used +A default value may also be provided. The default will be used if the `lang` key is not found. It will not be used if the key is found but has an empty value. @@ -159,51 +298,56 @@ the key is found but has an empty value. If no default is provided and the value is missing, the query string is deemed invalid and the process will crash. -=== Request URL - -You can reconstruct the full URL of the resource. - -[source,erlang] -URL = cowboy_req:url(Req). - -You can also obtain only the base of the URL, excluding the -path and query string. - -[source,erlang] -BaseURL = cowboy_req:host_url(Req). +When the query string is `key=1&key=2`, the value for `key` +will be the list `[1, 2]`. Parameter names do not need to +include the PHP-style suffix. Constraints may be used to +ensure that only one value was passed through. === Headers -Cowboy allows you to obtain the header values as string, +Header values can be retrieved either as a binary string or parsed into a more meaningful representation. -This will get the string value of a header. +The get the raw value: [source,erlang] HeaderVal = cowboy_req:header(<<"content-type">>, Req). -You can of course set a default in case the header is missing. +Cowboy expects all header names to be provided as lowercase +binary strings. This is true for both requests and responses, +regardless of the underlying protocol. + +When the header is missing from the request, `undefined` +will be returned. A different default can be provided: [source,erlang] HeaderVal = cowboy_req:header(<<"content-type">>, Req, <<"text/plain">>). -And also obtain all headers. +All headers can be retrieved at once, either directly: + +[source,erlang] +#{headers := AllHeaders} = Req. + +Or using a function: [source,erlang] AllHeaders = cowboy_req:headers(Req). -To parse the previous header, simply call `parse_header/{2,3}` -where you would call `header/{2,3}` otherwise. +Cowboy provides equivalent functions to parse individual +headers. There is no function to parse all headers at once. + +To parse a specific header: [source,erlang] ParsedVal = cowboy_req:parse_header(<<"content-type">>, Req). -Cowboy will crash if it doesn't know how to parse the given -header, or if the value is invalid. +An exception will be thrown if it doesn't know how to parse the +given header, or if the value is invalid. The list of known headers +and default values can be found in the manual. -You can of course define a default value. Note that the default -value you specify here is the parsed value you'd like to get -by default. +When the header is missing, `undefined` is returned. You can +change the default value. Note that it should be the parsed value +directly: [source,erlang] ---- @@ -211,37 +355,21 @@ ParsedVal = cowboy_req:parse_header(<<"content-type">>, Req, {<<"text">>, <<"plain">>, []}). ---- -The list of known headers and default values is defined in the -manual. - -=== Meta - -Cowboy will sometimes associate some meta information with -the request. Built-in meta values are listed in the manual -for their respective modules. - -This will get a meta value. The returned value will be `undefined` -if it isn't defined. - -[source,erlang] -MetaVal = cowboy_req:meta(websocket_version, Req). - -You can change the default value if needed. +=== Peer -[source,erlang] -MetaVal = cowboy_req:meta(websocket_version, Req, 13). +The peer address and port number for the connection can be +retrieved either directly or using a function. -You can also define your own meta values. The name must be -an `atom()`. +To retrieve the peer directly: [source,erlang] -Req2 = cowboy_req:set_meta(the_answer, 42, Req). +#{peer := {IP, Port}} = Req. -=== Peer - -You can obtain the peer address and port number. This is -not necessarily the actual IP and port of the client, but -rather the one of the machine that connected to the server. +And using a function: [source,erlang] {IP, Port} = cowboy_req:peer(Req). + +Note that the peer corresponds to the remote end of the +connection to the server, which may or may not be the +client itself. It may also be a proxy or a gateway. diff --git a/docs/en/cowboy/2.0/guide/req/index.html b/docs/en/cowboy/2.0/guide/req/index.html index c3442c64..77987861 100644 --- a/docs/en/cowboy/2.0/guide/req/index.html +++ b/docs/en/cowboy/2.0/guide/req/index.html @@ -69,251 +69,380 @@ <h1 class="lined-header"><span>The Req object</span></h1> -<div class="paragraph"><p>The Req object is this variable that you will use to obtain
-information about a request, read the body of the request
-and send a response.</p></div>
<div class="sect1">
-<h2 id="_a_special_variable">A special variable</h2>
+<h2 id="req">The Req object</h2>
<div class="sectionbody">
-<div class="paragraph"><p>While we call it an "object", it is not an object in the
-OOP sense of the term. In fact it is completely opaque
-to you and the only way you can perform operations using
-it is by calling the functions from the <code>cowboy_req</code>
-module.</p></div>
-<div class="paragraph"><p>Almost all the calls to the <code>cowboy_req</code> module will
-return an updated request object. Just like you would
-keep the updated <code>State</code> variable in a gen_server,
-you MUST keep the updated <code>Req</code> variable in a Cowboy
-handler. Cowboy will use this object to know whether
-a response has been sent when the handler has finished
-executing.</p></div>
-<div class="paragraph"><p>The Req object allows accessing both immutable and
-mutable state. This means that calling some of the
-functions twice will not produce the same result.
-For example, when streaming the request body, the
-function will return the body by chunks, one at a
-time, until there is none left.</p></div>
+<div class="paragraph"><p>The Req object is a variable used for obtaining information
+about a request, read its body or send a response.</p></div>
+<div class="paragraph"><p>It is not really an object in the object-oriented sense.
+It is a simple map that can be directly accessed or
+used when calling functions from the <code>cowboy_req</code> module.</p></div>
+<div class="paragraph"><p>The Req object is the subject of a few different chapters.
+In this chapter we will learn about the Req object and
+look at how to retrieve information about the request.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_overview_of_the_cowboy_req_interface">Overview of the cowboy_req interface</h2>
+<h2 id="_direct_access">Direct access</h2>
<div class="sectionbody">
-<div class="paragraph"><p>With the exception of functions manipulating the request
-body, all functions return a single value. Depending on
-the function this can be the requested value (method,
-host, path, …), a boolean (has_body, has_resp_header…)
-a new Req object (set_resp_body, set_resp_header…), or
-simply the atom <code>ok</code> (chunk, continue, …).</p></div>
-<div class="paragraph"><p>The request body reading functions may return <code>{Result, Req}</code>
-or <code>{Result, Value, Req}</code>. The functions in this category
-are <code>body/{1,2}</code>, <code>body_qs/{1,2}</code>, <code>part/{1,2}</code>, <code>part_body/{1,2}</code>.</p></div>
-<div class="paragraph"><p>This chapter covers the access functions mainly. Cookies,
-request body and response functions are covered in their
-own chapters.</p></div>
+<div class="paragraph"><p>The Req map contains a number of fields which are documented
+and can be accessed directly. They are the fields that have
+a direct mapping to HTTP: the request <code>method</code>; the HTTP
+<code>version</code> used; the effective URI components <code>scheme</code>,
+<code>host</code>, <code>port</code>, <code>path</code> and <code>qs</code>; the request <code>headers</code>;
+and the connection <code>peer</code> address and port.</p></div>
+<div class="paragraph"><p>Note that the <code>version</code> field can be used to determine
+whether a connection is using HTTP/2.</p></div>
+<div class="paragraph"><p>To access a field, you can simply match in the function
+head. The following example sends a simple "Hello world!"
+response when the <code>method</code> is GET, and a 405 error
+otherwise.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req0</span><span style="color: #990000">=</span>#{<span style="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{
+ <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>
+ }, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello world!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
+<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">405</span>, #{
+ <span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>
+ }, <span style="color: #009900">Req0</span>),
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Any other field is internal and should not be accessed.
+They may change in future releases, including maintenance
+releases, without notice.</p></div>
+<div class="paragraph"><p>Modifying the Req object, while allowed, is not recommended
+unless strictly necessary. If adding new fields, make sure
+to namespace the field names so that no conflict can occur
+with future Cowboy updates or third party projects.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_request">Request</h2>
+<h2 id="_introduction_to_the_cowboy_req_interface">Introduction to the cowboy_req interface</h2>
<div class="sectionbody">
-<div class="paragraph"><p>When a client performs a request, it first sends a few required
-values. They are sent differently depending on the protocol
-being used, but the intent is the same. They indicate to the
-server the type of action it wants to do and how to locate
-the resource to perform it on.</p></div>
-<div class="paragraph"><p>The method identifies the action. Standard methods include
-GET, HEAD, OPTIONS, PATCH, POST, PUT, DELETE. Method names
-are case sensitive.</p></div>
+<div class="paragraph"><p>Functions in the <code>cowboy_req</code> module provide access to
+the request information but also various operations that
+are common when dealing with HTTP requests.</p></div>
+<div class="paragraph"><p>All the functions that begin with a verb indicate an action.
+Other functions simply return the corresponding value
+(sometimes that value does need to be built, but the
+cost of the operation is equivalent to retrieving a value).</p></div>
+<div class="paragraph"><p>Some of the <code>cowboy_req</code> functions return an updated Req
+object. They are the read, reply, set and delete functions.
+While ignoring the returned Req will not cause incorrect
+behavior for some of them, it is highly recommended to
+always keep and use the last returned Req object. The
+manual for <code>cowboy_req</code> details these functions and what
+modifications are done to the Req object.</p></div>
+<div class="paragraph"><p>Some of the calls to <code>cowboy_req</code> have side effects. This
+is the case of the read and reply functions. Cowboy reads
+the request body or replies immediately when the function
+is called.</p></div>
+<div class="paragraph"><p>All functions will crash if something goes wrong. There
+is usually no need to catch these errors, Cowboy will
+send the appropriate 4xx or 5xx response depending on
+where the crash occurred.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_request_method">Request method</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The request method can be retrieved directly:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>#{<span style="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="color: #009900">Method</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Or using a function:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">Method</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:method</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The host, port and path parts of the URL identify the resource
-being accessed. The host and port information may not be
-available if the client uses HTTP/1.0.</p></div>
+<div class="paragraph"><p>The method is a case sensitive binary string. Standard
+methods include GET, HEAD, OPTIONS, PATCH, POST, PUT
+or DELETE.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_http_version">HTTP version</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The HTTP version is informational. It does not indicate that
+the client implements the protocol well or fully.</p></div>
+<div class="paragraph"><p>There is typically no need to change behavior based on the
+HTTP version: Cowboy already does it for you.</p></div>
+<div class="paragraph"><p>It can be useful in some cases, though. For example, one may
+want to redirect HTTP/1.1 clients to use Websocket, while HTTP/2
+clients keep using HTTP/2.</p></div>
+<div class="paragraph"><p>The HTTP version can be retrieved directly:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Host</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host</span></span>(<span style="color: #009900">Req</span>),
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:port</span></span>(<span style="color: #009900">Req</span>),
-<span style="color: #009900">Path</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The version used by the client can of course also be obtained.</p></div>
+<pre><tt>#{<span style="color: #FF6600">version</span> <span style="color: #990000">:=</span> <span style="color: #009900">Version</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Or using a function:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">Version</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:version</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Do note however that clients claiming to implement one version
-of the protocol does not mean they implement it fully, or even
-properly.</p></div>
+<div class="paragraph"><p>Cowboy defines the <code>'HTTP/1.0'</code>, <code>'HTTP/1.1'</code> and <code>'HTTP/2'</code>
+versions. Custom protocols can define their own values as
+atoms.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_bindings">Bindings</h2>
+<h2 id="_effective_request_uri">Effective request URI</h2>
<div class="sectionbody">
-<div class="paragraph"><p>After routing the request, bindings are available. Bindings
-are these parts of the host or path that you chose to extract
-when defining the routes of your application.</p></div>
-<div class="paragraph"><p>You can fetch a single binding. The value will be <code>undefined</code>
-if the binding doesn’t exist.</p></div>
+<div class="paragraph"><p>The scheme, host, port, path and query string components
+of the effective request URI can all be retrieved directly:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Binding</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">my_binding</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If you need a different value when the binding doesn’t exist,
-you can change the default.</p></div>
+<pre><tt>#{
+ <span style="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="color: #009900">Scheme</span>,
+ <span style="color: #FF6600">host</span> <span style="color: #990000">:=</span> <span style="color: #009900">Host</span>,
+ <span style="color: #FF6600">port</span> <span style="color: #990000">:=</span> <span style="color: #009900">Port</span>,
+ <span style="color: #FF6600">path</span> <span style="color: #990000">:=</span> <span style="color: #009900">Path</span>,
+ <span style="color: #FF6600">qs</span> <span style="color: #990000">:=</span> <span style="color: #009900">Qs</span>
+} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Or using the related functions:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Binding</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">my_binding</span>, <span style="color: #009900">Req</span>, <span style="color: #993399">42</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can also obtain all bindings in one call. They will be
-returned as a list of key/value tuples.</p></div>
+<pre><tt><span style="color: #009900">Scheme</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:scheme</span></span>(<span style="color: #009900">Req</span>),
+<span style="color: #009900">Host</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host</span></span>(<span style="color: #009900">Req</span>),
+<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:port</span></span>(<span style="color: #009900">Req</span>),
+<span style="color: #009900">Path</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span>
+<span style="color: #009900">Qs</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:qs</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The scheme and host are lowercased case insensitive binary
+strings. The port is an integer representing the port number.
+The path and query string are case sensitive binary strings.</p></div>
+<div class="paragraph"><p>Cowboy defines only the <a href="#http">[http]</a> and <a href="#https">[https]</a> schemes.
+They are chosen so that the scheme will only be <a href="#https">[https]</a>
+for requests on secure HTTP/1.1 or HTTP/2 connections.</p></div>
+<div class="paragraph"><p>The effective request URI itself can be reconstructed with
+the <code>cowboy_req:uri/1,2</code> function. By default, an absolute
+URI is returned:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">AllBindings</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:bindings</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If you used <code>...</code> at the beginning of the route’s pattern
-for the host, you can retrieve the matched part of the host.
-The value will be <code>undefined</code> otherwise.</p></div>
+<pre><tt><span style="font-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">scheme://host</span></span><span style="font-style: italic"><span style="color: #9A1900">[:port]/path[?qs]</span></span>
+<span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Options are available to either disable or replace some
+or all of the components. Various URIs or URI formats can
+be generated this way, including the origin form:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">HostInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Similarly, if you used <code>...</code> at the end of the route’s
-pattern for the path, you can retrieve the matched part,
-or get <code>undefined</code> otherwise.</p></div>
+<pre><tt><span style="font-style: italic"><span style="color: #9A1900">%% /path[?qs]</span></span>
+<span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The protocol relative form:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="font-style: italic"><span style="color: #9A1900">%% //host[:port]/path[?qs]</span></span>
+<span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The absolute URI without a query string:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>A different host:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"example.org"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>And any other combination.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_query_string">Query string</h2>
+<h2 id="_bindings">Bindings</h2>
<div class="sectionbody">
-<div class="paragraph"><p>The raw query string can be obtained directly.</p></div>
+<div class="paragraph"><p>Bindings are the host and path components that you chose
+to extract when defining the routes of your application.
+They are only available after the routing.</p></div>
+<div class="paragraph"><p>Cowboy provides functions to retrieve one or all bindings.</p></div>
+<div class="paragraph"><p>To retrieve a single value:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Qs</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:qs</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can parse the query string and then use standard library
-functions to access individual values.</p></div>
+<pre><tt><span style="color: #009900">Value</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">userid</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>When attempting to retrieve a value that was not bound,
+<code>undefined</code> will be returned. A different default value
+can be provided:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">QsVals</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_qs</span></span>(<span style="color: #009900">Req</span>),
-{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">QsVals</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can match the query string into a map.</p></div>
+<pre><tt><span style="color: #009900">Value</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">userid</span>, <span style="color: #009900">Req</span>, <span style="color: #993399">42</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>To retrieve everything that was bound:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can use constraints to validate the values while matching
-them. The following snippet will crash if the <code>id</code> value is
-not an integer number or if the <code>lang</code> value is empty. Additionally
-the <code>id</code> value will be converted to an integer term, saving
-you a conversion step.</p></div>
+<pre><tt><span style="color: #009900">Bindings</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:bindings</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>They are returned as a list of key/value pairs, with
+keys being atoms.</p></div>
+<div class="paragraph"><p>The Cowboy router also allows you to capture many host
+or path segments at once using the <code>...</code> qualifier.</p></div>
+<div class="paragraph"><p>To retrieve the segments captured from the host name:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">QsMap</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that in the case of duplicate query string keys, the map
-value will become a list of the different values.</p></div>
-<div class="paragraph"><p>Read more about <sup>constraints</sup>.</p></div>
-<div class="paragraph"><p>A default value can be provided. The default will be used
-if the <code>lang</code> key is not found. It will not be used if
-the key is found but has an empty value.</p></div>
+<pre><tt><span style="color: #009900">HostInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>And the path segments:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>#{<span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If no default is provided and the value is missing, the
-query string is deemed invalid and the process will crash.</p></div>
+<pre><tt><span style="color: #009900">PathInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Cowboy will return <code>undefined</code> if <code>...</code> was not used
+in the route.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_request_url">Request URL</h2>
+<h2 id="_query_parameters">Query parameters</h2>
<div class="sectionbody">
-<div class="paragraph"><p>You can reconstruct the full URL of the resource.</p></div>
+<div class="paragraph"><p>Cowboy provides two functions to access query parameters.
+You can use the first to get the entire list of parameters.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">URL</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:url</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can also obtain only the base of the URL, excluding the
-path and query string.</p></div>
+<pre><tt><span style="color: #009900">QsVals</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_qs</span></span>(<span style="color: #009900">Req</span>),
+{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">QsVals</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Cowboy will only parse the query string, and not do any
+transformation. This function may therefore return duplicates,
+or parameter names without an associated value. The order of
+the list returned is undefined.</p></div>
+<div class="paragraph"><p>When a query string is <code>key=1&key=2</code>, the list returned will
+contain two parameters of name <code>key</code>.</p></div>
+<div class="paragraph"><p>The same is true when trying to use the PHP-style suffix <code>[]</code>.
+When a query string is <code>key[]=1&key[]=2</code>, the list returned will
+contain two parameters of name <code>key[]</code>.</p></div>
+<div class="paragraph"><p>When a query string is simply <code>key</code>, Cowboy will return the
+list <code>[{<<"key">>, true}]</code>, using <code>true</code> to indicate that the
+parameter <code>key</code> was defined, but with no value.</p></div>
+<div class="paragraph"><p>The second function Cowboy provides allows you to match out
+only the parameters you are interested in, and at the same
+time do any post processing you require using <sup>constraints</sup>.
+This function returns a map.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">BaseURL</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host_url</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt>#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Constraints can be applied automatically. The following
+snippet will crash when the <code>id</code> parameter is not an integer,
+or when the <code>lang</code> parameter is empty. At the same time, the
+value for <code>id</code> will be converted to an integer term:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">QsMap</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>A default value may also be provided. The default will be used
+if the <code>lang</code> key is not found. It will not be used if
+the key is found but has an empty value.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>#{<span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>If no default is provided and the value is missing, the
+query string is deemed invalid and the process will crash.</p></div>
+<div class="paragraph"><p>When the query string is <code>key=1&key=2</code>, the value for <code>key</code>
+will be the list <code>[1, 2]</code>. Parameter names do not need to
+include the PHP-style suffix. Constraints may be used to
+ensure that only one value was passed through.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_headers">Headers</h2>
<div class="sectionbody">
-<div class="paragraph"><p>Cowboy allows you to obtain the header values as string,
+<div class="paragraph"><p>Header values can be retrieved either as a binary string
or parsed into a more meaningful representation.</p></div>
-<div class="paragraph"><p>This will get the string value of a header.</p></div>
+<div class="paragraph"><p>The get the raw value:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">HeaderVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can of course set a default in case the header is missing.</p></div>
+<div class="paragraph"><p>Cowboy expects all header names to be provided as lowercase
+binary strings. This is true for both requests and responses,
+regardless of the underlying protocol.</p></div>
+<div class="paragraph"><p>When the header is missing from the request, <code>undefined</code>
+will be returned. A different default can be provided:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">HeaderVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>And also obtain all headers.</p></div>
+<div class="paragraph"><p>All headers can be retrieved at once, either directly:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>#{<span style="color: #FF6600">headers</span> <span style="color: #990000">:=</span> <span style="color: #009900">AllHeaders</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Or using a function:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">AllHeaders</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:headers</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To parse the previous header, simply call <code>parse_header/{2,3}</code>
-where you would call <code>header/{2,3}</code> otherwise.</p></div>
+<div class="paragraph"><p>Cowboy provides equivalent functions to parse individual
+headers. There is no function to parse all headers at once.</p></div>
+<div class="paragraph"><p>To parse a specific header:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">ParsedVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy will crash if it doesn’t know how to parse the given
-header, or if the value is invalid.</p></div>
-<div class="paragraph"><p>You can of course define a default value. Note that the default
-value you specify here is the parsed value you’d like to get
-by default.</p></div>
+<div class="paragraph"><p>An exception will be thrown if it doesn’t know how to parse the
+given header, or if the value is invalid. The list of known headers
+and default values can be found in the manual.</p></div>
+<div class="paragraph"><p>When the header is missing, <code>undefined</code> is returned. You can
+change the default value. Note that it should be the parsed value
+directly:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
@@ -321,53 +450,30 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">ParsedVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>,
{<span style="color: #990000"><<</span><span style="color: #FF0000">"text"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"plain"</span><span style="color: #990000">>></span>, []})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The list of known headers and default values is defined in the
-manual.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_meta">Meta</h2>
+<h2 id="_peer">Peer</h2>
<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will sometimes associate some meta information with
-the request. Built-in meta values are listed in the manual
-for their respective modules.</p></div>
-<div class="paragraph"><p>This will get a meta value. The returned value will be <code>undefined</code>
-if it isn’t defined.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">MetaVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:meta</span></span>(<span style="color: #FF6600">websocket_version</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can change the default value if needed.</p></div>
+<div class="paragraph"><p>The peer address and port number for the connection can be
+retrieved either directly or using a function.</p></div>
+<div class="paragraph"><p>To retrieve the peer directly:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">MetaVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:meta</span></span>(<span style="color: #FF6600">websocket_version</span>, <span style="color: #009900">Req</span>, <span style="color: #993399">13</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can also define your own meta values. The name must be
-an <code>atom()</code>.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_meta</span></span>(<span style="color: #FF6600">the_answer</span>, <span style="color: #993399">42</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_peer">Peer</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can obtain the peer address and port number. This is
-not necessarily the actual IP and port of the client, but
-rather the one of the machine that connected to the server.</p></div>
+<pre><tt>#{<span style="color: #FF6600">peer</span> <span style="color: #990000">:=</span> {<span style="color: #009900">IP</span>, <span style="color: #009900">Port</span>}} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>And using a function:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>{<span style="color: #009900">IP</span>, <span style="color: #009900">Port</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:peer</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Note that the peer corresponds to the remote end of the
+connection to the server, which may or may not be the
+client itself. It may also be a proxy or a gateway.</p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/guide/req_body.asciidoc b/docs/en/cowboy/2.0/guide/req_body.asciidoc index d2a43d24..ccb5890e 100644 --- a/docs/en/cowboy/2.0/guide/req_body.asciidoc +++ b/docs/en/cowboy/2.0/guide/req_body.asciidoc @@ -1,152 +1,130 @@ [[req_body]] == Reading the request body -The Req object also allows you to read the request body. +The request body can be read using the Req object. -Because the request body can be of any size, all body -reading operations will only work once, as Cowboy will -not cache the result of these operations. +Cowboy will not attempt to read the body until requested. +You need to call the body reading functions in order to +retrieve it. -Cowboy will not attempt to read the body until you do. -If handler execution ends without reading it, Cowboy -will simply skip it. +Cowboy will not cache the body, it is therefore only +possible to read it once. -Cowboy provides different ways to read the request body. -You can read it directly, stream it, but also read and -parse in a single call for form urlencoded formats or -multipart. All of these except multipart are covered in -this chapter. Multipart is covered later on in the guide. +You are not required to read it, however. If a body is +present and was not read, Cowboy will either cancel or +skip its download, depending on the protocol. -=== Check for request body +Cowboy provides functions for reading the body raw, +and read and parse form urlencoded or ^multipart^ bodies. +The latter is covered in its own chapter. -You can check whether a body was sent with the request. +=== Request body presence + +Not all requests come with a body. You can check for +the presence of a request body with this function: [source,erlang] cowboy_req:has_body(Req). -It will return `true` if there is a request body, and -`false` otherwise. +It returns `true` if there is a body; `false` otherwise. -Note that it is generally safe to assume that a body is -sent for `POST`, `PUT` and `PATCH` requests, without -having to explicitly check for it. +In practice, this function is rarely used. When the +method is `POST`, `PUT` or `PATCH`, the request body +is often required by the application, which should +just attempt to read it directly. === Request body length -You can obtain the body length if it was sent with the -request. +You can obtain the length of the body: [source,erlang] Length = cowboy_req:body_length(Req). -The value returned will be `undefined` if the length -couldn't be figured out from the request headers. If -there's a body but no length is given, this means that -the chunked transfer-encoding was used. You can read -chunked bodies by using the stream functions. +Note that the length may not be known in advance. In +that case `undefined` will be returned. This can happen +with HTTP/1.1's chunked transfer-encoding, or HTTP/2 +when no content-length was provided. + +Cowboy will update the body length in the Req object +once the body has been read completely. A length will +always be returned when attempting to call this function +after reading the body completely. === Reading the body -You can read the whole body directly in one call. +You can read the entire body with one function call: [source,erlang] -{ok, Body, Req2} = cowboy_req:body(Req). +{ok, Data, Req} = cowboy_req:read_body(Req0). + +Cowboy returns an `ok` tuple when the body has been +read fully. -By default, Cowboy will attempt to read up to a -size of 8MB. You can override this limit as needed. +By default, Cowboy will attempt to read up to 8MB +of data, for up to 15 seconds. The call will return +once Cowboy has read at least 8MB of data, or at +the end of the 15 seconds period. + +These values can be customized. For example, to read +only up to 1MB for up to 5 seconds: [source,erlang] -{ok, Body, Req2} = cowboy_req:body(Req, [{length, 100000000}]). +---- +{ok, Data, Req} = cowboy_req:read_body(Req0, + #{length => 1000000, period => 5000}). +---- -You can also disable it. +You may also disable the length limit: [source,erlang] -{ok, Body, Req2} = cowboy_req:body(Req, [{length, infinity}]). +{ok, Data, Req} = cowboy_req:read_body(Req0, #{length => infinity}). -It is recommended that you do not disable it for public -facing websites. +This makes the function wait 15 seconds and return with +whatever arrived during that period. This is not +recommended for public facing applications. -If the body is larger than the limit, then Cowboy will return -a `more` tuple instead, allowing you to stream it if you -would like to. +These two options can effectively be used to control +the rate of transmission of the request body. === Streaming the body -You can stream the request body by chunks. - -Cowboy returns a `more` tuple when there is more body to -be read, and an `ok` tuple for the last chunk. This allows -you to loop over all chunks. +When the body is too large, the first call will return +a `more` tuple instead of `ok`. You can call the +function again to read more of the body, reading +it one chunk at a time. [source,erlang] ---- -body_to_console(Req) -> - case cowboy_req:body(Req) of - {ok, Data, Req2} -> +read_body_to_console(Req0) -> + case cowboy_req:read_body(Req0) of + {ok, Data, Req} -> io:format("~s", [Data]), - Req2; - {more, Data, Req2} -> + Req; + {more, Data, Req} -> io:format("~s", [Data]), - body_to_console(Req2) + read_body_to_console(Req) end. ---- -You can of course set the `length` option to configure the -size of chunks. - -=== Rate of data transmission - -You can control the rate of data transmission by setting -options when calling body functions. This applies not only -to the functions described in this chapter, but also to -the multipart functions. - -The `read_length` option defines the maximum amount of data -to be received from the socket at once, in bytes. - -The `read_timeout` option defines the time Cowboy waits -before that amount is received, in milliseconds. - -=== Transfer and content decoding - -Cowboy will by default decode the chunked transfer-encoding -if any. It will not decode any content-encoding by default. - -The first time you call a body function you can set the -`transfer_decode` and `content_decode` options. If the body -was already started being read these options are simply -ignored. - -The following example shows how to set both options. - -[source,erlang] ----- -{ok, Data, Req2} = cowboy_req:body(Req, [ - {transfer_decode, fun transfer_decode/2, TransferState}, - {content_decode, fun content_decode/1} -]). ----- +The `length` and `period` options can also be used. +They need to be passed for every call. === Reading a form urlencoded body -You can directly obtain a list of key/value pairs if the -body was sent using the application/x-www-form-urlencoded -content-type. - -[source,erlang] -{ok, KeyValues, Req2} = cowboy_req:body_qs(Req). - -You can then retrieve an individual value from that list. +Cowboy provides a convenient function for reading and +parsing bodies sent as application/x-www-form-urlencoded. [source,erlang] -{_, Lang} = lists:keyfind(lang, 1, KeyValues). +{ok, KeyValues, Req} = cowboy_req:read_urlencoded_body(Req0). -You should not attempt to match on the list as the order -of the values is undefined. +This function returns a list of key/values, exactly like +the function `cowboy_req:parse_qs/1`. -By default Cowboy will reject bodies with a size above -64KB when using this function. You can override this limit -by setting the `length` option. +The defaults for this function are different. Cowboy will +read for up to 64KB and up to 5 seconds. They can be modified: [source,erlang] -{ok, KeyValues, Req2} = cowboy_req:body_qs(Req, [{length, 2000000}]). +---- +{ok, KeyValues, Req} = cowboy_req:read_urlencoded_body(Req0, + #{length => 4096, period => 3000}). +---- diff --git a/docs/en/cowboy/2.0/guide/req_body/index.html b/docs/en/cowboy/2.0/guide/req_body/index.html index ac43be1d..2b0b2a49 100644 --- a/docs/en/cowboy/2.0/guide/req_body/index.html +++ b/docs/en/cowboy/2.0/guide/req_body/index.html @@ -69,174 +69,142 @@ <h1 class="lined-header"><span>Reading the request body</span></h1> -<div class="paragraph"><p>The Req object also allows you to read the request body.</p></div>
-<div class="paragraph"><p>Because the request body can be of any size, all body
-reading operations will only work once, as Cowboy will
-not cache the result of these operations.</p></div>
-<div class="paragraph"><p>Cowboy will not attempt to read the body until you do.
-If handler execution ends without reading it, Cowboy
-will simply skip it.</p></div>
-<div class="paragraph"><p>Cowboy provides different ways to read the request body.
-You can read it directly, stream it, but also read and
-parse in a single call for form urlencoded formats or
-multipart. All of these except multipart are covered in
-this chapter. Multipart is covered later on in the guide.</p></div>
+<div class="paragraph"><p>The request body can be read using the Req object.</p></div>
+<div class="paragraph"><p>Cowboy will not attempt to read the body until requested.
+You need to call the body reading functions in order to
+retrieve it.</p></div>
+<div class="paragraph"><p>Cowboy will not cache the body, it is therefore only
+possible to read it once.</p></div>
+<div class="paragraph"><p>You are not required to read it, however. If a body is
+present and was not read, Cowboy will either cancel or
+skip its download, depending on the protocol.</p></div>
+<div class="paragraph"><p>Cowboy provides functions for reading the body raw,
+and read and parse form urlencoded or <sup>multipart</sup> bodies.
+The latter is covered in its own chapter.</p></div>
<div class="sect1">
-<h2 id="_check_for_request_body">Check for request body</h2>
+<h2 id="_request_body_presence">Request body presence</h2>
<div class="sectionbody">
-<div class="paragraph"><p>You can check whether a body was sent with the request.</p></div>
+<div class="paragraph"><p>Not all requests come with a body. You can check for
+the presence of a request body with this function:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It will return <code>true</code> if there is a request body, and
-<code>false</code> otherwise.</p></div>
-<div class="paragraph"><p>Note that it is generally safe to assume that a body is
-sent for <code>POST</code>, <code>PUT</code> and <code>PATCH</code> requests, without
-having to explicitly check for it.</p></div>
+<div class="paragraph"><p>It returns <code>true</code> if there is a body; <code>false</code> otherwise.</p></div>
+<div class="paragraph"><p>In practice, this function is rarely used. When the
+method is <code>POST</code>, <code>PUT</code> or <code>PATCH</code>, the request body
+is often required by the application, which should
+just attempt to read it directly.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_request_body_length">Request body length</h2>
<div class="sectionbody">
-<div class="paragraph"><p>You can obtain the body length if it was sent with the
-request.</p></div>
+<div class="paragraph"><p>You can obtain the length of the body:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body_length</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The value returned will be <code>undefined</code> if the length
-couldn’t be figured out from the request headers. If
-there’s a body but no length is given, this means that
-the chunked transfer-encoding was used. You can read
-chunked bodies by using the stream functions.</p></div>
+<div class="paragraph"><p>Note that the length may not be known in advance. In
+that case <code>undefined</code> will be returned. This can happen
+with HTTP/1.1’s chunked transfer-encoding, or HTTP/2
+when no content-length was provided.</p></div>
+<div class="paragraph"><p>Cowboy will update the body length in the Req object
+once the body has been read completely. A length will
+always be returned when attempting to call this function
+after reading the body completely.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_reading_the_body">Reading the body</h2>
<div class="sectionbody">
-<div class="paragraph"><p>You can read the whole body directly in one call.</p></div>
+<div class="paragraph"><p>You can read the entire body with one function call:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>By default, Cowboy will attempt to read up to a
-size of 8MB. You can override this limit as needed.</p></div>
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Cowboy returns an <code>ok</code> tuple when the body has been
+read fully.</p></div>
+<div class="paragraph"><p>By default, Cowboy will attempt to read up to 8MB
+of data, for up to 15 seconds. The call will return
+once Cowboy has read at least 8MB of data, or at
+the end of the 15 seconds period.</p></div>
+<div class="paragraph"><p>These values can be customized. For example, to read
+only up to 1MB for up to 5 seconds:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body</span></span>(<span style="color: #009900">Req</span>, [{<span style="font-weight: bold"><span style="color: #000080">length</span></span>, <span style="color: #993399">100000000</span>}])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can also disable it.</p></div>
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>,
+ #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="color: #993399">5000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>You may also disable the length limit:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body</span></span>(<span style="color: #009900">Req</span>, [{<span style="font-weight: bold"><span style="color: #000080">length</span></span>, <span style="color: #FF6600">infinity</span>}])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It is recommended that you do not disable it for public
-facing websites.</p></div>
-<div class="paragraph"><p>If the body is larger than the limit, then Cowboy will return
-a <code>more</code> tuple instead, allowing you to stream it if you
-would like to.</p></div>
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #FF6600">infinity</span>})<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>This makes the function wait 15 seconds and return with
+whatever arrived during that period. This is not
+recommended for public facing applications.</p></div>
+<div class="paragraph"><p>These two options can effectively be used to control
+the rate of transmission of the request body.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_streaming_the_body">Streaming the body</h2>
<div class="sectionbody">
-<div class="paragraph"><p>You can stream the request body by chunks.</p></div>
-<div class="paragraph"><p>Cowboy returns a <code>more</code> tuple when there is more body to
-be read, and an <code>ok</code> tuple for the last chunk. This allows
-you to loop over all chunks.</p></div>
+<div class="paragraph"><p>When the body is too large, the first call will return
+a <code>more</code> tuple instead of <code>ok</code>. You can call the
+function again to read more of the body, reading
+it one chunk at a time.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">body_to_console</span></span>(<span style="color: #009900">Req</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body</span></span>(<span style="color: #009900">Req</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">-></span>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">read_body_to_console</span></span>(<span style="color: #009900">Req0</span>) <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
<span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s"</span>, [<span style="color: #009900">Data</span>]),
- <span style="color: #009900">Req2</span>;
- {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">-></span>
+ <span style="color: #009900">Req</span>;
+ {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
<span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s"</span>, [<span style="color: #009900">Data</span>]),
- <span style="font-weight: bold"><span style="color: #000000">body_to_console</span></span>(<span style="color: #009900">Req2</span>)
+ <span style="font-weight: bold"><span style="color: #000000">read_body_to_console</span></span>(<span style="color: #009900">Req</span>)
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can of course set the <code>length</code> option to configure the
-size of chunks.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rate_of_data_transmission">Rate of data transmission</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can control the rate of data transmission by setting
-options when calling body functions. This applies not only
-to the functions described in this chapter, but also to
-the multipart functions.</p></div>
-<div class="paragraph"><p>The <code>read_length</code> option defines the maximum amount of data
-to be received from the socket at once, in bytes.</p></div>
-<div class="paragraph"><p>The <code>read_timeout</code> option defines the time Cowboy waits
-before that amount is received, in milliseconds.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_transfer_and_content_decoding">Transfer and content decoding</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will by default decode the chunked transfer-encoding
-if any. It will not decode any content-encoding by default.</p></div>
-<div class="paragraph"><p>The first time you call a body function you can set the
-<code>transfer_decode</code> and <code>content_decode</code> options. If the body
-was already started being read these options are simply
-ignored.</p></div>
-<div class="paragraph"><p>The following example shows how to set both options.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body</span></span>(<span style="color: #009900">Req</span>, [
- {<span style="color: #FF6600">transfer_decode</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> <span style="font-weight: bold"><span style="color: #000000">transfer_decode</span></span><span style="color: #990000">/</span><span style="color: #993399">2</span>, <span style="color: #009900">TransferState</span>},
- {<span style="color: #FF6600">content_decode</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> <span style="font-weight: bold"><span style="color: #000000">content_decode</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>}
-])<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The <code>length</code> and <code>period</code> options can also be used.
+They need to be passed for every call.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_reading_a_form_urlencoded_body">Reading a form urlencoded body</h2>
<div class="sectionbody">
-<div class="paragraph"><p>You can directly obtain a list of key/value pairs if the
-body was sent using the application/x-www-form-urlencoded
-content-type.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body_qs</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can then retrieve an individual value from that list.</p></div>
+<div class="paragraph"><p>Cowboy provides a convenient function for reading and
+parsing bodies sent as application/x-www-form-urlencoded.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #FF6600">lang</span>, <span style="color: #993399">1</span>, <span style="color: #009900">KeyValues</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You should not attempt to match on the list as the order
-of the values is undefined.</p></div>
-<div class="paragraph"><p>By default Cowboy will reject bodies with a size above
-64KB when using this function. You can override this limit
-by setting the <code>length</code> option.</p></div>
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>This function returns a list of key/values, exactly like
+the function <code>cowboy_req:parse_qs/1</code>.</p></div>
+<div class="paragraph"><p>The defaults for this function are different. Cowboy will
+read for up to 64KB and up to 5 seconds. They can be modified:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body_qs</span></span>(<span style="color: #009900">Req</span>, [{<span style="font-weight: bold"><span style="color: #000080">length</span></span>, <span style="color: #993399">2000000</span>}])<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>,
+ #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">4096</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="color: #993399">3000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/guide/rest_handlers.asciidoc b/docs/en/cowboy/2.0/guide/rest_handlers.asciidoc index 6bff18d7..f28c0661 100644 --- a/docs/en/cowboy/2.0/guide/rest_handlers.asciidoc +++ b/docs/en/cowboy/2.0/guide/rest_handlers.asciidoc @@ -15,8 +15,8 @@ must return a `cowboy_rest` tuple. [source,erlang] ---- -init(Req, _Opts) -> - {cowboy_rest, Req, #state{}}. +init(Req, State) -> + {cowboy_rest, Req, State}. ---- Cowboy will then switch to the REST protocol and start executing diff --git a/docs/en/cowboy/2.0/guide/rest_handlers/index.html b/docs/en/cowboy/2.0/guide/rest_handlers/index.html index 15282e5f..36e87f9e 100644 --- a/docs/en/cowboy/2.0/guide/rest_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/rest_handlers/index.html @@ -84,8 +84,8 @@ must return a <code>cowboy_rest</code> tuple.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_rest</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}}<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">cowboy_rest</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>Cowboy will then switch to the REST protocol and start executing
the state machine.</p></div>
<div class="paragraph"><p>After reaching the end of the flowchart, the <code>terminate/3</code> callback
diff --git a/docs/en/cowboy/2.0/guide/routing.asciidoc b/docs/en/cowboy/2.0/guide/routing.asciidoc index 6ac2ebde..864a19a3 100644 --- a/docs/en/cowboy/2.0/guide/routing.asciidoc +++ b/docs/en/cowboy/2.0/guide/routing.asciidoc @@ -37,11 +37,11 @@ PathsList = [Path1, Path2, ... PathN]. Finally, each path contains matching rules for the path along with optional constraints, and gives us the handler module to be used -along with options that will be given to it on initialization. +along with its initial state. [source,erlang] -Path1 = {PathMatch, Handler, Opts}. -Path2 = {PathMatch, Constraints, Handler, Opts}. +Path1 = {PathMatch, Handler, InitialState}. +Path2 = {PathMatch, Constraints, Handler, InitialState}. Continue reading to learn more about the match syntax and the optional constraints. @@ -199,13 +199,13 @@ This can be done with a simple call to `cowboy_router:compile/1`. [source,erlang] ---- Dispatch = cowboy_router:compile([ - %% {HostMatch, list({PathMatch, Handler, Opts})} - {'_', [{'_', my_handler, []}]} + %% {HostMatch, list({PathMatch, Handler, InitialState})} + {'_', [{'_', my_handler, #{}}]} ]), %% Name, NbAcceptors, TransOpts, ProtoOpts -cowboy:start_http(my_http_listener, 100, +cowboy:start_clear(my_http_listener, 100, [{port, 8080}], - [{env, [{dispatch, Dispatch}]}] + #{env => #{dispatch => Dispatch}} ). ---- diff --git a/docs/en/cowboy/2.0/guide/routing/index.html b/docs/en/cowboy/2.0/guide/routing/index.html index 032d8214..01c5dd7d 100644 --- a/docs/en/cowboy/2.0/guide/routing/index.html +++ b/docs/en/cowboy/2.0/guide/routing/index.html @@ -107,14 +107,14 @@ http://www.gnu.org/software/src-highlite --> <pre><tt><span style="color: #009900">PathsList</span> <span style="color: #990000">=</span> [<span style="color: #009900">Path1</span>, <span style="color: #009900">Path2</span>, <span style="color: #990000">...</span> <span style="color: #009900">PathN</span>]<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>Finally, each path contains matching rules for the path along with
optional constraints, and gives us the handler module to be used
-along with options that will be given to it on initialization.</p></div>
+along with its initial state.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Path1</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">Opts</span>}<span style="color: #990000">.</span>
-<span style="color: #009900">Path2</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">Opts</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="color: #009900">Path1</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}<span style="color: #990000">.</span>
+<span style="color: #009900">Path2</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>Continue reading to learn more about the match syntax and the optional
constraints.</p></div>
</div>
@@ -297,13 +297,13 @@ by Lorenzo Bettini http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
- <span style="font-style: italic"><span style="color: #9A1900">%% {HostMatch, list({PathMatch, Handler, Opts})}</span></span>
- {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF6600">'_'</span>, <span style="color: #FF6600">my_handler</span>, []}]}
+ <span style="font-style: italic"><span style="color: #9A1900">%% {HostMatch, list({PathMatch, Handler, InitialState})}</span></span>
+ {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF6600">'_'</span>, <span style="color: #FF6600">my_handler</span>, #{}}]}
]),
<span style="font-style: italic"><span style="color: #9A1900">%% Name, NbAcceptors, TransOpts, ProtoOpts</span></span>
-<span style="font-weight: bold"><span style="color: #000000">cowboy:start_http</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #993399">100</span>,
+<span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #993399">100</span>,
[{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}],
- [{<span style="color: #FF6600">env</span>, [{<span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>}]}]
+ #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}}
)<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>Note that this function will return <code>{error, badarg}</code> if the structure
given is incorrect.</p></div>
diff --git a/docs/en/cowboy/2.0/guide/static_files.asciidoc b/docs/en/cowboy/2.0/guide/static_files.asciidoc index 39197a88..ef271198 100644 --- a/docs/en/cowboy/2.0/guide/static_files.asciidoc +++ b/docs/en/cowboy/2.0/guide/static_files.asciidoc @@ -124,8 +124,8 @@ a binary string is also allowed (but will require extra processing). If the function can't figure out the mimetype, then it should return `{<<"application">>, <<"octet-stream">>, []}`. -When the static handler fails to find the extension in the -list, it will send the file as `application/octet-stream`. +When the static handler fails to find the extension, +it will send the file as `application/octet-stream`. A browser receiving such file will attempt to download it directly to disk. diff --git a/docs/en/cowboy/2.0/guide/static_files/index.html b/docs/en/cowboy/2.0/guide/static_files/index.html index 6ef9d782..0edde8a3 100644 --- a/docs/en/cowboy/2.0/guide/static_files/index.html +++ b/docs/en/cowboy/2.0/guide/static_files/index.html @@ -195,8 +195,8 @@ is recommended to return the mimetype in tuple form, although a binary string is also allowed (but will require extra
processing). If the function can’t figure out the mimetype,
then it should return <code>{<<"application">>, <<"octet-stream">>, []}</code>.</p></div>
-<div class="paragraph"><p>When the static handler fails to find the extension in the
-list, it will send the file as <code>application/octet-stream</code>.
+<div class="paragraph"><p>When the static handler fails to find the extension,
+it will send the file as <code>application/octet-stream</code>.
A browser receiving such file will attempt to download it
directly to disk.</p></div>
<div class="paragraph"><p>Finally, the mimetype can be hard-coded for all files.
diff --git a/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc b/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc index 63fd52be..5332eec4 100644 --- a/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc +++ b/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc @@ -16,8 +16,8 @@ is handled by the sub protocol. [source,erlang] ---- -init(Req, _Opts) -> - {cowboy_websocket, Req, #state{}}. +init(Req, State) -> + {cowboy_websocket, Req, State}. ---- The return value may also have a `Timeout` value and/or the @@ -29,10 +29,12 @@ The following snippet switches to the `my_protocol` sub protocol, sets the timeout value to 5 seconds and enables hibernation: +// @todo Yeah maybe what we really need is an Opts map. + [source,erlang] ---- -init(Req, _Opts) -> - {my_protocol, Req, #state{}, 5000, hibernate}. +init(Req, State) -> + {my_protocol, Req, State, 5000, hibernate}. ---- If a sub protocol does not make use of these options, it should diff --git a/docs/en/cowboy/2.0/guide/sub_protocols/index.html b/docs/en/cowboy/2.0/guide/sub_protocols/index.html index c75da6a4..34f7db9b 100644 --- a/docs/en/cowboy/2.0/guide/sub_protocols/index.html +++ b/docs/en/cowboy/2.0/guide/sub_protocols/index.html @@ -85,8 +85,8 @@ is handled by the sub protocol.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}}<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>The return value may also have a <code>Timeout</code> value and/or the
atom <code>hibernate</code>. These options are useful for long living
connections. When they are not provided, the timeout value
@@ -99,8 +99,8 @@ hibernation:</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">my_protocol</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}, <span style="color: #993399">5000</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">my_protocol</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>If a sub protocol does not make use of these options, it should
crash if it receives anything other than the default values.</p></div>
</div>
diff --git a/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc b/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc index 9ddddf4c..b280fd86 100644 --- a/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc +++ b/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc @@ -18,8 +18,8 @@ must return a `ws` tuple. [source,erlang] ---- -init(Req, _Opts) -> - {cowboy_websocket, Req, #state{}}. +init(Req, State) -> + {cowboy_websocket, Req, State}. ---- Upon receiving this tuple, Cowboy will switch to the code @@ -34,18 +34,18 @@ the connection, assuming no correct subprotocol was found. [source,erlang] ---- -init(Req, _Opts) -> +init(Req, State) -> case cowboy_req:parse_header(<<"sec-websocket-protocol">>, Req) of undefined -> - {ok, Req, #state{}}; + {ok, Req, State}; Subprotocols -> case lists:keymember(<<"mychat2">>, 1, Subprotocols) of true -> Req2 = cowboy_req:set_resp_header(<<"sec-websocket-protocol">>, <<"mychat2">>, Req), - {ok, Req2, #state{}}; + {ok, Req2, State}; false -> - {stop, Req, undefined} + {stop, Req, State} end end. ---- @@ -60,12 +60,14 @@ It is also very easy to ensure that this message arrives before any message from other processes by sending it before registering or enabling timers. +// @todo This doesn't even work. + [source,erlang] ---- -init(Req, _Opts) -> +init(Req, State) -> self() ! post_init, %% Register process here... - {cowboy_websocket, Req, #state{}}. + {cowboy_websocket, Req, State}. websocket_info(post_init, Req, State) -> %% Perform post_init initialization here... @@ -169,8 +171,8 @@ A good timeout value is 60 seconds. [source,erlang] ---- -init(Req, _Opts) -> - {cowboy_websocket, Req, #state{}, 60000}. +init(Req, State) -> + {cowboy_websocket, Req, State, 60000}. ---- This value cannot be changed once it is set. It defaults to diff --git a/docs/en/cowboy/2.0/guide/ws_handlers/index.html b/docs/en/cowboy/2.0/guide/ws_handlers/index.html index 4bdd00d9..e8121220 100644 --- a/docs/en/cowboy/2.0/guide/ws_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/ws_handlers/index.html @@ -87,8 +87,8 @@ must return a <code>ws</code> tuple.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}}<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>Upon receiving this tuple, Cowboy will switch to the code
that handles Websocket connections and perform the handshake
immediately.</p></div>
@@ -102,18 +102,18 @@ the connection, assuming no correct subprotocol was found.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
<span style="color: #000080">undefined</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}};
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
<span style="color: #009900">Subprotocols</span> <span style="color: #990000">-></span>
<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">lists:keymember</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"mychat2"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">Subprotocols</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
<span style="color: #000080">true</span> <span style="color: #990000">-></span>
<span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>,
<span style="color: #990000"><<</span><span style="color: #FF0000">"mychat2"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req2</span>, <span style="color: #008080">#state</span>{}};
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req2</span>, <span style="color: #009900">State</span>};
<span style="color: #000080">false</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>}
+ {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>It is not recommended to wait too long inside the <code>init/2</code>
@@ -129,10 +129,10 @@ or enabling timers.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
<span style="font-weight: bold"><span style="color: #000080">self</span></span>() <span style="color: #990000">!</span> <span style="color: #FF6600">post_init</span>,
<span style="font-style: italic"><span style="color: #9A1900">%% Register process here...</span></span>
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}}<span style="color: #990000">.</span>
+ {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span>
<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #FF6600">post_init</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
<span style="font-style: italic"><span style="color: #9A1900">%% Perform post_init initialization here...</span></span>
@@ -238,8 +238,8 @@ leave the process alive forever.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">_Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #008080">#state</span>{}, <span style="color: #993399">60000</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #993399">60000</span>}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>This value cannot be changed once it is set. It defaults to
<code>infinity</code>.</p></div>
</div>
diff --git a/docs/en/erlang.mk/1/guide/app.asciidoc b/docs/en/erlang.mk/1/guide/app.asciidoc index 99ff0527..eef5d45e 100644 --- a/docs/en/erlang.mk/1/guide/app.asciidoc +++ b/docs/en/erlang.mk/1/guide/app.asciidoc @@ -126,6 +126,8 @@ your situation. Short description of the project. `PROJECT_VERSION`:: Current version of the project. +`PROJECT_MOD`:: + The application callback module. `PROJECT_REGISTERED`:: List of the names of all registered processes. `LOCAL_DEPS`:: diff --git a/docs/en/erlang.mk/1/guide/app/index.html b/docs/en/erlang.mk/1/guide/app/index.html index 7d2b36f8..619c7201 100644 --- a/docs/en/erlang.mk/1/guide/app/index.html +++ b/docs/en/erlang.mk/1/guide/app/index.html @@ -216,6 +216,14 @@ your situation.</p></div> </p>
</dd>
<dt class="hdlist1">
+<code>PROJECT_MOD</code>
+</dt>
+<dd>
+<p>
+ The application callback module.
+</p>
+</dd>
+<dt class="hdlist1">
<code>PROJECT_REGISTERED</code>
</dt>
<dd>
@@ -246,17 +254,7 @@ your situation.</p></div> <div class="paragraph"><p>There’s no need for quotes or anything. The relevant part of
the Cowboy Makefile follows, if you need an example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PROJECT =</span> cowboy
-<span style="color: #009900">PROJECT_DESCRIPTION =</span> Small<span style="color: #990000">,</span> fast<span style="color: #990000">,</span> modular HTTP server<span style="color: #990000">.</span>
-<span style="color: #009900">PROJECT_VERSION =</span> 2.0.0-pre.2
-<span style="color: #009900">PROJECT_REGISTERED =</span> cowboy_clock
-
-<span style="color: #009900">LOCAL_DEPS =</span> crypto
-<span style="color: #009900">DEPS =</span> cowlib ranch</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Any space before and after the value is dropped.</p></div>
<div class="paragraph"><p><a href="../deps">Dependencies</a> are covered in details in
the next chapter.</p></div>
@@ -439,33 +437,19 @@ the <a href="http://www.erlang.org/doc/man/erlc.html">erlc Manual</a> for the full list.</p></div>
<div class="paragraph"><p>By default, Erlang.mk will set the following options:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">ERLC_OPTS =</span> -Werror <span style="color: #990000">+</span>debug_info <span style="color: #990000">+</span>warn_export_vars <span style="color: #990000">+</span>warn_shadow_vars <span style="color: #990000">+</span>warn_obsolete_guard</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>In other words: warnings as errors, debug info (recommended) and
enable warnings for exported variables, shadow variables and
obsolete guard functions.</p></div>
<div class="paragraph"><p>You can redefine this variable in your Makefile to change it
completely, either before or after including Erlang.mk:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">ERLC_OPTS =</span> <span style="color: #990000">+</span>debug_info</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>You can also filter out some options from the defaults Erlang.mk
sets, by defining ERLC_OPTS after including Erlang.mk using the
<code>:=</code> operator.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>include erlang.mk
-
-<span style="color: #990000">ERLC_OPTS :=</span> <span style="color: #009900">$(</span>filter-out -Werror<span style="color: #990000">,</span><span style="color: #009900">$(ERLC_OPTS))</span></tt></pre></div></div>
+<div class="content"></div></div>
</div>
<div class="sect3">
<h4 id="_erlc_exclude">ERLC_EXCLUDE</h4>
@@ -475,11 +459,7 @@ not normally need it.</p></div> <div class="paragraph"><p>To exclude a module, simply list it in the variable, either
before or after including Erlang.mk:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">ERLC_EXCLUDE =</span> cowboy_http2</tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
</div>
@@ -525,11 +505,7 @@ when you have behaviors used by other modules in your project.</p></div> the dependency tracking file every time you compile. You can
do this by adding the following line to your <em>Makefile</em>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>NO_MAKEDEP <span style="color: #990000">?=</span> <span style="color: #993399">1</span></tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>As you can see, the snippet above uses <code>?=</code> instead of a
simple equal sign. This is to allow you to temporarily override
this value when you do make substantial changes to your project
@@ -559,18 +535,7 @@ file is generated. To do this, you would add your hook before or after including the <em>erlang.mk</em> file.</p></div>
<div class="paragraph"><p>The easiest way is after:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PROJECT =</span> example
-
-include erlang.mk
-
-<span style="color: #009900">$(PROJECT)</span>.d<span style="color: #990000">::</span> src/generated_mod.erl
-
-src/generated_mod.erl<span style="color: #990000">::</span> gen-mod.sh
- <span style="color: #009900">$(gen_verbose)</span> <span style="color: #990000">.</span>/gen-mod.sh <span style="color: #009900">$@</span></tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>In this case we use <code>$(gen_verbose)</code> to hide the details of
the build by default. Erlang.mk will simply say what file
is it currently generating.</p></div>
@@ -582,20 +547,7 @@ modified.</p></div> Erlang.mk, don’t forget to set the <code>.DEFAULT_GOAL</code> variable,
otherwise nothing will get built:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PROJECT =</span> example
-
-.DEFAULT_GOAL <span style="color: #990000">=</span> all
-
-<span style="color: #009900">$(PROJECT)</span>.d<span style="color: #990000">::</span> src/generated_mod.erl
-
-include erlang.mk
-
-src/generated_mod.erl<span style="color: #990000">::</span> gen-mod.sh
- <span style="color: #009900">$(gen_verbose)</span> <span style="color: #990000">.</span>/gen-mod.sh <span style="color: #009900">$@</span></tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
<div class="sect1">
diff --git a/docs/en/erlang.mk/1/guide/common_test/index.html b/docs/en/erlang.mk/1/guide/common_test/index.html index aae734f1..54cefcaf 100644 --- a/docs/en/erlang.mk/1/guide/common_test/index.html +++ b/docs/en/erlang.mk/1/guide/common_test/index.html @@ -90,11 +90,7 @@ options. Options are documented in the <a href="http://www.erlang.org/doc/apps/common_test/run_test_chapter.html">Common Test user guide</a>.
You can use it to set Common Test hooks, for example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">CT_OPTS =</span> -ct_hooks cowboy_ct_hook</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>The <code>CT_SUITES</code> variable can be used to override what
Common Test suites Erlang.mk will be aware of. It does
not normally need to be set as Erlang.mk will find the
@@ -103,11 +99,7 @@ test suites automatically.</p></div> If the file is named <em>http_SUITE.erl</em>, the test suite
is <code>http</code>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">CT_SUITES =</span> http ws</tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
<div class="sect1">
diff --git a/docs/en/erlang.mk/1/guide/compat/index.html b/docs/en/erlang.mk/1/guide/compat/index.html index 6202c6a2..cd68a9e6 100644 --- a/docs/en/erlang.mk/1/guide/compat/index.html +++ b/docs/en/erlang.mk/1/guide/compat/index.html @@ -125,11 +125,7 @@ issues.</p></div> your application, by making it a dependency of the <code>app</code>
target:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #990000">app::</span> rebar.config</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Don’t forget to commit the file when it changes!</p></div>
<div class="paragraph"><p>If you run into other issues, it’s probably because you use a
feature specific to Erlang.mk, like the <code>cp</code> fetch method.
diff --git a/docs/en/erlang.mk/1/guide/deps/index.html b/docs/en/erlang.mk/1/guide/deps/index.html index ad4a3523..780aaf56 100644 --- a/docs/en/erlang.mk/1/guide/deps/index.html +++ b/docs/en/erlang.mk/1/guide/deps/index.html @@ -109,11 +109,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Once you find the package you need, adding it as a dependency
to your project is a one-liner:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">DEPS =</span> cowboy</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>And that’s it! The next time you run <code>make</code>, Erlang.mk will
fetch and compile Cowboy. Erlang.mk will also ensure Cowboy
is available whenever you use the shell, run tests and any
@@ -128,20 +124,11 @@ dependencies.</p></div> <div class="paragraph"><p>For example, you could add a parse transform project like
this to make it available only at build time:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">BUILD_DEPS =</span> erlando</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Or you could depend on a C project directly, if you are
building a NIF:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">BUILD_DEPS =</span> leveldb
-<span style="color: #009900">dep_leveldb =</span> git https<span style="color: #990000">:</span>//github.com/basho/leveldb 2.1.3</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>This dependency will be built before your application, so
you could easily copy the resulting shared file into your
<em>priv/</em> directory as part of the build process. More information
@@ -155,43 +142,22 @@ Do note that there is no way to choose the version, the application used will be the one already on your system.</p></div>
<div class="paragraph"><p>You could depend on the Crypto application, for example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">LOCAL_DEPS =</span> crypto</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Erlang.mk comes with additional types of dependencies.
It has <code>TEST_DEPS</code> for dependencies used only for testing:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">TEST_DEPS =</span> ct_helper
-<span style="color: #009900">dep_ct_helper =</span> git https<span style="color: #990000">:</span>//github.com/ninenines/ct_helper master</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p><code>DOC_DEPS</code> for dependencies used only when building documentation:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">DOC_DEPS =</span> edown</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p><code>REL_DEPS</code> for dependencies required to build the release,
or to include extra applications in the release:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">REL_DEPS =</span> recon</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>And <code>SHELL_DEPS</code> for dependencies to make available when running
the <code>make shell</code> command:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">SHELL_DEPS =</span> tddreloader</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>All these will be documented in more details in their respective
chapters.</p></div>
<div class="sect3">
@@ -200,11 +166,7 @@ chapters.</p></div> find the project you are looking for, if you only provide
its name. This is this case:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">DEPS =</span> cowboy</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>If you need a different version, you need to define another
variable. There are two ways to do this, each being useful
for different reasons.</p></div>
@@ -212,12 +174,7 @@ for different reasons.</p></div> need to do is to define the <code>dep_$(DEP_NAME)_commit</code>
variable. In the case of Cowboy, this would look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">DEPS =</span> cowboy
-<span style="color: #009900">dep_cowboy_commit =</span> 2.0.0-pre.2</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Erlang.mk will use the package index to get all information
about Cowboy, except the commit number which will be overriden.</p></div>
<div class="paragraph"><p>If you need to set the fetch method or repository information
@@ -225,12 +182,7 @@ too, for example because you want to use your own fork, or simply because the project is missing from the index, you
can define the <code>dep_$(DEP_NAME)</code> variable with everything:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">DEPS =</span> cowboy
-<span style="color: #009900">dep_cowboy =</span> git https<span style="color: #990000">:</span>//github.com/essen/cowboy 2.0.0-pre.2</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>This will fetch Cowboy from your fork at the given commit.</p></div>
</div>
<div class="sect3">
@@ -304,61 +256,33 @@ You can use any valid commit, tag or branch in that repository for the commit value.</p></div>
<div class="paragraph"><p>For example, to fetch Cowboy with tag 2.0.0-pre.2 from Git:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">dep_cowboy =</span> git https<span style="color: #990000">:</span>//github.com/ninenines/cowboy 2.0.0-pre.2</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Or to fetch Ehsa tag 4.0.3 from Mercurial:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">dep_ehsa =</span> hg https<span style="color: #990000">:</span>//bitbucket.org/a12n/ehsa 4.0.3</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Git also comes with a concept of submodules. Erlang.mk can
automatically initializes and updates submodules for dependencies,
as long as they were added beforehand using <code>git submodule add</code>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">dep_cowboy =</span> git-submodule</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>The <code>svn</code> method only has a repository value, but that’s
simply because the SVN repository URL can also contain
the path and commit.</p></div>
<div class="paragraph"><p>This would fetch an example project from the trunk:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">dep_ex1 =</span> svn https<span style="color: #990000">:</span>//example.com/svn/trunk/project/ex<span style="color: #993399">1</span></tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>And this would fetch a separate example project from a
specific commit:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">dep_ex2 =</span> svn svn<span style="color: #990000">:</span>//example.com/svn/branches/erlang-proj/ex<span style="color: #993399">2</span>@<span style="color: #993399">264</span></tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>You can copy a directory from your machine using the <code>cp</code> method.
It only takes the path to copy from:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">dep_cowboy =</span> cp <span style="color: #009900">$(HOME)</span>/ninenines/cowboy</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Finally, you can use a package from the
<a href="https://hex.pm/">Hex repository</a>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">dep_cowboy =</span> hex 1.0.3</tt></pre></div></div>
+<div class="content"></div></div>
</div>
<div class="sect3">
<h4 id="_custom_fetch_methods">Custom fetch methods</h4>
@@ -371,14 +295,7 @@ Or in layman terms, if your dependency is Cowboy, this would become <em>deps/cowboy</em>.</p></div>
<div class="paragraph"><p>To give an example, this is what the Git method does:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>define dep_fetch_git
- git clone -q -n -- <span style="color: #009900">$(</span>call dep_repo<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">)</span> <span style="color: #009900">$(DEPS_DIR)</span><span style="color: #990000">/</span><span style="color: #009900">$(</span>call dep_name<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">);</span> <span style="color: #990000">\</span>
- cd <span style="color: #009900">$(DEPS_DIR)</span><span style="color: #990000">/</span><span style="color: #009900">$(</span>call dep_name<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">)</span> <span style="color: #990000">&&</span> git checkout -q <span style="color: #009900">$(</span>call dep_commit<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">);</span>
-endef</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Note that, like dependency information, this custom fetch method
must be written before including <em>erlang.mk</em>.</p></div>
</div>
@@ -452,20 +369,11 @@ on your system.</p></div> <div class="paragraph"><p>To ignore a dependency, simply add it to the <code>IGNORE_DEPS</code>
variable:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>IGNORE_DEPS <span style="color: #990000">+=</span> edown proper</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>This will only ignore dependencies that are needed for
building. It is therefore safe to write:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>IGNORE_DEPS <span style="color: #990000">+=</span> edown proper
-<span style="color: #009900">TEST_DEPS =</span> proper</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>The PropEr application will be fetched as intended when
running <code>make tests</code> or <code>make check</code>. It will however
not be fetched when running <code>make</code> or <code>make deps</code>.</p></div>
@@ -483,11 +391,7 @@ own dependencies.</p></div> if you know you will never use this project as a dependency,
<code>=</code> will work. But to avoid it biting you later on, do this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>DEPS_DIR <span style="color: #990000">?=</span> <span style="color: #009900">$(CURDIR)</span>/libs</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>The <code>$(CURDIR)</code> part is important, otherwise dependencies of
dependencies will be fetched in the wrong directory.</p></div>
<div class="paragraph"><p>Erlang.mk will also export the <code>REBAR_DEPS_DIR</code> variable for
@@ -656,19 +560,11 @@ Other projects with no Makefile are left untouched. <div class="paragraph"><p>You can disable the replacing of the <em>erlang.mk</em> file by
defining the <code>NO_AUTOPATCH_ERLANG_MK</code> variable:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">NO_AUTOPATCH_ERLANG_MK =</span> <span style="color: #993399">1</span></tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>You can also disable autopatch entirely for a few select
projects using the <code>NO_AUTOPATCH</code> variable:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">NO_AUTOPATCH =</span> cowboy ranch cowlib</tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
<div class="sect1">
diff --git a/docs/en/erlang.mk/1/guide/edoc/index.html b/docs/en/erlang.mk/1/guide/edoc/index.html index 97ab6018..49a8a4ee 100644 --- a/docs/en/erlang.mk/1/guide/edoc/index.html +++ b/docs/en/erlang.mk/1/guide/edoc/index.html @@ -87,12 +87,7 @@ EDoc options. Options are documented in the <div class="paragraph"><p>A common use for this variable is to enable Markdown in doc
comments, using the <code>edown</code> application:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">DOC_DEPS =</span> edown
-<span style="color: #009900">EDOC_OPTS =</span> {doclet<span style="color: #990000">,</span> edown_doclet}</tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
<div class="sect1">
@@ -119,11 +114,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>You can enable automatic generation on <code>make docs</code> by adding
the following to your Makefile:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #990000">docs::</span> edoc</tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
diff --git a/docs/en/erlang.mk/1/guide/eunit/index.html b/docs/en/erlang.mk/1/guide/eunit/index.html index b4d2ca59..a75d30d4 100644 --- a/docs/en/erlang.mk/1/guide/eunit/index.html +++ b/docs/en/erlang.mk/1/guide/eunit/index.html @@ -125,20 +125,12 @@ EUnit options. Options are documented in the <a href="http://www.erlang.org/doc/man/eunit.html#test-2">EUnit manual</a>.
At the time of writing, the only available option is <code>verbose</code>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">EUNIT_OPTS =</span> verbose</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>The <code>EUNIT_ERL_OPTS</code> variable allows you to specify options
to be passed to <code>erl</code> when running EUnit tests. For example,
you can load the <em>vm.args</em> and <em>sys.config</em> files:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">EUNIT_ERL_OPTS =</span> -args_file rel/vm.args -config rel/sys.config</tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
<div class="sect1">
diff --git a/docs/en/erlang.mk/1/guide/external_plugins/index.html b/docs/en/erlang.mk/1/guide/external_plugins/index.html index 8b52c986..cdc8f70b 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins/index.html @@ -90,12 +90,7 @@ of dependencies.</p></div> <div class="paragraph"><p>For example, if you have <code>cowboy</code> in <code>DEPS</code>, add <code>cowboy</code> in
<code>DEP_PLUGINS</code> also:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">DEPS =</span> cowboy
-<span style="color: #009900">DEP_PLUGINS =</span> cowboy</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>This will load the file <em>plugins.mk</em> in the root folder of
the Cowboy repository.</p></div>
</div>
@@ -113,12 +108,7 @@ writing <code>DEP_PLUGINS = cowboy/plugins.mk</code>.</p></div> from Cowboy and no other, we would write the following in
our Makefile:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">DEPS =</span> cowboy
-<span style="color: #009900">DEP_PLUGINS =</span> cowboy/mk/dist.mk</tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
<div class="sect1">
@@ -135,13 +125,7 @@ individual plugins in <em>plugins.mk</em>.</p></div> <em>mk/templates.mk</em>, you could write the following <em>plugins.mk</em>
file:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #990000">THIS :=</span> <span style="color: #009900">$(</span>dir <span style="color: #009900">$(</span>realpath <span style="color: #009900">$(</span>lastword <span style="color: #009900">$(MAKEFILE_LIST))))</span>
-include <span style="color: #009900">$(THIS)</span>/mk/dist.mk
-include <span style="color: #009900">$(THIS)</span>/mk/templates.mk</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>The <code>THIS</code> variable is required to relatively include files.</p></div>
<div class="paragraph"><p>This allows users to not only be able to select individual
plugins, but also select all plugins from the dependency
diff --git a/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc b/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc index fb98dbe4..317355e6 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc +++ b/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc @@ -51,3 +51,8 @@ http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html[Mix]. === reload.mk A https://github.com/bullno1/reload.mk[live reload plugin] for Erlang.mk. + +=== rust.mk + +A https://github.com/goertzenator/rust.mk[plugin] to build https://www.rust-lang.org/[Rust] crates and install binaries into `priv/`. + diff --git a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html index ef333210..c66915ec 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html @@ -137,6 +137,12 @@ to generate a compatible configuration file for <div class="paragraph"><p>A <a href="https://github.com/bullno1/reload.mk">live reload plugin</a> for Erlang.mk.</p></div>
</div>
</div>
+<div class="sect1">
+<h2 id="_rust_mk">rust.mk</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>A <a href="https://github.com/goertzenator/rust.mk">plugin</a> to build <a href="https://www.rust-lang.org/">Rust</a> crates and install binaries into <code>priv/</code>.</p></div>
+</div>
+</div>
diff --git a/docs/en/erlang.mk/1/guide/getting_started.asciidoc b/docs/en/erlang.mk/1/guide/getting_started.asciidoc index cdb3bfe0..3a7c0d10 100644 --- a/docs/en/erlang.mk/1/guide/getting_started.asciidoc +++ b/docs/en/erlang.mk/1/guide/getting_started.asciidoc @@ -27,14 +27,14 @@ in your Erlang distribution, or even in your OS packages. The next step is therefore to download it: [source,bash] -$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk +$ wget https://erlang.mk/erlang.mk Or: [source,bash] -$ curl https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk +$ curl https://erlang.mk/erlang.mk -o erlang.mk -Alternatively, just https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk[click on this link]. +Alternatively, just https://erlang.mk/erlang.mk[click on this link]. Make sure you put the file inside the folder we created previously. @@ -203,7 +203,7 @@ For a step by step: ---- $ mkdir hello_joe $ cd hello_joe -$ curl https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk +$ curl https://erlang.mk/erlang.mk -o erlang.mk $ echo "include erlang.mk" > Makefile $ make ---- diff --git a/docs/en/erlang.mk/1/guide/getting_started/index.html b/docs/en/erlang.mk/1/guide/getting_started/index.html index 67c402ef..049ce0a0 100644 --- a/docs/en/erlang.mk/1/guide/getting_started/index.html +++ b/docs/en/erlang.mk/1/guide/getting_started/index.html @@ -101,15 +101,15 @@ in your Erlang distribution, or even in your OS packages.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ wget https<span style="color: #990000">:</span>//raw<span style="color: #990000">.</span>githubusercontent<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk/master/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
+<pre><tt>$ wget https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
<div class="paragraph"><p>Or:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ curl https<span style="color: #990000">:</span>//raw<span style="color: #990000">.</span>githubusercontent<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk/master/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
-<div class="paragraph"><p>Alternatively, just <a href="https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk">click on this link</a>.</p></div>
+<pre><tt>$ curl https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk -o erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
+<div class="paragraph"><p>Alternatively, just <a href="https://erlang.mk/erlang.mk">click on this link</a>.</p></div>
<div class="paragraph"><p>Make sure you put the file inside the folder we created previously.</p></div>
</div>
</div>
@@ -282,11 +282,7 @@ manually.</p></div> create a folder, put Erlang.mk in it, and write a one line
Makefile containing:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>include erlang.mk</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>For a step by step:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
@@ -295,7 +291,7 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->
<pre><tt>$ mkdir hello_joe
$ cd hello_joe
-$ curl https<span style="color: #990000">:</span>//raw<span style="color: #990000">.</span>githubusercontent<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk/master/erlang<span style="color: #990000">.</span>mk
+$ curl https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk -o erlang<span style="color: #990000">.</span>mk
$ echo <span style="color: #FF0000">"include erlang.mk"</span> <span style="color: #990000">></span> Makefile
$ make</tt></pre></div></div>
<div class="paragraph"><p>From that point onward you can create an <code>src/</code> folder or start
diff --git a/docs/en/erlang.mk/1/guide/ports/index.html b/docs/en/erlang.mk/1/guide/ports/index.html index 8a9a9066..131751f8 100644 --- a/docs/en/erlang.mk/1/guide/ports/index.html +++ b/docs/en/erlang.mk/1/guide/ports/index.html @@ -82,20 +82,12 @@ It defaults to <em>c_src/</em>. Should you need to modify it, all you need to do is to set the variable in your Makefile before including
Erlang.mk:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">C_SRC_DIR =</span> <span style="color: #009900">$(CURDIR)</span>/my_nif_source</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>When this directory exists, Erlang.mk will automatically create a
file named <em>$(C_SRC_ENV)</em>. This file defaults to <em>$(C_SRC_DIR)/env.mk</em>.
This can also be changed:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">C_SRC_ENV =</span> <span style="color: #009900">$(C_SRC_DIR)</span>/erlang_env.mk</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>It contains a few variable definitions for the environment used for the build:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
@@ -137,11 +129,7 @@ it.</p></div> <div class="paragraph"><p>You can include the <em>env.mk</em> file to benefit from the Erlang
environment detection:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>include env.mk</tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
<div class="sect1">
@@ -154,11 +142,7 @@ executables, using the source files it finds in <em>$(C_SRC_DIR)</em>.</p></div> this and create an executable instead, put this in your Makefile
before including Erlang.mk:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">C_SRC_TYPE =</span> executable</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>The generated file name varies depending on the type of project
you have (shared library or executable) and on the platform you
build the project on.</p></div>
diff --git a/docs/en/erlang.mk/1/guide/releases/index.html b/docs/en/erlang.mk/1/guide/releases/index.html index 40022d86..cc0d3c45 100644 --- a/docs/en/erlang.mk/1/guide/releases/index.html +++ b/docs/en/erlang.mk/1/guide/releases/index.html @@ -80,11 +80,7 @@ file in the <em>$(RELX_CONFIG)</em> location. This defaults to <em>$(CURDIR)/relx.config</em>. You can override it by defining
the variable before including Erlang.mk:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">RELX_CONFIG =</span> <span style="color: #009900">$(CURDIR)</span>/webchat.config</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Relx does not need to be installed. Erlang.mk will download
and build it automatically.</p></div>
<div class="paragraph"><p>The Relx executable will be saved in the <em>$(RELX)</em> file. This
@@ -97,21 +93,13 @@ location defaults to <em>$(CURDIR)/relx</em> and can be overriden.</p></div> <div class="paragraph"><p>You can specify additional Relx options using the <code>RELX_OPTS</code>
variable. For example, to enable <code>dev_mode</code>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">RELX_OPTS =</span> -d <span style="font-weight: bold"><span style="color: #0000FF">true</span></span></tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>While you can specify the output directory for the release
in the Relx options directly, Erlang.mk provides a specific
variable for it: <code>RELX_OUTPUT_DIR</code>. It defaults to the <em>_rel</em>
directory. You can also override it:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">RELX_OUTPUT_DIR =</span> /path/to/staging/directory</tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
<div class="sect1">
diff --git a/docs/en/erlang.mk/1/guide/shell/index.html b/docs/en/erlang.mk/1/guide/shell/index.html index ed093c95..bdcbc854 100644 --- a/docs/en/erlang.mk/1/guide/shell/index.html +++ b/docs/en/erlang.mk/1/guide/shell/index.html @@ -78,11 +78,7 @@ with all the paths set properly to experiment with your code.</p></div> that are only to be used when the <code>make shell</code> command is called.
For example, if you want to use <em>kjell</em> as your shell:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">SHELL_DEPS =</span> kjell</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Dependencies are downloaded and compiled the first time you
run the <code>make shell</code> command.</p></div>
<div class="paragraph"><p>You can customize the executable used to start the Erlang shell.
@@ -90,26 +86,14 @@ To continue with our example, if you want to use <em>kjell</em> as your shell, you also need to change <code>SHELL_ERL</code> and point it to the
<code>kjell</code> executable:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">SHELL_ERL =</span> <span style="color: #009900">$(DEPS_DIR)</span>/kjell/bin/kjell</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>You can specify additional options to be used when starting the
shell using the <code>SHELL_OPTS</code> variable:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">SHELL_OPTS =</span> -setcookie chocolate</tt></pre></div></div>
+<div class="content"></div></div>
<div class="paragraph"><p>Any of the usual <code>erl</code> options can be used, including <code>-eval</code>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">SHELL_OPTS =</span> -eval <span style="color: #FF0000">'my_app:run()'</span></tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
<div class="sect1">
diff --git a/docs/en/gun/1.0/guide/protocols/index.html b/docs/en/gun/1.0/guide/protocols/index.html index ed694fce..cf7b7add 100644 --- a/docs/en/gun/1.0/guide/protocols/index.html +++ b/docs/en/gun/1.0/guide/protocols/index.html @@ -151,7 +151,6 @@ current protocol.</p></div> width="100%"
frame="border"
cellspacing="0" cellpadding="4">
-<caption class="title">Table 1. Supported operations per protocol</caption>
<col width="25%" />
<col width="25%" />
<col width="25%" />
@@ -263,7 +262,6 @@ cellspacing="0" cellpadding="4"> width="100%"
frame="border"
cellspacing="0" cellpadding="4">
-<caption class="title">Table 2. Messages sent per protocol</caption>
<col width="25%" />
<col width="25%" />
<col width="25%" />
diff --git a/docs/en/gun/1.0/guide/start/index.html b/docs/en/gun/1.0/guide/start/index.html index d8b8cc96..359a3bad 100644 --- a/docs/en/gun/1.0/guide/start/index.html +++ b/docs/en/gun/1.0/guide/start/index.html @@ -81,11 +81,7 @@ of downloading Gun and setting up paths.</p></div> in your Makefile.</p></div>
<div class="listingblock">
<div class="title">Adding Gun as an erlang.mk dependency</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">DEPS =</span> gun</tt></pre></div></div>
+<div class="content"></div></div>
</div>
</div>
<div class="sect1">
|